端点参考 · 创建生成任务
用 POST /v1/contents/generations/tasks 创建视频任务。请求返回任务 ID,视频在后台生成。已有火山方舟 Seedance 接入代码时,可以查看火山兼容接口。
发送创建请求
先设置 TP_API_KEY,把 MODEL_ID 换成视频模型目录返回的模型 ID,再设置一个新的 TP_REQUEST_ID(例如 UUID)。参数按该模型的 Schema 填写。成功生成可能产生费用。
curl "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": "海边日落,镜头缓慢推进"}],
"duration": 5,
"ratio": "16:9",
"resolution": "720p"
}'媒体有可公开下载的 URL 时可以先直接传入。如果当前可用的规格和路由要求已登记素材,请按 asset_required 提示登记素材,等到 active 后使用返回的句柄。
保存任务 ID 并查询
只依赖创建响应的 id。status 可能省略或由上游返回,以查询结果判定任务是否完成。请原样保存 ID,创建时间从查询结果读取。
{ "id": "TASK_ID", "status": "queued" }请求参数速查
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 目录里的 slug 或 aliases[] 之一。缺失返回 400 |
content | array | 是 | 使用 text、image_url、video_url、audio_url 或 draft_task。媒体字段的 url 可填公网可下载地址、素材库句柄 tt-ref://<id>(亦支持平台素材的 asset://<UUID>)或属于当前 Key 的 tt-upload://<id>。火山官方预置素材使用火山给出的 asset://,详见火山兼容接口。 |
content[].role | string | 视场景而定 | 区分素材用途:first_frame / last_frame / reference_image / reference_video / reference_audio。三种互斥的组合方式(首帧 / 首尾帧 / 全模态参考)见具体模型的 schema 说明,一次请求只能用其中一种,混用会在异步处理阶段才失败 |
resolution(同义键 size) | string | 视模型和供货协议而定 | 按分辨率计价和按秒计价的模型都可能按输出分辨率选择价格档;按秒费用为对应档每秒价格 × 计费时长。未指定或未匹配价格档时可能按最高价档兜底,供货协议也可能要求显式指定;支持值以实际目录、参数 schema 和价格档为准 |
ratio | string | 否 | 画面比例,如 16:9,以 schema 为准 |
duration | number | 按秒计价的模型上必填且必须 > 0,其余情况可选 | 缺失时创建期直接返回 400,不会等任务跑完才失败 |
provider | object | 否 | 高级路由偏好 {allow, deny},取值为供货协议标识。多个约束同时生效,筛空时返回 400。 |
callback_url | string | 否 | 目前传入会返回 400,请通过查询接口获取结果。 |
priority | integer | 否 | 目前传入会返回 400。 |
safety_identifier | string | 否 | 按平台设置处理,客户端可省略。 |
| 其它创作参数 | — | 否 | schema additionalProperties: true,平台不会因为模型方新增字段而拒绝请求;具体某个参数在本平台是否真正生效,以对应模型的 schema 描述为准 |
以上示例为平台统一协议,使用 content 数组和顶层的 duration、resolution、ratio。火山方舟接口走 /api/v3,阿里百炼原生的 input / parameters 需改成此处格式。
样片转正式片
适用的 Seedance 2.5 供货规格支持创建时在顶层发送 "draft": true 生成样片。查询成功后,创建正式任务时在 content[] 放入一条样片引用,使用创建样片的同一把 Key:
{"type":"draft_task","draft_task":{"id":"DRAFT_TASK_ID"}}正式片固定走创建样片的供货路径。样片任务超出 7 天的引用窗口、归属不符或不在受支持的路径上时返回 draft_task_invalid。样片引用只放在 content[] 中且只放一条,不能与平台素材句柄混用。规格偏好与样片不一致时,先核对设置再提交。费用以实际用量记录为准。
创建超时怎么办?
- 已拿到
id:查询原任务。停止本地等待后,远端任务仍可能继续并计费,/v1没有取消接口。 - 24 小时内发生超时、连接中断或
502,且原请求带了Idempotency-Key:用同一把 Key、同一接口、原请求体和原幂等键重试。换用新的幂等键会提交新任务。 - 未带幂等键且没有
id:先提交反馈,提供发生时间和请求标识,核查任务是否已经创建。
常见错误
错误体统一形状:{"error": {"message", "type", "code"?, "param"?}}。
| HTTP | code | 含义 | 处理 |
|---|---|---|---|
| 400 | (无) | 缺 model | 补字段 |
| 400 | (无,param: "duration") | 按秒计价模型缺合法 duration | 补正数 |
| 400 | content_not_supported | content[] 里有一项该货源收不了(例如类型或角色不匹配、缺少 URL) | 检查内容组合是否符合该模型支持的场景 |
| 400 | asset_required / asset_not_found / asset_not_active / asset_type_mismatch / asset_model_mismatch / asset_supplier_mismatch / asset_tier_conflict | 素材相关问题 | 见素材库错误说明 |
| 400 | draft_task_invalid / draft_task_unsupported_combination / draft_task_tier_conflict | 样片引用或规格设置不匹配 | 核对样片的 Key、ID、引用位置和规格偏好 |
| 404 | (无) | 该模型此刻没有可用货源可路由 | 核对模型 ID,或稍后重试 |
| 409 | (无) | 同一个 Idempotency-Key 值的另一次调用正在处理中 | 稍后用相同的 Idempotency-Key 值重试;已获得任务 ID 时请选择查询原任务 |
| 500 | (无) | 平台侧配置问题,非请求导致 | 可重试或联系支持 |
| 502 | upstream_error | 上游供应商不可达 | 可重试,不要盲目频繁重试创建 |
| 503 | asset_supplier_unavailable | 引用的素材没有任何可路由的落地 | 联系支持 |
完整错误码 → 错误码。