用一张图片生成视频(首帧模式)
用一张有权使用、可公开下载的图片作为视频的第一帧。先按模型参数确认所选模型支持首帧模式,再创建一次任务。成功生成可能产生费用。
快速做法
先设置 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
}'返回:
{ "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 再查即可。
成功时的完整响应形状
{
"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。产物有保留期,成功后请尽快下载;下载失败可以重试下载,这不会重新创建生成任务。
确认模型与参数
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"}'响应:
{
"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 | 素材没有绑定到本次请求的模型 | 检查是否用同一批素材调用了不同型号 |
完整错误码列表 → 错误码。
完成后
- 查看视频模型能力和参数
- 想查每个字段的完整定义 → 端点参考 · 创建生成任务 / 查询生成任务 / 模型目录与 Schema
- 了解首尾帧、参考视频和其它组合