用一张图片生成视频（首帧模式）

用一张图片作为视频的第一帧，生成一段视频。本页覆盖当前已上线的单首帧路径：一次请求只提供一张首帧图，不涉及尾帧、参考视频等多素材组合（那些会在对应能力上线后单独出教程）。

本页可能产生生成费用：创建的任务成功完成后按平台计费规则扣费。素材注册、查询、下载不会重新创建生成任务，这些环节是否涉及其它费用以平台计费口径为准。

你需要准备

一个 sk- 开头的 API Key
一张能被公网直接下载的图片地址（浏览器打开能看到图，不需要登录、不是本地路径）
能执行 cURL 的终端

流程总览

① 查目录，确认模型 slug 与它的计费维度
② 查该模型的参数 schema（可选但推荐，用来确认这次调用要传哪些字段）
③ 注册图片素材，等它变成 active
④ 创建生成任务，content 里用 role=first_frame 引用素材
⑤ 轮询任务直到终态
⑥ 下载视频

第 1 步 · 确认模型与它的参数形状

curl "$TP_API_BASE/contents/generations/models" \
  -H "Authorization: Bearer $TP_API_KEY"

从返回的 data[] 里找到你要用的 Seedance 型号，记下它的 slug（下文用 {MODEL_ID} 代替）。

推荐在正式调用前查一次该模型的参数 schema，用来动态确认这次要传哪些字段——平台创作参数按型号有差异（例如是否支持 generate_audio、return_last_frame 只有部分型号支持），schema 是随发布更新的权威来源，比记住一份写死的字段表更可靠：

curl "$TP_API_BASE/contents/generations/models/{MODEL_ID}/schema" \
  -H "Authorization: Bearer $TP_API_KEY"

返回一个标准 JSON Schema（required/properties/字段说明），required 里列出的字段是这个型号计费方式下必填的；properties 里每个字段带一句说明，包含该字段仅哪些型号支持。

状态码	含义
`200`	正常返回 schema
`404`	目录里没有这个模型 slug——检查拼写，或说明目录还未收录该型号
`501`	模型在目录里，但平台还没为它登记参数 schema——模型仍可正常调用，只是这份"提前校验"用不了
`503`	平台侧取数失败，与"模型不存在"无关，稍后重试

第 2 步 · 注册图片素材

curl -X POST "$TP_API_BASE/media/assets" \
  -H "Authorization: Bearer $TP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/first-frame.jpg", "asset_type": "image"}'

响应：

{
  "asset_id": "3f2c1a90-...",
  "ref": "tt-ref://3f2c1a90-...",
  "asset_type": "image",
  "status": "pending"
}

记下 ref——创建任务时直接把它填进 content[]，平台会在路由时改写成对应供应商的引用方式，你不需要关心供应商侧的具体形态。

等素材就绪

curl "$TP_API_BASE/media/assets/{ASSET_ID}" -H "Authorization: Bearer $TP_API_KEY"

status 六个取值：pending（排队中）/ processing（处理中）/ active（可引用）/ failed（处理失败）/ expired（已过期）/ deleted（已删除）。只有 active 才能用于生成，引用非 active 的素材会被创建接口同步拒绝。每 5～10 秒查一次，直到 active 或进入失败类终态（换素材重新走第 2 步）。

第 3 步 · 创建生成任务（只执行一次）

这一步会创建付费任务。⚠ 排队中的任务目前基本无法取消：取消接口存在（DELETE …/tasks/{id}），但排队中只有火山直连货源支持取消，其它货源返回 403；已结束的任务可以删除。建议带上 Idempotency-Key 请求头（值自己生成一个唯一字符串，如 UUID）：同一把 Key + 同一个 Idempotency-Key 值在 24 小时内重复提交，返回的是同一次调用的结果，不会重复创建任务、不会重复计费。请求超时、返回 5xx 或连接中断时，用相同的 Idempotency-Key 重试即可安全恢复；换成新的 Idempotency-Key 值会被当成一次新的调用。

