用一张图片生成视频(首帧模式)

用一张有权使用、可公开下载的图片作为视频的第一帧。先按模型参数确认所选模型支持首帧模式,再创建一次任务。成功生成可能产生费用。

快速做法

先设置 TP_API_KEY。在下方创建示例中替换 MODEL_ID 和图片地址。能直接下载的公网图片可先直传。创建响应返回 id 后,用同一把 Key 查询并下载。

第 3 步 · 创建生成任务(只执行一次)

每次新任务设置一个新的 TP_REQUEST_ID。无响应时使用原 Key、原请求体和原幂等键恢复,详见创建接口重试规则。这个 /v1 路径没有取消接口。

终端命令
curl -X POST "https://intertoken.ai/v1/contents/generations/tasks" \
  -H "Authorization: Bearer $TP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $TP_REQUEST_ID" \
  -d '{
    "model": "{MODEL_ID}",
    "content": [
      {"type": "text", "text": "保持主体一致,镜头缓慢推进"},
      {"type": "image_url", "role": "first_frame", "image_url": {"url": "https://example.com/first-frame.jpg"}}
    ],
    "resolution": "720p",
    "duration": 5
  }'

返回:

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

保存 id,下一步查询这个任务。若登记了图片,请把示例里的 URL 换成返回的 ref。Seedance 2.5 首帧比例跟随图片,按 Schema 省略 ratio。

没传 resolution 时:计费按该模型档位中最高价档兜底,实际输出分辨率仍由模型自身决定,两者不是一回事。

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

终端命令
curl "https://intertoken.ai/v1/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 再查即可。

成功时的完整响应形状

JSON
{
  "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供对账/排障用的上游任务标识、原始产物链接、上游模型全名、上游侧用量;只有当这次调用经过一个可核对的中间供应链环节时才会出现——某些直连路径没有这类中间信息可回显,这不代表调用有问题

失败时:

JSON
{
  "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。产物有保留期,成功后请尽快下载;下载失败可以重试下载,这不会重新创建生成任务。

确认模型与参数

终端命令
curl "https://intertoken.ai/v1/contents/generations/models" \
  -H "Authorization: Bearer $TP_API_KEY"

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

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

终端命令
curl "https://intertoken.ai/v1/contents/generations/models/ENCODED_MODEL_ID/schema" \
  -H "Authorization: Bearer $TP_API_KEY"

把 MODEL_ID 中的斜杠编码为 %2F 后填入 ENCODED_MODEL_ID。返回一个标准 JSON Schema(required/properties/字段说明),required 里列出的字段是这个型号计费方式下必填的;properties 里每个字段带一句说明,包含该字段仅哪些型号支持。

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

登记与复用图片素材

当请求返回 asset_required,或想复用一张图时,先登记,再等待 active。

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

响应:

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

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

等素材就绪

终端命令
curl "https://intertoken.ai/v1/media/assets/{ASSET_ID}" -H "Authorization: Bearer $TP_API_KEY"

status 六个取值:pending(排队中)/ processing(处理中)/ active(可引用)/ failed(处理失败)/ expired(已过期)/ deleted(已删除)。只有 active 才能用于生成,引用非 active 的素材会被创建接口同步拒绝。每 5~10 秒查一次,直到 active 或进入失败类终态(更换素材后重新登记)。

本页涉及的错误

错误含义处理
asset_required当前可选路径要求已登记的图片登记素材,等到 active 后用返回的 ref 创建。
asset_not_active素材还没就绪打开「登记与复用图片素材」继续等 active
asset_not_found素材不存在,或不属于当前 Key核对 asset_id 与所用的 Key 是否一致
asset_type_mismatch引用的素材实际类型与声明类型不符确认素材确实是图片类型
asset_model_mismatch素材没有绑定到本次请求的模型检查是否用同一批素材调用了不同型号

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

完成后