博客

教程

seedance-2.5-flash 图生视频 API 教程:curl 与 Python Requests

面向开发者的实用集成演练:请求结构、首帧/尾帧输入、异步轮询和错误排查

2026年11月19日
封面图:深咖啡底色上,宽窄不一的米色与铜色织物条带交错编织,构成扁平的篮纹几何图案。
本页内容

图生视频调用实际做了什么

在写第一行代码之前,先了解 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。

按此顺序诊断:

  1. 图像 URL 可访问吗? 从同一网络自己获取它。过期的签名 URL 和私有存储桶是首要原因。
  2. 格式受支持吗? 重新编码为标准格式,而不是争论。
  3. 首帧和尾帧一致吗? 不匹配的宽高比或差异极大的场景通常表现为校验或质量问题。
  4. 你是否添加了名称错误的字段? 未知键通常被拒绝而不是忽略。与模型参考进行对比。

类别 2:参数不匹配

症状:请求因某个设置被拒绝,或者输出忽略你的配置。

  • 不支持的分辨率或时长。 只使用文档中的值;任意数字是常见的拒绝原因。
  • 模型标识符拼写错误。 它是固定字符串——复制它,不要重新输入。
  • 嵌套错误。 属于顶层的设置放到了 input 内,或反之,会产生令人困惑的错误。以第 3 章的请求结构为参考。

类别 3:轮询超时与任务失败

症状:任务被接受,但从未到达终止成功状态。

  • 确认你轮询的是正确的标识符。 批处理脚本中跨任务的复制粘贴错误出奇地常见。
  • 检查状态是否真的在推进。 记录每次轮询的状态,以便查看任务是正在推进还是停滞。
  • 区分 API 失败与生成失败。 如果轮询请求本身出错,那是传输问题。如果任务报告 failed,读取错误体——它通常会指出导致问题的输入。
  • 重新运行最小 curl 冒烟测试。 如果冒烟测试也失败,问题在于凭证或服务;如果它成功,问题在于你的请求体。

通用调试姿态

对每个任务记录三件事:确切的请求体、返回的任务标识符,以及带有错误体的最终状态。有了这三样,几乎每个事件都是五分钟的诊断,而不是一个下午。如有疑问,将请求缩减到第 3 章的最小形式,并逐个添加字段直到它出错——最后添加的字段就是罪魁祸首。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档