Token Libs API
    • BytePlus (ModelArk) Seedance2.0 视频生成 API接入文档
    • 火山方舟 Seedance2.0 系列视频生成 API接入文档

    火山方舟 Seedance2.0 系列视频生成 API接入文档

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

    1. 接入概览#

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

    鉴权#

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

    支持的接口#

    操作方法与路径
    创建任务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）
    真人 / 仿真人参考图素材审核POST /byteplus/api/asset/upload/sync（见 §8）

    2. 创建任务#

    POST /byteplus/api/v3/contents/generations/tasks
    请求体与 火山方舟 官方完全一致（model + content[] 多模态数组 + resolution /
    ratio / duration / seed / generate_audio 等参数）。完整字段见官方
    创建视频生成任务 API。

    请求示例#

    {
  "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。响应体与官方
    查询视频生成任务 API 一致（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 由 火山方舟 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 结果。

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

    这是与官方 火山方舟 回调的关键差异：
    状态变化官方 火山方舟 回调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. 错误处理#

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

    7. 计费说明（概要）#

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

    8. 素材上传（辅助接口，同步）#

    POST /byteplus/api/asset/upload/sync
    将一组媒体 URL 注册 / 上传到 火山方舟 素材库，同步返回素材引用。与视频生成任务不同，
    这是一个辅助接口：不创建任务、不轮询、不计费。

    请求#

    请求头：Authorization: Bearer sk-xxxx（tokenlibs 令牌，非上游密钥）、Content-Type: application/json
    请求体：固定为 {images, asset_type}，无需携带 model。
    {
  "images": [
    "https://XXX11.png",
    "https://XXX2.png"
  ],
  "asset_type": "Image"
}

    响应示例（成功，HTTP 200）#

    {
  "track_id": "5208a2ec6ce266dbf898a967d8561ba8",
  "status": "completed",
  "task_id": "task-20260617095644-d9236ee8",
  "asset_urls": [
    "Asset://asset-20260617175337-krnp7",
    "Asset://asset-20260617175647-p7p8m"
  ]
}
    ⚠️ 此处 task_id / track_id 为上传素材文件请求任务的参数，不可轮询、无对应任务记录，
    请勿用于查询 / 取消接口。

    响应示例（失败，HTTP 400）#

    {
  "message": "第1条URL文件类型不受支持，请确保URL包含受支持的扩展名...",
  "status": "failed"
}

    HTTP 状态码#

    场景HTTP响应体
    成功200成功格式（见上）
    失败400{message, status:"failed"}
    无可用渠道 / 请求体非法 JSON400{message, status:"failed"}
    网络异常500{message, status:"failed"}

    curl 示例#

    上一页
    BytePlus (ModelArk) Seedance2.0 视频生成 API接入文档
    Built with