教程
seedance-2.5-flash 图生视频 API 教程:curl 与 Python Requests
面向开发者的实用集成演练:请求结构、首帧/尾帧输入、异步轮询和错误排查
本页内容
图生视频调用实际做了什么
在写第一行代码之前,先了解 API 在另一端做了什么会很有帮助。seedance-2.5-flash/image-to-video 调用并不是一个阻塞到视频文件返回的同步请求。它是一个两阶段、异步的工作流:你先提交任务,然后轮询其结果。
提交阶段
你发送一个 POST 请求,携带输入图像和生成设置。API 校验请求体,将任务入队,并立即返回一个包含任务标识符和初始状态的响应。这个过程很快——通常只是一瞬间——因为此时还没有渲染任何像素。你的任务是捕获该标识符并妥善保存。
渲染阶段
生成在后台进行。根据片段长度和设置的不同,这可能要花费相当可观的实际时间。在这个窗口期内,不要期望最终视频 URL 已经可用。相反,你应该查询任务的状态。
结果阶段
最终任务会到达终止状态:成功,并带有一个可下载的视频产物;或者失败,并带有一个可供排查的错误。一旦到达终止状态,就应停止轮询。
为什么这对你的代码很重要
因为模型是异步的,最常见的集成错误是架构性的,而不是语法性的:假设第一个响应就包含视频、以固定间隔休眠而不是轮询状态字段、以及未能区分瞬时的 processing 状态与永久性失败。本教程的所有内容都围绕一个干净的“提交 → 轮询 → 退出”循环展开,所以在阅读过程中请牢记这三个阶段。
前置条件与请求结构
首次调用前需要准备什么
- API 凭证。 你的 HiAPI API 密钥,随每个请求发送。请将其保存在环境变量(
HIAPI_API_KEY)中,而不是源代码管理中——下面的示例就是这样读取的。 - 模型标识符。 本教程中该字符串是固定的:
seedance-2.5-flash/image-to-video。将其视为不透明常量;不要用各部分拼接它。 - 源图像。 一个公开 URL 或受支持的内联图像引用。模型至少需要一张首帧图像。
- HTTP 客户端。 用于冒烟测试的
curl,以及用于任何你打算保留的内容的requests。
请求体的逻辑字段
无论使用哪种语言,图生视频请求体都由几个概念组构成。分别了解它们可以让 JSON 更容易理解:
模型与输入
- 模型标识符。
- 一个输入对象,包含首帧图像,以及可选的尾帧图像。第 4 章介绍它们如何相互作用。
输出设置
- 与分辨率和时长相关的开关。
- 原生音频开关,它决定生成的片段是否带有伴随音轨。第 5 章将介绍何时开启它。
返回什么
成功提交会返回一个任务对象。你实际需要的字段是任务标识符和当前状态。其他一切都是你可以记录或忽略的元数据。第一天不要把整个响应解析成类型化模型——先记录、检查,然后再收窄。
继续之前做一个快速现实检查:如果你的请求体包含任何你无法用一句话解释其名称的字段,就删除它并从最小化开始。seedance-2.5-flash/image-to-video 的模型页面是确切接受字段名的参考。
用 curl 提交任务
从可能生效的最小请求开始,然后一次添加一个字段。以下是用 curl 进行的最小提交:
curl -X POST "$HIAPI_BASE_URL/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/image-to-video",
"input": {
"first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
}
}'
逐个字段注释
Authorization—— 你的 API 密钥,作为 bearer token。如果这里出错,你会在任何校验运行之前收到认证错误,所以调试时先检查它。Content-Type: application/json—— 必需;省略它会产生令人困惑的下游错误。model—— 固定的模型标识符。这里拼错会得到 4xx,而不是静默回退。input.first_frame_image—— 片段的开场图像。使用你的网络实际可访问的 URL;私有或过期的 URL 会在获取时失败,而不是在提交时失败。
读取响应
响应是包含任务标识符和状态的 JSON。立即保存标识符——这就是你将在第 7 章轮询的内容。在 shell 中提取它的快速方法:
# 在上面的 curl 之后,通过 jq 管道处理
# {"job_id": "...", "status": "queued"}
添加尾帧
要同时控制结束帧,请在同一个 input 对象内添加第二张图像。字段名和接受的格式以模型文档为准——不要猜测替代拼写;API 会拒绝未知键,而不是忽略它们。
一旦最小请求生效,你就有了一个冒烟测试,可以在出现问题时重新运行。把它保存在文件中;当服务在凌晨两点出问题时,它比任何长篇大论都更有价值。
首帧与尾帧输入
输入图像是任务能否成功的最大决定因素。它们塑造片段的内容,同时也是请求被拒绝的最常见来源。
首帧控制什么
首帧图像设定生成片段的开场状态:构图、主体、光照和色彩。模型从该起点生成运动和延续,因此图像应该看起来像你真正希望在时间零点出现的一帧。模糊、裁剪或高度压缩的源图像不会神奇地在后续环节变好。
尾帧控制什么
提供尾帧图像可以固定结束状态。当片段必须落在特定镜头上时——产品美图帧、logo 揭示、剪辑中的匹配切换——这很有用。省略时,模型自行选择结尾,这对探索性工作没问题,但对生产来说不可预测。
两者如何相互作用
当两者都提供时,模型在它们之间插值。这有实际后果:
- 连续性胜过对比。 同一场景中运动幅度适中的两帧,比两张不相关的图像产生更连贯的片段。如果帧差异极大,预计会出现可见的变形,而不是合理的过渡。
- 宽高比应匹配。 首帧和尾帧之间不匹配的宽高比会迫使模型进行尴尬的重新构图。提交前将两者裁剪到相同比例。
- 分辨率应相当。 发送清晰的首帧和低分辨率的尾帧会给模型相互矛盾的信号。
提交前检查清单
在发送之前,请验证:两个图像 URL 都可公开访问,且不会在任务中途过期;两者都是受支持的格式;两者宽高比相同;两者都不是带有你不希望渲染的 UI 元素的截图。对每个 URL 进行快速 HEAD 请求,比一次失败的生成任务更便宜地捕获大多数这些问题。
如果你确实遇到拒绝,错误消息通常会指向输入对象。先在本地验证图像——尺寸、格式和可访问性——然后再怀疑 API。
分辨率和原生音频设置
输出设置是开发者容易过度配置的地方。好消息是默认值很合理;风险在于从另一个模型的文档中照搬值。
分辨率
分辨率决定交付视频的大小,并进而影响生成时间和输出体积。两条经验法则:
- 为目标目的地选择,而不是为数字选择。 用于移动端信息流的片段不需要以大尺寸渲染,然后又被缩小。选择满足目标平台的最小分辨率。
- 优先使用文档中的预设之一。 传入任意或不支持的值是请求被拒绝的常见原因。如果你需要特定帧,请在生成后裁剪或缩放,而不是与请求校验器对抗。
原生音频
原生音频开关决定生成的片段是否包含随视频一起产生的伴随音轨。考虑你是否需要它:
- 启用它,当片段是带声音观看的最终交付物时——社交内容、短促销、环境音频能增强运动感的角色场景。
- 禁用它,当你将在编辑器中加入自己的音乐或旁白,或者片段是中间资产时。生成你将要丢弃的音频是浪费工作,并使下游处理更繁重。
时长
时长与其他一切耦合:更长的片段生成时间更长,也更容易出现主体一致性漂移。对于首次集成,从短开始。用简短片段确认流水线端到端工作,然后再信任管道后加长。
保持设置对象小巧
如果你发现自己添加设置来修复质量问题,停下来检查问题是否实际上出在输入图像上。大多数令人失望的输出可追溯到第 4 章,而不是缺少某个旋钮。有意识地配置,将确切的设置对象与每个任务标识符一起记录,你就能将质量变化归因于特定的调整。
用 Python 做同样的请求
curl 请求可以直接转换为 Python。这里的目标不是框架——而是一个小型、可读的客户端,提交任务并返回标识符,这样轮询层可以保持分离。
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"
def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
payload = {
"model": MODEL,
"input": {"first_frame_image": first_frame_url},
}
if last_frame_url:
payload["input"]["last_frame_image"] = last_frame_url
response = requests.post(
f"{BASE_URL}/image-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()
为什么这样结构化
- 用环境变量做配置。 基础 URL 和密钥位于代码之外,因此同一个客户端可以针对不同环境运行。
- 提交时使用
timeout=30。 提交很快;提交挂起表示网络或认证问题,你希望尽早发现,而不是无限期阻塞工作进程。 - 解析前先
raise_for_status()。 4xx 响应体通常是 JSON 错误对象,而不是任务。先抛出异常可以保持正常路径干净,并让调用者显式处理失败。 - 提交与轮询分离。
submit_job只做一件事。下一章的轮询循环接收返回的字典并负责等待。
移植到服务中
在真实服务中,包装调用,使失败以携带状态码和响应体的类型化异常形式出现——生产调试时你会想要原始响应体。将请求体与返回的任务标识符一起记录;当同事问为什么某个片段看起来不对时,那行日志就是整个调查。
字段名与 curl 示例完全相同。如果你能读懂一个,就能读懂另一个——这正是从 curl 开始值得花五分钟的原因。
轮询结果而不猛击 API
现在任务已存在并有一个标识符。朴素的做法——休眠六十秒然后祈祷——有两种失败方式:任务提前完成时浪费时间,任务耗时更长时完全失败。
轮询状态字段,而不是时钟
写一个循环,查询任务的当前状态并根据它分支:
import time
import requests
def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
deadline = time.monotonic() + timeout_s
delay = 2.0
while time.monotonic() < deadline:
r = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
r.raise_for_status()
job = r.json()
status = job.get("status")
if status == "succeeded":
return job
if status == "failed":
raise RuntimeError(f"job failed: {job.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15.0) # 有界指数退避
raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")
重要的特性
- 显式终止状态。 只有
succeeded和failed结束循环。任何其他状态都是瞬时的。不要将未知状态视为失败——新的中间状态会随时间出现,你的循环应容忍它们。 - 有界退避。 从小开始(几秒),以适度的因子增长,上限约为十到十五秒。这可以保持短任务敏捷,而不会在长渲染期间猛击端点。
- 硬性截止时间。 始终限制总等待时间。没有它,卡住的任务会永久占用一个工作进程。根据你最长的现实渲染时间加上余量来选择上限。
- 将失败与超时分开。
failed任务是值得向用户报告的生成错误。超时是值得重试或单独调查的基础设施状况。将两者混为一谈会让事件复盘变得痛苦。
在 Web 服务中
不要在用户等待的请求处理器中运行此循环。提交、存储任务标识符、立即返回,让后台工作进程轮询并交付结果——通过 webhook、队列或前端监视的行更新。上面的循环是工作进程关注的问题,而不是 HTTP 关注的问题。
排查常见失败
大多数失败归为三类。先确定类别,再确定具体原因。
类别 1:输入校验失败
症状:提交时、任何渲染之前立即出现 4xx。
按此顺序诊断:
- 图像 URL 可访问吗? 从同一网络自己获取它。过期的签名 URL 和私有存储桶是首要原因。
- 格式受支持吗? 重新编码为标准格式,而不是争论。
- 首帧和尾帧一致吗? 不匹配的宽高比或差异极大的场景通常表现为校验或质量问题。
- 你是否添加了名称错误的字段? 未知键通常被拒绝而不是忽略。与模型参考进行对比。
类别 2:参数不匹配
症状:请求因某个设置被拒绝,或者输出忽略你的配置。
- 不支持的分辨率或时长。 只使用文档中的值;任意数字是常见的拒绝原因。
- 模型标识符拼写错误。 它是固定字符串——复制它,不要重新输入。
- 嵌套错误。 属于顶层的设置放到了
input内,或反之,会产生令人困惑的错误。以第 3 章的请求结构为参考。
类别 3:轮询超时与任务失败
症状:任务被接受,但从未到达终止成功状态。
- 确认你轮询的是正确的标识符。 批处理脚本中跨任务的复制粘贴错误出奇地常见。
- 检查状态是否真的在推进。 记录每次轮询的状态,以便查看任务是正在推进还是停滞。
- 区分 API 失败与生成失败。 如果轮询请求本身出错,那是传输问题。如果任务报告
failed,读取错误体——它通常会指出导致问题的输入。 - 重新运行最小
curl冒烟测试。 如果冒烟测试也失败,问题在于凭证或服务;如果它成功,问题在于你的请求体。
通用调试姿态
对每个任务记录三件事:确切的请求体、返回的任务标识符,以及带有错误体的最终状态。有了这三样,几乎每个事件都是五分钟的诊断,而不是一个下午。如有疑问,将请求缩减到第 3 章的最小形式,并逐个添加字段直到它出错——最后添加的字段就是罪魁祸首。