对接文档

文档信息

• 适用环境：生产环境
• Base URL：https://api.topview.ai
• 路径前缀：/cn
• 上游：火山方舟中国区
• 模型：Seedance 2.0 / 2.0 fast / 2.0 mini / 2.5
• 协议版本：方舟 /api/v3 内容生成任务协议
• 更新时间：2026-11-12

本接口是火山方舟中国区 API 的透传代理。除了路径要加 /cn 前缀之外， 请求体、响应体、错误信封与上游一致。平台负责上游鉴权、任务归属隔离、并发控制与积分扣费， 客户端无需持有方舟 API Key。

1. 与 BytePlus 国际版通道的关系

两条通道是独立服务：

• 上游账号不同，并发额度与素材额度都分开配置。
• 价目不同，账单上是两个独立的计费项。
• 模型名不通用，混用路径与模型会返回 400 InvalidParameter。
• 任务互不可见，用另一条通道查询任务会返回 404。
• 素材库互不可见，素材 ID 不能跨通道引用。

2. 接口概览

POST /cn/api/v3/contents/generations/tasks          创建视频生成任务
GET  /cn/api/v3/contents/generations/tasks/{id}     查询任务
POST /cn?Action={Action}&Version=2024-01-01         素材库（见第 8 节）

不提供任务列表与删除接口。

3. 鉴权与通用约定

Authorization: Bearer sk-你的TopviewAPIKey
Content-Type: application/json

• 使用与国际版相同的 Topview API Key。
• 仅接受 Topview API Key（sk-），无需传递 Topview-Uid 或 Topview-Team-Id。
• 创建响应的 id 是上游任务 ID（task_* 开头），平台不做替换。
• 创建与查询响应里都有的 upstream_task_id（cgt-*）是火山侧原始 ID，仅供排查，不能用于查询。
• 响应头 X-Topview-Request-Id 是平台内部任务 ID，请记录到日志。
• 请求体上限 10 MB；大图建议使用公网 URL。

4. 创建视频生成任务

4.1 接口

POST https://api.topview.ai/cn/api/v3/contents/generations/tasks

4.2 请求字段

model

以下四个官方 model ID 已开通：

各模型可用的分辨率互不相同，超出上表范围会被拒绝。两点容易踩到： 4K 只认 4k 这一种写法，传 2160p 会被拒；fast 与 mini 只有 480p 与 720p， 不支持 1080p 及以上。

content

请求体结构与官方一致。图片 URL 支持公网 HTTP(S) 地址、data:{MIME};base64,{data}， 以及 asset://{assetId} 素材库引用。

asset:// 里的素材 ID 必须是在本通道（/cn）的素材接口下创建的， 传入国际版通道的素材 ID 会返回 400 InvalidParameter。

分辨率

resolution 可以作为顶层字段传递，也可以写在 prompt 文本的 --resolution 4k 命令中。只接受第 6 节价目表中已定价的分辨率。

callback_url

可选，填写终态回调的公网 HTTP(S) 地址。平台会把该值替换成自己的上游回调地址， 在任务终态时转发原始回调体。内网和回环地址会被拒绝。

4.3 请求示例

curl -X POST \
  'https://api.topview.ai/cn/api/v3/contents/generations/tasks' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "电影级镜头，一艘飞船穿过深紫色星云"
      }
    ],
    "resolution": "480p",
    "duration": 5
  }'

4.4 创建成功响应

{
  "id": "task_H6q96265lFuQOt2fIO8F2DBgWqmBv2Gl",
  "upstream_task_id": "cgt-20260916172941-r49zf"
}

只有 id 能用于查询。upstream_task_id 创建时就会返回，与查询响应里的同名字段一样 仅供排查，不能作为查询参数。

响应头：

X-Topview-Request-Id: 平台内部任务ID

4.5 创建失败响应

平台侧校验产生的错误（Key 无效、model 未开通、并发不足、分辨率未定价等）在顶层 error 对象：

