教程
如何通过 HiAPI API 调用 seedance-2.5-flash 文生视频(curl 与 Python)
面向开发者的可用请求演练:端点、参数、异步任务处理,以及可运行的 curl 和 Python 示例
本页内容
seedance-2.5-flash/text-to-video 能为你提供什么
seedance-2.5-flash/text-to-video 是 HiAPI API 上的一个文生视频生成端点。你发送一段描述目标场景的文本提示词,模型返回生成的视频。约定就是这么简单:输入文本,输出视频。
由于视频生成比典型的聊天补全耗时更长,这个端点是异步的。单次调用不会阻塞等待视频就绪,而是创建一个生成任务,你在任务进入终态后再获取结果。如果你之前集成过任何长时间运行的媒体 API,这种形态会很熟悉:提交、保存任务标识符,然后获取结果。
因此你这一侧的集成工作分为三件事:构造合法的提交请求、持久化任务 ID、可靠地获取完成的视频。本教程用可运行的 curl 和 Python 代码走完这三步,然后讲解参数校验、轮询与回调的取舍,以及大多数首次集成都会踩到的失败模式。
如果你正在构建以编程方式将提示词转换为短视频片段的流水线——内容工具、原型后端或内部生成服务——本指南适合你。如果你需要同步响应,或者你找的是图像生成而不是视频生成,那么另一个端点更合适。如果这符合你的用例,请继续阅读前置条件。
前置条件与获取 API Key
在发出第一个请求之前,请确认三件事。
HiAPI 账户与 API Key
对该端点的所有请求都使用与你的 HiAPI 账户绑定的 API Key 进行认证。请在账户控制面板中创建 Key,并避免将其提交到源码管理中。下面的示例从环境变量读取它,这样你可以直接粘贴到终端或脚本中,而无需内联编辑密钥:
export HIAPI_API_KEY="your_api_key_here"
一个能发起 HTTPS 请求的客户端
curl 部分你需要 curl,macOS 和大多数 Linux 发行版都自带。Python 部分你需要 Python 3 和 requests 库(pip install requests)。不需要厂商专用的 SDK——该端点是带 JSON 请求体的普通 HTTPS,因此任何 HTTP 客户端都可以使用,从 Node 的 fetch 到 Python 的 httpx。
一种在请求之间存储状态的方式
由于生成是异步的,你需要某个地方保存提交调用返回的任务标识符——数据库行、任务队列、测试期间的 JSON 文件。如果你打算用回调代替轮询,你还需要一个 HiAPI 可以访问的 HTTPS 端点。
有了 Key 和可用的客户端,你就可以提交请求了。
用 curl 发出第一个可用的请求
提交调用是一个带 JSON 请求体的 POST。确切的端点路径和认证头名称记录在模型页面上——请原样使用这些值,不要从其他 API 推断。调用的结构如下:
curl -X POST "$HIAPI_BASE_URL/v1/models/seedance-2.5-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
}'
关于各个部分有几点说明:
- 方法与路径。
POST创建一个新的生成任务。路径用于标识模型;在把它复制到你自己的配置之前,请对照模型页面确认。 - 请求头。
Authorization头携带你的 Key,Content-Type: application/json告诉服务器如何解析请求体。 - 请求体。至少需要发送一个
prompt字符串。提示词是创意输入——模型渲染的一切都来自它,因此要明确说明主体、运动、光照和镜头行为。
如果请求被接受,响应中会包含一个任务对象。你不会立即得到视频 URL。请从响应中提取任务标识符并保存。确切的字段名是模型页面上记录的响应模式的一部分;请将它们视为唯一事实来源,在看到真实的响应之前,不要将猜测硬编码到客户端中。
你可以先用 curl 检查原始响应,然后在理解其形态后将同样的调用移到代码中。
选择参数:提示词、分辨率和时长
只有 prompt 是严格必需的,但有几个可选参数会决定输出结果和请求成本。请有意识地设置它们,而不是盲目接受默认值。
提示词
提示词是影响最大的参数。像给摄像师做简报一样撰写:主体、动作、环境、光照和镜头风格。"A cyclist weaving through a neon-lit Tokyo street at night, handheld camera, shallow depth of field" 比 "a city" 给模型提供了多得多的信息。请将提示词控制在模型页面上记录的长度限制之内。
分辨率
更高的分辨率意味着更多细节和更大的输出文件,生成时间也可能更长。视频生成通常按输出时长计费,但请根据价格面板和模型文档确认当前的计费依据和任何分辨率档位,而不要自行假设。选择满足交付目标的最低分辨率——后期放大通常比全部以最高质量生成更便宜。
时长
时长控制模型生成多少秒的视频,通常同时影响延迟和成本。较短的片段更适合迭代:在较短时长下打磨提示词,直到运动看起来正确,然后以最终长度重新生成。
发送前校验
在将值接入生产代码之前,请查看模型页面了解每个参数的允许范围——允许的时长、支持的分辨率以及任何枚举值。然后在客户端进行校验:在请求离开你的进程之前,拒绝超出范围的时长和未知的分辨率值。这样可以将一类服务端校验错误转化为你自己日志中即时、低成本的失败。
同样的规则适用于参数名称。请从文档中复制它们;像时长字段中多出一个下划线这样的拼写错误通常会被拒绝或被静默忽略,而静默忽略是更难发现的 bug。
用 Python 发出同样的请求
以下是 Python 中的等价提交代码。它从环境变量读取 Key,发送 JSON 请求体,检查状态码,并从文档记录的响应字段中返回任务标识符。
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_video(prompt: str, **options) -> str:
payload = {
"prompt": prompt,
**options, # e.g. resolution="720p", duration=5
}
response = requests.post(
f"{BASE_URL}/v1/models/seedance-2.5-flash/text-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
body = response.json()
task_id = body["id"] # confirm the field name on the model page
return task_id
if __name__ == "__main__":
task_id = submit_video(
"A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
)
print("submitted task:", task_id)
这段代码中有几个有意的选择:
- 超时。提交调用应该快速返回,但显式的
timeout可以防止挂起的套接字阻塞你的工作进程。 raise_for_status()。遇到 HTTP 错误时立即失败,而不是把错误响应体当作成功响应来解析。- 关键字选项。传入
**options可以让调用点保持可读,并且在你确认了模型页面上的确切名称后,添加resolution或duration变得非常简单。 - 返回 ID。函数的职责在提交时结束。请将该 ID 持久化到某个持久存储中——下一节将用它来获取结果。
在真实的流水线中,请将 submit_video 视为队列驱动工作流中的一个步骤:将其入队,将返回的任务 ID 与你的任务记录一起保存,并让一个独立的工作进程负责获取结果。
处理异步结果:轮询与回调
提交之后你有一个任务 ID,但还没有视频。有两种方式弥合这个差距。
轮询
按固定间隔轮询任务状态端点,直到任务进入终态,然后从完成的响应中获取输出 URL。
import time
import requests
def wait_for_video(task_id: str, timeout_s: int = 600) -> dict:
deadline = time.time() + timeout_s
delay = 2.0
while time.time() < deadline:
response = requests.get(
f"{BASE_URL}/v1/tasks/{task_id}", # confirm path on the model page
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
task = response.json()
state = task["status"]
if state == "completed":
return task
if state == "failed":
raise RuntimeError(task.get("error", "generation failed"))
time.sleep(delay)
delay = min(delay * 1.5, 15) # gentle backoff, capped
raise TimeoutError(f"task {task_id} did not finish in time")
轮询的三条实用规则:
- 退避。从较短的延迟开始并逐渐增加。持续高频率轮询会浪费配额并增加负载,却没有任何好处。
- 设置上限。每个轮询循环都需要一个截止时间。视频生成可能需要一段时间,但无界的循环最终会因为某个卡住的任务让你的工作进程永远挂起。
- 区分状态。显式处理
failed,这样糟糕的提示词就不会被静默地当成超时。
回调
如果你注册一个 HTTPS 回调 URL,HiAPI 可以在任务完成时通知你,从而完全避免轮询。两条规则让回调安全可靠:
- 先验证再信任。在通过平台文档记录的机制验证其签名或来源之前,将回调视为未经认证的输入。
- 保持幂等。回调可能会被多次投递。以任务 ID 作为处理器的键,并将重复投递的处理设为无操作——只存储一次结果,对重复投递予以确认。
无论选择哪种方式,结果获取都是幂等的:为已完成的任务获取结果 URL 应该返回相同的视频,因此网络错误后的重试是安全的。
常见错误及其修复方法
大多数失败都归结为少数几类。在假设存在未记录的行为之前,请先逐项排查这份清单。
认证失败
401 或 403 几乎总是意味着 Key 缺失、格式错误或已过期。检查 Authorization 头是否存在、认证方案是否与文档完全一致,以及环境变量是否确实包含 Key——空字符串会产生一个令人困惑但与认证相关的失败。
校验被拒绝
带有校验消息的 4xx 意味着服务器拒绝了你的参数。重新阅读模型页面上的允许范围,并逐字符确认参数名称。如果时长或分辨率超出范围,修复方法是之前所述的客户端校验——在你自己的代码中快速失败,而不是往返服务器。
任务卡在非终态
如果轮询始终看不到 completed 或 failed,任务可能仍在运行,或者你的轮询循环查询了错误的任务 ID。记录你提交的 ID 和轮询的 ID 并进行比较。你的循环还应强制执行截止时间;当截止时间触发时,应暴露任务 ID,而不是盲目重试。
回调之后结果没有到达
如果你依赖回调,请检查你的端点是否可通过 HTTPS 公开访问、是否快速返回成功状态而不是内联执行繁重工作,以及重复投递是否以幂等方式处理。如果回调处理器在同一个任务的第二次投递时报错,看起来就会像结果丢失了。
重复提交同一作业
如果你的工作进程在超时后重试提交调用,可能会创建重复任务。在调用端点之前,先在你自己的数据库中记录一个客户端请求键或作业 ID,并在重试前检查它,从而使提交在你这一侧保持幂等。
一般原则:当出现失败时,先阅读错误响应体和模型文档,然后再修改代码。如果某个值或字段没有被记录,请避免假设它存在——对照模型页面进行验证,并相应地调整请求。