端点参考 · 创建生成任务

用 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,创建时间从查询结果读取。

JSON
{ "id": "TASK_ID", "status": "queued" }

下一步 · 用同一把 Key 查询任务结果

请求参数速查

字段类型必填说明
modelstring是目录里的 slug 或 aliases[] 之一。缺失返回 400
contentarray是使用 text、image_url、video_url、audio_url 或 draft_task。媒体字段的 url 可填公网可下载地址、素材库句柄 tt-ref://<id>(亦支持平台素材的 asset://<UUID>)或属于当前 Key 的 tt-upload://<id>。火山官方预置素材使用火山给出的 asset://,详见火山兼容接口。
content[].rolestring视场景而定区分素材用途:first_frame / last_frame / reference_image / reference_video / reference_audio。三种互斥的组合方式(首帧 / 首尾帧 / 全模态参考)见具体模型的 schema 说明,一次请求只能用其中一种,混用会在异步处理阶段才失败
resolution(同义键 size)string视模型和供货协议而定按分辨率计价和按秒计价的模型都可能按输出分辨率选择价格档;按秒费用为对应档每秒价格 × 计费时长。未指定或未匹配价格档时可能按最高价档兜底,供货协议也可能要求显式指定;支持值以实际目录、参数 schema 和价格档为准
ratiostring否画面比例,如 16:9,以 schema 为准
durationnumber按秒计价的模型上必填且必须 > 0,其余情况可选缺失时创建期直接返回 400,不会等任务跑完才失败
providerobject否高级路由偏好 {allow, deny},取值为供货协议标识。多个约束同时生效,筛空时返回 400。
callback_urlstring否目前传入会返回 400,请通过查询接口获取结果。
priorityinteger否目前传入会返回 400。
safety_identifierstring否按平台设置处理,客户端可省略。
其它创作参数—否schema additionalProperties: true,平台不会因为模型方新增字段而拒绝请求;具体某个参数在本平台是否真正生效,以对应模型的 schema 描述为准

以上示例为平台统一协议,使用 content 数组和顶层的 duration、resolution、ratio。火山方舟接口走 /api/v3,阿里百炼原生的 input / parameters 需改成此处格式。

样片转正式片

适用的 Seedance 2.5 供货规格支持创建时在顶层发送 "draft": true 生成样片。查询成功后,创建正式任务时在 content[] 放入一条样片引用,使用创建样片的同一把 Key:

JSON
{"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"?}}。

HTTPcode含义处理
400(无)缺 model补字段
400(无,param: "duration")按秒计价模型缺合法 duration补正数
400content_not_supportedcontent[] 里有一项该货源收不了(例如类型或角色不匹配、缺少 URL)检查内容组合是否符合该模型支持的场景
400asset_required / asset_not_found / asset_not_active / asset_type_mismatch / asset_model_mismatch / asset_supplier_mismatch / asset_tier_conflict素材相关问题见素材库错误说明
400draft_task_invalid / draft_task_unsupported_combination / draft_task_tier_conflict样片引用或规格设置不匹配核对样片的 Key、ID、引用位置和规格偏好
404(无)该模型此刻没有可用货源可路由核对模型 ID,或稍后重试
409(无)同一个 Idempotency-Key 值的另一次调用正在处理中稍后用相同的 Idempotency-Key 值重试;已获得任务 ID 时请选择查询原任务
500(无)平台侧配置问题,非请求导致可重试或联系支持
502upstream_error上游供应商不可达可重试,不要盲目频繁重试创建
503asset_supplier_unavailable引用的素材没有任何可路由的落地联系支持

完整错误码 → 错误码。