{
  "error": {
    "code": "InvalidParameter",
    "message": "错误详情 Request id: 示例请求ID",
    "param": "",
    "type": "BadRequest"
  }
}

由上游生成侧校验产生的错误是另一种形状，最常见的是分辨率、时长、比例不合法。 顶层没有 error，而是 code / message / data，且官方信封被字符串化放进 message：

{
  "code": "fail_to_fetch_task",
  "message": "{\"error\":{\"code\":\"InvalidParameter\",\"message\":\"the parameter resolution specified in the request is not valid for model doubao-seedance-2-5 in t2v Request id: 示例请求ID\",\"param\":\"resolution\",\"type\":\"BadRequest\"}}",
  "data": null
}

两种形状的 HTTP 状态都是 400，都表示创建失败、不扣费、不占并发槽位。 解析时不要假设顶层一定有 error：先读顶层 error，取不到再看顶层 code， 若为 fail_to_fetch_task 就把 message 当 JSON 字符串再解一层， 其中 error.param 会指出哪个字段不合法。

创建失败时没有上游任务 ID，请用响应头中的 X-Topview-Request-Id 提交工单。 创建结果未知的任务不会被自动认领，平台会在超时窗口后释放并发槽位并置为失败，不会扣费。

4.6 样片模式（仅 Seedance 2.5）

先用 480p 快速生成一段样片（Draft），确认镜头、动作与提示词意图符合预期后， 再基于样片生成 1080p 成片。只有 doubao-seedance-2-5-260628 支持。 两步都用 4.1 节的创建接口，查询用第 5 节的接口。

Step 1：生成样片。 在普通请求上加 "draft": true，resolution 只能是 480p：

curl -X POST \
  'https://api.topview.ai/cn/api/v3/contents/generations/tasks' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      { "type": "text", "text": "女孩抱着狐狸，女孩睁开眼，温柔地看向镜头，镜头缓缓拉远" },
      { "type": "image_url", "image_url": { "url": "https://example.com/girl-fox.png" } }
    ],
    "resolution": "480p",
    "duration": 5,
    "ratio": "adaptive",
    "draft": true
  }'

创建响应里的 id（task_*）就是样片 ID。查询到 succeeded 后可下载样片预览， 只有 succeeded 的样片才能生成成片。

Step 2：生成成片。 content 里只放一个 draft_task 项，resolution 必须传 1080p：

curl -X POST \
  'https://api.topview.ai/cn/api/v3/contents/generations/tasks' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      { "type": "draft_task", "draft_task": { "id": "task_样片ID" } }
    ],
    "resolution": "1080p"
  }'

成片返回新的 task_* ID，按普通任务查询与下载。

成片请求的参数规则：

本通道的约束：

• draft_task.id 填创建响应的 id（task_*），不要填 upstream_task_id。
• 只能引用本账号、本通道（/cn）创建且已 succeeded 的样片，否则返回 400， 提示 must be a draft task with status 'succeeded'。
• 样片 ID 从样片的 created_at 起算有效期：2026-10-28 10:00（UTC+8）及之后创建的为 14 天， 此前创建的为 7 天。任务保留期仍是 7 天（见 5.5 节），样片预览请在 7 天内下载。

5. 查询任务

5.1 接口

GET https://api.topview.ai/cn/api/v3/contents/generations/tasks/{id}

{id} 接受：

• 创建接口返回的上游任务 ID（task_* 开头）
• 平台内部任务 ID（X-Topview-Request-Id）

查询响应中的 upstream_task_id（cgt-*）不能用于本接口查询。

5.2 请求示例

curl -X GET \
  'https://api.topview.ai/cn/api/v3/contents/generations/tasks/task_H6q96265lFuQOt2fIO8F2DBgWqmBv2Gl' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey'

5.3 任务状态

状态取值：queued、running、succeeded、failed、cancelled。 拿到 succeeded 时，video_url 已经可以下载。

5.4 成功响应