curl -X POST "$TP_API_BASE/contents/generations/tasks" \
  -H "Authorization: Bearer $TP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 你生成的唯一字符串" \
  -d '{
    "model": "{MODEL_ID}",
    "content": [
      {"type": "text", "text": "保持主体一致，镜头缓慢推进"},
      {"type": "image_url", "role": "first_frame", "image_url": {"url": "tt-ref://{ASSET_ID}"}}
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

{ "id": "任务ID", "status": "queued" }

保存 id，之后只靠它查询，不要重复创建。

没传 resolution 时：计费按该模型档位中最高价档兜底（宁多算不漏收），实际输出分辨率仍由模型自身决定，两者不是一回事。

第 4 步 · 轮询任务直到终态

curl "$TP_API_BASE/contents/generations/tasks/{TASK_ID}" \
  -H "Authorization: Bearer $TP_API_KEY"

status 五个取值：

status	含义	你该做什么
`queued`	排队中	继续查
`running`	生成中	继续查；`running` 持续几分钟是正常的，不代表卡住
`succeeded`	成功	去第 5 步下载
`failed`	失败	记下 `error.reason` 和 `error.message`，不要重建
`canceled`	已取消	同上

每 15～20 秒查一次。查询请求本身失败（网络错、5xx）可以重查同一个 id——查询不会重新创建任务。停止本地等待（关窗口、Ctrl+C）不会取消远端任务，任务仍可能继续执行，是否扣费按最终结果处理；之后用保存的 id 再查即可。

成功时的完整响应形状

{
  "id": "任务ID",
  "status": "succeeded",
  "output": [
    { "type": "video", "url": "https://…/xxx.mp4" }
  ],
  "usage": { "total_tokens": 108900 },
  "error": null,
  "echo": {
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "upstream_task_id": "...",
    "upstream_model": "...",
    "upstream_usage": { "total_tokens": 108900 }
  }
}

字段	说明
`output[]`	产物定位符数组，取 `type == "video"` 的 `url` 下载
`usage.total_tokens`	计费依据的用量计数，不是金额；账单以用量查询为准
`echo`	可选，仅在平台确实拿到额外可回显信息时才出现——整个对象可能不存在，出现时其中每个字段也各自独立可能缺失。不要假设它一定出现，也不要假设某个子字段一定存在
`echo` 里的生成参数回显（`resolution`/`ratio`/`duration`/`seed` 等）	上游实际采用的参数值，用于确认"平台/上游到底按什么参数生成的"，与你请求时传的值可能不同
`echo.upstream_task_id` / `upstream_url` / `upstream_model` / `upstream_usage`	供对账/排障用的上游任务标识、原始产物链接、上游模型全名、上游侧用量；只有当这次调用经过一个可核对的中间供应链环节时才会出现——某些直连路径没有这类中间信息可回显，这不代表调用有问题

失败时：

{
  "id": "任务ID",
  "status": "failed",
  "output": null,
  "usage": null,
  "error": { "reason": "upstream_error", "message": "..." }
}

error.reason 只有三个取值：upstream_error（上游生成失败）、upstream_expired（上游超时未完成）、canceled（已取消）。请按 reason 分支处理，不要解析 message 文案——文案只保证人可读，不保证跨版本稳定。

第 5 步 · 下载

取 output[] 里 type == "video" 的 url。产物有保留期，成功后请尽快下载；下载失败可以重试下载，这不会重新创建生成任务。

本页涉及的错误

错误	含义	处理
`asset_required`	该路由要求素材句柄，你传了公网 URL	回第 2 步注册素材，改用 `tt-ref://`
`asset_not_active`	素材还没就绪	回第 2 步继续等 `active`
`asset_not_found`	素材不存在，或不属于当前 Key	核对 `asset_id` 与所用的 Key 是否一致
`asset_type_mismatch`	引用的素材实际类型与声明类型不符	确认素材确实是图片类型
`asset_model_mismatch`	素材没有绑定到本次请求的模型	检查是否用同一批素材调用了不同型号

完整错误码列表 → 错误码。

完成后

想知道这个模型还支持什么参数、有什么限制 → 对应的模型说明页
想查每个字段的完整定义 → 端点参考 · 创建生成任务 / 查询生成任务 / 模型目录与 Schema
首尾帧、参考视频等多素材组合 → 待对应能力上线后另有教程