TTokenPortal

端点参考 · 创建生成任务

Doc status已发布Feature status已上线Last updated：2026-09-21

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

5. 响应

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

HTTPcode含义处理
400（无）缺 model补字段
400（无，param: "duration"）按秒计价模型缺合法 duration补正数
400content_not_supportedcontent[] 里有一项该货源收不了（类型/角色不匹配、缺 url、首尾帧超过 1 张等）检查内容组合是否符合该模型支持的场景
400asset_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 值重试，或直接轮询已在处理的那次调用
502upstream_error上游供应商不可达可重试，不要盲目频繁重试创建
503asset_supplier_unavailable引用的素材没有任何可路由的落地联系支持

完整错误码 → 错误码。

8. 重试规则

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