{
  "id": "task_H6q96265lFuQOt2fIO8F2DBgWqmBv2Gl",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://上游签名地址/video.mp4"
  },
  "usage": {
    "completion_tokens": 25600,
    "total_tokens": 25600
  },
  "upstream_task_id": "cgt-20260902145633-tjvgp",
  "created_at": 1788300000,
  "updated_at": 1788300300
}

5.5 时效限制

收到 succeeded 后请尽快下载到自己的存储。

产物为 MP4 容器 + H.265 / HEVC 编码。Chrome / Firefox 对 MP4 中的 HEVC 支持并不普遍， 若面向浏览器播放，建议转存时一并转码为 H.264，不要把上游地址直接交给前端。

5.6 任务不存在

任务不存在、格式非法、任务不属于当前账号或属于另一条通道时，统一返回 HTTP 404：

{
  "error": {
    "code": "ResourceNotFound",
    "message": "The specified resource `被查询的ID` is not found. Request id: 示例请求ID",
    "param": "",
    "type": "NotFound"
  }
}

超出上游保留期的任务是例外：这种查询会回源，上游响应原样透传给你， 形状与上面不同——HTTP 状态码是 400，没有 error 对象，错误码在根层：

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

因此判断「任务已无法取回」时不要只解析 error.code：请同时认 404 的 error.code = ResourceNotFound 与 400 的根层 code = task_not_exist。 只按前者写解析，在这条路径上会取到空值。两种形状语义相同，都表示任务再也取不回来。

6. 计费规则

按响应中的 usage.completion_tokens 计费：

原价积分 = usage.completion_tokens × 每百万 token 单价 ÷ 1,000,000
最终扣费积分 = 原价积分 × 账号折扣率

结果保留 6 位小数，四舍五入。1 平台积分 = 1 元人民币。

单位为积分（元）/ 百万 token，为标准价，2.0 系列取值来自火山方舟中国区官网人民币价目表。 单价按分辨率分档，且并非随分辨率单调递增——doubao-seedance-2-0-260128 的 4k 档 每百万 token 单价低于它自己的 480p/720p 档。 你账号生效的模型折扣可在 Overview 页的 Model discounts 查看，未列出的 model 按标准价计费。

• 不传 resolution 时按上游默认档（720p）计费。
• 请求 content 出现 type: "video_url" 时使用“含视频输入”单价。
• 样片模式（4.6 节）两步独立计费：样片按 480p 档计费，与普通 480p 一致；成片按 1080p 档计费， 单价列看样片请求是否含视频输入，输入视频时长也按样片计算，样片本身不计入 token。
• failed、cancelled 任务不扣费。
• succeeded 后按 usage 后置扣费，同一任务只扣一次。
• 首次扣费保存价格与折扣快照，后续价格调整不影响该任务。
• 扣上费才交付：扣上才返回 succeeded 与视频地址、发送成功回调，扣费未完成时查询仍返回 running。
• 扣费时余额不足，查询返回 HTTP 402 AccountOverdueError，不返回视频。充值后再查询即补扣并交付。

7. 并发与限流

本通道的并发额度与国际版通道独立，且必须由运营人员显式开通。 额度用满或查询过于频繁时返回 HTTP 429，错误码 RateLimitExceeded。 轮询间隔请不低于 15 秒，并使用指数退避处理 429。

8. 素材库

把常用图片存到平台侧，之后在 content 里用 asset://{assetId} 引用， 避免每次请求都上传 Base64。本通道的素材库与国际版通道完全独立， 两边素材互不可见，素材 ID 不能跨通道使用，额度也要分别开通。

8.1 接口形状

Action 放在 query，参数放在 JSON 请求体，鉴权仍用同一把 Topview API Key：

POST https://api.topview.ai/cn?Action=CreateAssetGroup&Version=2024-01-01
Authorization: Bearer sk-你的TopviewAPIKey
Content-Type: application/json

注意路径是 /cn，国际版素材接口在根路径 /。

8.2 开放的 Action

