Token Libs API
    • BytePlus (ModelArk) Seedance2.0 视频生成 API接入文档

    BytePlus (ModelArk) Seedance2.0 视频生成 API接入文档

    本文面向调用 tokenlibs 的客户，描述通过 tokenlibs 网关访问 BytePlus ModelArk
    Seedance 2.0 视频生成能力的接口。请求 / 响应形状与 BytePlus 官方 API 保持一致——
    你只需将官方 SDK / 客户端的 host 改为 tokenlibs 地址、密钥改为 tokenlibs 令牌即可接入。
    与官方文档的对照请见Byteplus官方网址。
    本文只说明 tokenlibs 网关层引入的差异，未提及的字段一律原样透传。

    1. 接入概览#

    项官方 BytePlustokenlibs 下游
    Hosthttps://ark.ap-southeast.bytepluses.comhttps://api-global.tokenlibs.com
    路径前缀/api/v3/contents/generations/tasks/byteplus/api/v3/contents/generations/tasks
    鉴权BytePlus API Keytokenlibs 令牌（Authorization: Bearer sk-xxxx）
    透传是“受控透传”：除身份字段（id / model）外，请求与响应的所有字段
    （包括 BytePlus 未来新增的字段）都原样转发。

    鉴权#

    所有接口使用统一的 tokenlibs 鉴权头：
    Authorization: Bearer <你的 tokenlibs 令牌>
Content-Type: application/json
    tokenlibs 校验令牌、用户/分组、配额与限流后，转发到 BytePlus。
    客户端不需要、也不应携带上游 BytePlus 密钥。

    支持的接口#

    操作方法与路径
    创建任务POST /byteplus/api/v3/contents/generations/tasks
    查询任务GET /byteplus/api/v3/contents/generations/tasks/{task_id}
    取消 / 删除任务DELETE /byteplus/api/v3/contents/generations/tasks/{task_id}
    结果回调（Webhook）由 tokenlibs 主动 POST 到你的 callback_url（见 §5）

    2. 创建任务#

    POST /byteplus/api/v3/contents/generations/tasks
    请求体与 BytePlus 官方完全一致（model + content[] 多模态数组 + resolution /
    ratio / duration / seed / generate_audio 等参数）。完整字段见官方
    Create a video generation task。

    请求示例#

    {
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "A kitten yawns at the camera" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "callback_url": "https://your-server.example.com/byteplus/webhook"
}

    响应#

    与官方一致，返回任务 ID。唯一差异：id 为 tokenlibs 颁发的 task_xxxx。
    { "id": "task_a1b2c3d4e5f6..." }
    创建是异步接口。拿到 id 后通过 §3 查询状态；成功后从 content.video_url 取结果。
    请妥善保存此 task_id，后续查询 / 取消 / Webhook 均以它为准。

    3. 查询任务#

    GET /byteplus/api/v3/contents/generations/tasks/{task_id}
    路径参数 {task_id} 为创建时返回的 task_xxxx。响应体与官方
    Retrieve a video generation task 一致（id 已改写为对外形态）。

    响应示例（成功）#

    {
  "id": "task_a1b2c3d4e5f6...",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": { "video_url": "https://.../output.mp4" },
  "usage": { "completion_tokens": 1234, "total_tokens": 1234 },
  "created_at": 1717142400,
  "updated_at": 1717142460
}

    status 取值#

    status含义
    queued排队中
    running生成中
    succeeded成功（终态，content.video_url 可用）
    failed失败（终态，error 含原因）
    cancelled已取消（终态；仅 queued 任务被取消后出现）
    expired超时（终态；任务长期处于 queued/running 超过过期阈值）

    重要语义：终态由网关裁决#

    tokenlibs 以自身任务状态为权威来源：
    content.video_url 由 BytePlus CDN 直出，tokenlibs 不代理；请在有效期内（官方约 24h）及时保存。

    4. 取消 / 删除任务#

    DELETE /byteplus/api/v3/contents/generations/tasks/{task_id}
    与官方一致，DELETE 的行为取决于任务当前状态：
    任务状态是否可操作行为操作后
    queued可从队列移除，状态置为 cancelledcancelled（仍可查询）
    running否—（返回 409）—
    succeeded / failed / expired可删除任务记录，不再可查询记录被物理删除
    cancelled否——

    5. 结果回调（Webhook）#

    在创建任务时传入 callback_url，tokenlibs 将在任务产生明确结果时，向该地址 POST 结果。

    ✅ 仅在“明确结果（终态）”时推送#

    这是与官方 BytePlus 回调的关键差异：
    状态变化官方 BytePlus 回调tokenlibs Webhook
    → queued推送不推送
    → running推送不推送
    → succeeded推送✅ 推送
    → failed推送✅ 推送
    → cancelled—（不推送）✅ 推送（终态）
    → expired推送✅ 推送
    即：tokenlibs 只在任务到达终态（succeeded / failed / cancelled / expired，即结果已确定）时
    推送一次    ，不会推送中间的 queued / running 进度。

    回调请求#

    方法：POST，Content-Type: application/json
    请求头：X-tokenlibs-Task-Id: task_xxxx（便于校验 / 关联）
    请求体：与查询接口的响应体完全相同。
    {
  "id": "task_a1b2c3d4e5f6...",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": { "video_url": "https://.../output.mp4" },
  "usage": { "completion_tokens": 1234, "total_tokens": 1234 }
}

    投递策略#

    超时：单次请求 10s。
    重试：最多 3 次，退避节奏 0s / 2s / 4s（首次立即）。返回 2xx 视为成功并停止重试。
    状态确认：请将关键状态获取 以查询接口（§3）为兜底，不要仅依赖 Webhook。
    你的回调端点应尽快返回 2xx，并对同一 task_id 的重复投递做幂等处理
    （重试或边界情况下可能重复收到）。

    6. 错误处理#

    上游错误：BytePlus 返回的错误原样透传（错误码与错误信息一致）。
    网关错误：tokenlibs 自身的前置错误（鉴权失败 / 配额不足 / 无可用渠道 / 限流等）
    以 BytePlus 的错误代码返回。

    7. 计费说明（概要）#

    Seedance 按 token 计费：charge = X × cellRatio × completion_tokens × group_ratio，
    仅成功的视频计费，失败（含内容审核拒绝）不计费。cellRatio 按
    「模型 × 分辨率档（480p/720p 同档，1080p 独立）× 是否含视频输入」查表确定；*-fast
    模型无分辨率维度且不支持 1080p。结算在任务成功时以 usage.completion_tokens 为基准完成。
    详细倍率表见 官方计费说明。
    Built with