教程
如何调用 seedance-2.5 图生视频 API:可用的 curl 与 Python 示例
本页内容
seedance-2.5 图生视频端点能为你提供什么
seedance-2.5 图生视频是 HiAPI 上的一个异步模型端点,可将一张或两张静态图片转换成一段短视频。你向它发送一张图片(或一对分别作为运动起止点的图片),描述期望发生的变化,平台会返回一个任务,当生成完成时该任务会解析为一个视频文件 URL。
在典型的视频生成技术栈中,该端点处于“让静态图动起来”这一层。你已经有源图片——产品图、角色渲染图、分镜帧——你需要的是动效,而非一张新图片。由于调用是异步的,你的工作是提交任务、保留任务标识符,并持续轮询直到结果就绪。这种先提交再轮询的模式在 HiAPI 的长时间运行生成端点中通用,因此你在此处编写的客户端可以迁移到其他模型。
该端点还提供原生音频选项,如果你的处理流程需要一个带声音的视频片段,而不是一个之后才配乐的无声素材,这一点很重要。如果你需要精确到帧的运镜或可循环的动效,那么使用明确的首帧和尾帧进行图生视频,通常是在不搭建 3D 场景的情况下最具可控性的选择。
前提条件与身份认证
在首次调用前,请准备好三样东西。
1. 一个 HiAPI API 密钥
每个请求都使用你的密钥进行认证,以 bearer token 形式放在 Authorization 请求头中发送。请勿将其提交到源码管理中——从环境变量读取它,这样同一脚本既能在本地运行,也能在 CI 中运行。
export HIAPI_API_KEY="your_key_here"
2. API 可获取的源图片
图片输入是 URL。请将图片托管在服务可访问的位置——带签名 URL 的对象存储、CDN 或任何公共 HTTPS 地址。如果你不希望公开暴露图片,请生成一个短时效的签名 URL,而不是将存储桶设为公开。
对于首帧/尾帧工作流,你需要一张图片(仅首帧)或两张图片(首帧和尾帧)。
3. 一个 HTTP 客户端
任何能发送 JSON 的工具都可以:curl 用于快速冒烟测试,Python 中的 requests 或 httpx,Node 中的 fetch。你不需要特殊的 SDK。
该模型的具体基础 URL、路径和字段名位于 HiAPI 控制台的模型页面上;请在下方示例中逐字使用这些值。一旦你有了密钥和图片 URL,就可以提交了。
首帧输入与尾帧输入
两个图片输入控制视频片段的不同端点,选择哪一个会改变你对动效的控制程度。
仅首帧。 你提供一张图片,模型从它向前生成。当你希望模型自行创造动效时,这是正确选择:缓慢转身的肖像、旋转的产品、云朵飘动的风景。你放弃了对片段结束位置的确定性,但获得了更大的创作空间,并且只需要一个素材。
首帧和尾帧。 你提供两张图片,模型在它们之间生成路径。当端点很重要时,这是正确选择:拼合成最终组合标志的 logo、从姿势 A 移动到姿势 B 的角色、从画面左侧滑到右侧的物体。提供尾帧会约束运动,这通常意味着更少意外,并且如果你计划重复播放该片段,还能获得更好的可循环性。
一条实用规则:如果你能将片段描述为“这张图片发生了某些变化”,就只使用首帧。如果你能将其描述为“这张图片变成那张图片”,就提供两张。提供两张时,请保持两张图片在构图、宽高比和光照上一致——不匹配的图片对会迫使模型处理一个看起来像故障的跳跃。
你的提示词应补充图片,而不是与它们冲突。描述运动,而不是模型已经能看到的静态内容。
使用 curl 提交第一个请求
以下请求提交一个图生视频任务。请用 HiAPI 控制台中 seedance-2.5 图生视频模型页面上显示的值替换端点路径、模型标识符和字段名,并换入你自己的图片 URL。
curl -X POST "$HIAPI_BASE_URL/<image-to-video-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5/image-to-video",
"prompt": "The camera slowly pushes in as the subject turns toward the light",
"first_frame_image": "https://your-cdn.example.com/frame-01.jpg",
"last_frame_image": "https://your-cdn.example.com/frame-02.jpg"
}'
关于请求结构,有几点需要注意:
prompt描述运动。保持简短具体;大量形容词列表往往会稀释指令。first_frame_image对于图生视频是必需的。last_frame_image是可选的——仅首帧生成时完全去掉该字段。- 如果需要音频选项,它们是同一 JSON 正文中的额外字段(下文会介绍)。
响应是一个包含标识符和状态的任务对象。保存该标识符;每次轮询都需要它。如果调用返回的是认证或校验错误,请先检查请求头和图片 URL,再重试。
Python 中的相同请求
以下是 Python 中的等效提交代码,已重构为便于捕获任务标识符的形式。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<image-to-video-path>"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(first_frame, last_frame=None, prompt="", audio=False):
payload = {
"model": "seedance-2.5/image-to-video",
"prompt": prompt,
"first_frame_image": first_frame,
}
if last_frame:
payload["last_frame_image"] = last_frame
if audio:
payload["audio"] = True
resp = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
resp.raise_for_status()
data = resp.json()
return data["task_id"], data
task_id, raw = submit_video(
first_frame="https://your-cdn.example.com/frame-01.jpg",
last_frame="https://your-cdn.example.com/frame-02.jpg",
prompt="The camera slowly pushes in as the subject turns toward the light",
)
print(task_id)
有两个值得尽早养成的习惯。第一,在提交调用上设置显式的 timeout——挂起的请求应该快速失败,而不是阻塞你的 worker。第二,开发期间保留原始响应。保存任务标识符的字段可能因端点版本不同而与 task_id 不同,打印一次原始 JSON 可以省去一轮调试。
轮询异步任务直到视频就绪
图生视频生成所需的时间超过一个 HTTP 请求应保持打开的时间,因此平台采用先提交再轮询的生命周期。提交会返回任务标识符;然后你定期查询任务端点,直到其状态达到终止状态。
import time
import requests
def wait_for_video(task_id, interval=5, max_wait=600):
url = f"{BASE_URL}/<task-path>/{task_id}"
deadline = time.time() + max_wait
while time.time() < deadline:
resp = requests.get(url, headers=HEADERS, timeout=30)
resp.raise_for_status()
task = resp.json()
status = task.get("status")
if status == "succeeded":
return task["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"Task {task_id} ended as {status}: {task.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} not ready after {max_wait}s")
围绕四条规则来设计轮询:
- 以适中的间隔轮询。 五秒是合理的默认值。猛击端点并不会让视频渲染得更快。
- 始终设置截止时间。 任务可能失败或排队时间超过预期;无界循环会把暂时性问题变成卡死的 worker。
- 将
failed和cancelled视为终止状态。 暴露错误字段,而不是永远重试同一任务。 - 持续轮询时使用退避。 如果同时轮询许多任务,请逐渐增大间隔以避免突发流量。
在生产环境中,请从后台 worker 或队列中轮询,而不是在 Web 请求处理器内部轮询。结果是视频 URL;请及时下载并复制到你自己的存储中,因为生成的资源 URL 通常不是永久性的。
处理原生音频标志
seedance-2.5 可以生成带原生音频的片段,该控制项是与图片输入和提示词并列的请求字段——而不是单独端点。确切的字段名和可接受值列在模型页面上;上面的 Python 辅助函数通过传入 audio 布尔值进行示例说明。
是否启用取决于片段的消费方式。
在以下情况请求音频: 输出直接面向受众——社交帖子、预览、演示——并且你希望片段无需二次剪辑就感觉完整。原生音频还能帮助审阅者判断节奏,因为声音让运动时序更易读。
在以下情况跳过音频: 你的处理流程会叠加自己的配乐、片段要送入合成或编辑工具,或者你计划生成许多变体而只为最终选中的版本配乐。无声生成保持素材中性,并避免后续的同步问题。
关于缩小范围的一条实用说明:将音频视为每次请求的决策,而不是全局设置。如上所示,一个接受 audio 标志的单一辅助函数,可以让同一代码路径同时服务于无声后台批处理和精致的最终渲染。
如果标志存在但结果无声,请先确认该值按预期序列化——字符串 "true" 与布尔值 true 是常见的不匹配——再假设模型忽略了它。
常见失败点与后续步骤
大多数首次集成问题可归入四类。
服务无法获取的输入
在你的浏览器中可用的 URL 可能在服务端失败:私有存储桶、过期链接或阻止非浏览器用户代理的主机。请使用生命周期足以覆盖整个生成过程的签名 URL,并确认图片能从你网络之外的机器加载。
不匹配的帧
当首帧和尾帧在宽高比、裁剪或色温上不同时,模型必须调和这种跳跃。提交前,请将该图片对预处理为相同尺寸和相近的调色。
错误的字段名或模型标识符
此处的示例使用模型页面上的请求结构;请从控制台逐字复制字段名和模型字符串,而不是凭记忆或旧片段。字段名中的拼写错误往往会被静默忽略,而不是被拒绝。
永不终止的轮询
如果你的循环反复超时,请记录你观察到的每个状态值。看到意外的状态字符串通常能解释停滞——你的终止状态检查可能只是与 API 返回的内容不匹配。
一旦单个片段端到端跑通,自然的后续步骤是通过同一提交并轮询的辅助函数批量处理多张图片、在提交周围添加带退避的重试,并将结果写入持久存储。你可以在 seedance-2.5 图生视频模型页面上找到端点详情、请求字段和参数参考,并据此将上述代码适配到你自己的图片。