素材组：CreateAssetGroup、GetAssetGroup、ListAssetGroups、 UpdateAssetGroup、DeleteAssetGroup。

素材：CreateAsset、GetAsset、ListAssets、UpdateAsset、DeleteAsset。

真人认证：CreateVisualValidateSession、GetVisualValidateResult，见 8.6 节。

其他 Action 返回 InvalidActionOrVersion。

8.3 请求示例

curl -X POST \
  'https://api.topview.ai/cn?Action=CreateAssetGroup&Version=2024-01-01' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{"Name": "我的素材组", "Description": "产品图"}'

curl -X POST \
  'https://api.topview.ai/cn?Action=CreateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "GroupId": "上一步返回的Id",
    "AssetType": "Image",
    "URL": "https://example.com/product.png",
    "Name": "产品主图"
  }'

拿到素材 Id 后即可在本通道的视频生成请求里写 "url": "asset://素材Id"。

8.4 响应形状

成功时结果在 Result 下；失败时错误在 ResponseMetadata.Error 下， 与视频接口的顶层 error 信封不同，请分别处理。

{
  "ResponseMetadata": { "RequestId": "示例请求ID", "Action": "CreateAssetGroup" },
  "Result": { "Id": "素材组Id", "Name": "我的素材组" }
}

8.5 隔离与限额

• 素材按账号 + 通道隔离。操作他人素材、或跨通道操作自己的素材， 均返回 ResourceNotFound，与素材不存在完全同形。
• 列表只返回你在本通道下的素材，TotalCount 也只统计这一部分。 PageSize 上限默认 50，超出会被收敛。
• 素材数、素材组数、素材接口并发数三项额度逐账号逐通道单独约定。 用满返回 QuotaExceeded，并发超限返回 FlowLimitExceeded。
• 素材能力需按通道单独开通。未开通时返回 QuotaExceeded， 提示 asset quota is not configured for this account，重试无用，请联系商务。
• 审核未通过的素材会被平台定期回收；审核通过的素材不会被自动删除。

8.6 真人素材

含真人人像的素材需先完成真人活体认证，再上传到认证返回的 LivenessFace 素材组。 接口与火山官方 CreateVisualValidateSession / GetVisualValidateResult 同形，路径加 /cn 前缀。

1. 创建认证会话，拿到 BytedToken 和 H5Link：

curl -X POST \
  'https://api.topview.ai/cn?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{"CallbackURL": "https://your-domain.example.com/face-result"}'

CallbackURL 可选，是用户在 H5 点「完成」后浏览器跳转的页面，不是服务端回调。

1. 让被认证的真人本人在约 15 分钟内用手机打开 H5Link 完成认证。
2. 每 3～5 秒查询一次结果，直到 Result.GroupId 非空：

curl -X POST \
  'https://api.topview.ai/cn?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{"BytedToken": "上一步返回的BytedToken"}'

认证未完成时 GroupId 为空串；认证未通过返回 VisualValidateFailed，会话过期返回 VisualValidateSessionExpired，两者都需要重新创建会话。

1. 用 CreateAsset 把与认证本人一致的图片或视频上传到该 GroupId，Active 后用 asset://素材Id 引用。

真人素材组计入素材组额度，并出现在 ListAssetGroups（GroupType = LivenessFace）中。

9. 常见错误

排查问题时请提供 X-Topview-Request-Id、创建接口返回的 task_* ID，并注明调用的是 /cn 通道。不要提供 API Key。

10. 接入注意事项

• 路径必须带 /cn 前缀，素材接口同样如此。
• 不要暴露 API Key。
• 务必记录 X-Topview-Request-Id。
• 收到 succeeded 后尽快下载视频。
• 轮询间隔不低于 15 秒，并保留轮询作为回调的兜底。
• 请求体上限 10 MB。
• 400、401、402、404 等确定性错误不应自动重试。
• 样片转成片时只传 model、一个 draft_task 项和 "resolution": "1080p"，提示词、素材、时长、比例等不要再传。