端点参考 · 创建生成任务

1. 概述

创建一个视频/多模态生成作业（目前包含 Seedance 系列模型）。请求立即返回作业 id，生成在后台异步进行，用查询生成任务轮询结果。

已经对接过火山方舟（字节）Seedance？本平台另有火山兼容路径 POST /api/v3/contents/generations/tasks：请求与返回按火山方舟的字段取值，只需换 Base URL、API Key 和 model。详见《Seedance 系列模型接入指南》 §0a。本页描述的是 /v1 路径。


状态	已上线
适用模型	模型目录接口 `GET https://intertoken.ai/v1/contents/generations/models` 返回的生成类模型
计费	作业成功完成时按平台计费规则扣费一次；创建请求本身不扣费
幂等	支持 `Idempotency-Key` 请求头，见 §4
取消	不支持，已创建的作业无法主动取消

2. 使用前提

用模型目录接口拿到模型 slug
若模型 asset_required: true 且这次请求带图片/视频/音频输入，先用素材库注册好素材
建议先查一次该模型的参数 schema，确认这次要传哪些字段——不同模型支持的创作参数不同，schema 是随发布更新的权威来源

3. 鉴权与地址

POST https://intertoken.ai/v1/contents/generations/tasks
Authorization: Bearer sk-…        （或 x-api-key: sk-…，Authorization 为空时的备选）
Content-Type: application/json

4. 请求

{
  "model": "volcengine/doubao-seedance-2.0",
  "content": [
    { "type": "text", "text": "无人机航拍海边日落，镜头缓慢推进" },
    { "type": "image_url", "role": "first_frame", "image_url": { "url": "https://example.com/first-frame.jpg" } }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5
}

字段	类型	必填	说明
`model`	string	是	目录里的 `slug` 或 `aliases[]` 之一。缺失返回 400
`content`	array	是	typed parts 数组，元素 `type` 取值 `text` / `image_url` / `video_url` / `audio_url`。图/视频/音频位的 `url` 支持四种形态：公网可拉取 URL、素材库句柄 `tt-ref://<id>`（见素材库）、平台私有存储句柄 `tt-upload://<id>`（属主校验只认发起请求的 Key）、火山官方预置素材句柄 `asset://<id>`（原样透传，⛔ 不经过素材库注册，仅路由到火山直连/太行时上游认得，其它货源会失败）
`content[].role`	string	视场景而定	区分素材用途：`first_frame` / `last_frame` / `reference_image` / `reference_video` / `reference_audio`。三种互斥的组合方式（首帧 / 首尾帧 / 全模态参考）见具体模型的 schema 说明，一次请求只能用其中一种，混用会在异步处理阶段才失败
`resolution`（同义键 `size`）	string	视计费维度而定	计费维度为按分辨率计价的模型上可选，缺省按该模型最高价档兜底计费；按秒计价的模型上同样可选，仅描述性、不参与计价
`ratio`	string	否	画面比例，如 `16:9`，以 schema 为准
`duration`	number	按秒计价的模型上必填且必须 > 0，其余情况可选	缺失时创建期直接返回 400，不会等任务跑完才失败
`provider`	object	否	路由偏好 `{allow, deny}`（⚠ 只有这两个键，没有 `sort`）。取值是供应商方言标识（如 `volcengine`/`kyy-seedance2`/`lanyun-seedance`），⛔ 不是供应商展示名。与已有约束是 AND 关系，都给了就都要满足；筛空全部候选 ⇒ `400`
`callback_url`	string	否	⛔ 不支持，传了直接 400——webhook 回调尚未上线，⛔ 不要依赖它
`priority`	integer	否	⛔ 不支持，传了直接 400——会让一个客户插队到共享供应商队列所有其他客户前面，暂不开放
`safety_identifier`	string	否	⚠ 传了会被平台侧的值静默覆盖（不报错）——平台用它向上游做终端用户滥用归因，不需要你自己传
其它创作参数	—	否	schema `additionalProperties: true`，平台不会因为模型方新增字段而拒绝请求；具体某个参数在本平台是否真正生效，以对应模型的 schema 描述为准

5. 响应

{ "id": "cgt-20260101120000-a1b2c", "status": "queued" }

字段	类型	说明
`id`	string	作业 ID，之后只依赖它查询，⛔ 假设固定前缀——上例是字节原厂号的形态，其它货源形态不同。也 ⛔ 从它里面解析时间或任何含义：那串数字是上游自己的编号规则，平台⛔ 保证其含义与稳定性；要创建时刻请在查询作业后读 `created_at`。
`status`	string	创建时恒为 `queued`

这个响应体是上游原样透传的，不是平台归一后的固定格式——不同货源返回的原始字段可能不止 id/status 这两个，但平台保证一定能解析出 id。创建响应体请只依赖 id 字段，其余字段不要当成契约来解析；归一化、稳定的结果形状在查询生成任务里。

6. 示例

curl -X POST "https://intertoken.ai/v1/contents/generations/tasks" \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 你生成的唯一字符串" \
  -d '{
    "model": "{MODEL_ID}",
    "content": [{"type": "text", "text": "海边日落，镜头缓慢推进"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

7. 错误

错误体统一形状：{"error": {"message", "type", "code"?, "param"?}}。

HTTP	`code`	含义	处理
400	（无）	缺 `model`	补字段
400	（无，`param: "duration"`）	按秒计价模型缺合法 `duration`	补正数
400	`content_not_supported`	`content[]` 里有一项该货源收不了（类型/角色不匹配、缺 `url`、首尾帧超过 1 张等）	检查内容组合是否符合该模型支持的场景
400	`asset_required` / `asset_not_found` / `asset_not_active` / `asset_type_mismatch` / `asset_model_mismatch` / `asset_supplier_mismatch` / `asset_tier_conflict`	素材相关问题	见素材库错误说明
404	（无）	该模型此刻没有可用货源可路由	核对模型 ID，或稍后重试
500	（无）	平台侧配置问题，非请求导致	可重试或联系支持
409	（无）	同一个 `Idempotency-Key` 值的另一次调用正在处理中	稍后用相同的 `Idempotency-Key` 值重试，或直接轮询已在处理的那次调用
502	`upstream_error`	上游供应商不可达	可重试，不要盲目频繁重试创建
503	`asset_supplier_unavailable`	引用的素材没有任何可路由的落地	联系支持

完整错误码 → 错误码。

8. 重试规则

情况	能否重试	说明
创建请求超时 / 502 / 连接中断，且带了 `Idempotency-Key`	用相同的 `Idempotency-Key` 值安全重试	24 小时内命中同一次调用的结果，不会重复创建、不会重复计费
创建请求超时 / 502 / 连接中断，未带 `Idempotency-Key`	不建议直接重试	先用没有 `id` 时唯一能做的方式——联系支持核查是否已创建；后续请求建议都带上这个头
已拿到 `id`	只轮询该 `id`	不要重新创建
本地进程退出 / 停止等待	远端任务不会取消	无取消接口，任务仍可能继续执行并计费