ComputeHub 开发者接入指南

统一算力平台 · Seedance 视频生成网关
Base URL：https://computehub.zhikecn.com/api/v3 · 文档版本：2026-08-25

业务方只需把火山方舟的域名换成算力平台域名，把官方 ark-… Key 换成平台下发的 ch_live_… Key。路径与请求体尽量与方舟 Ark 兼容。

1. 快速开始

1.1 获取凭证

联系平台管理员，填写业务信息并申请额度。
管理员签发平台 API Key（形如 ch_live_…），明文只展示一次，请妥善保存。
调用时使用：Authorization: Bearer ch_live_xxxxxxxx

1.2 Base URL

环境	Base URL
生产	`https://computehub.zhikecn.com/api/v3`
对比：火山官方	`https://ark.cn-beijing.volces.com/api/v3`

1.3 最小示例（文生视频）

export KEY='ch_live_你的平台Key'
export BASE='https://computehub.zhikecn.com/api/v3'

curl -s -X POST "$BASE/contents/generations/tasks" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "duration": 5,
    "resolution": "720p",
    "content": [
      { "type": "text", "text": "一只橘猫在阳光下散步，写实电影感" }
    ]
  }'
# → {"id":"cgt-…"}

curl -s -H "Authorization: Bearer $KEY" \
  "$BASE/contents/generations/tasks/cgt-…"

成功时 status 为 succeeded，成片在 content.video_url（临时 ~24h）。推荐用 GET …/tasks/{id}/video 取 OSS 签名 URL。网关会自动注入 callback_url，无需手填或火山控制台配置。

2. 鉴权与错误码

2.1 请求头

Header	必填	说明
`Authorization`	是	`Bearer <平台Key>`
`Content-Type`	有 Body 时	`application/json`
`X-Channel`	否	渠道标识
`X-Trace-Id`	否	业务追踪 ID

2.2 平台扩展响应头

Header	说明
`X-ComputeHub-Application-Id`	申请单 ID
`X-ComputeHub-Usage-Id`	用量事件 ID
`X-ComputeHub-Reserved-Cents`	预扣金额（分）

2.3 常见 HTTP 状态

状态	含义
200	成功
401	Key 无效 / 已吊销
402	额度不足
403	无权限（如跨申请单引用素材）
409	素材未 Active
429	QPS / 日调用上限

3. 模型

平台 SKU	上游模型（可被环境覆盖）
`seedance-2.0`	`doubao-seedance-2-0-260128`
`seedance-2.0-mini`	`doubao-seedance-2-0-mini-260615`
`seedance-2.5`	`doubao-seedance-2-5-260628`

也可直接传官方 doubao-seedance-… 模型 ID。

4. 垫图 / 垫视频

何时需要：漫剧人物一致、商品外观、指定场景/风格、图生视频。纯文生可不传。

4.0 本地图片（平台扩展）

生成接口不接受本机路径。先调用 POST /media/upload（multipart 字段 file）上传到 OSS，返回公网 URL，再用于直链或 /assets 入库。

curl -s -X POST "$BASE/media/upload" \
  -H "Authorization: Bearer $KEY" \
  -F "file=@./character.png"
# → {"url":"https://….aliyuncs.com/refs/…", …}

4.1 公网 HTTPS 直链

{
  "model": "seedance-2.0",
  "duration": 5,
  "resolution": "720p",
  "content": [
    { "type": "text", "text": "根据参考图，角色转身微笑" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/character.png" },
      "role": "reference_image"
    }
  ]
}

4.2 素材库 asset://

POST /assets 上传公网 URL → 得到 asset-…
GET /assets/{id} 轮询至 Active
生成时 image_url.url = "asset://asset-…"

curl -s -X POST "$BASE/assets" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/character.png","asset_name":"hero-v1","asset_type":"Image"}'

说明：直连火山素材库需 AK/SK 管控面；平台已封装为 Bearer /api/v3/assets，业务无需持有火山 AK/SK。视频生成路径与官方一致。

5. API 一览

方法	路径	说明	计费
POST	`/contents/generations/tasks`	创建任务	预扣
GET	`/contents/generations/tasks/{id}`	查询任务	—
GET	`/contents/generations/tasks/{id}/video`	OSS 落盘成片签名 URL	—
POST	`/assets`	上传素材	不计费
GET	`/assets/{id}`	查询素材	不计费

6. 额度与风控

创建任务按估价预扣；成功确认、失败回滚。
额度用尽 → 402；Key 吊销 → 401；申请单冻结不可调用。
单 Key 有 QPS、日调用上限。

7. 成片落盘

上游临时 video_url（约 24h）。
平台 Worker 转存私有 OSS（通常数分钟内）。
业务方：任务查询响应可含 archived_video_url，或调用 GET …/tasks/{id}/video 获取签名 URL（约 1h 有效，可重复请求）。
管理端「用量统计 → 下载」经平台代理获取成片。

curl -s -H "Authorization: Bearer $KEY" \
  "$BASE/contents/generations/tasks/cgt-…/video"

8. 推荐流程

申请额度 → 拿到 ch_live_ Key
   ↓
（可选）POST /assets → 轮询 Active
   ↓
POST /contents/generations/tasks
   ↓
轮询 GET …/tasks/{id} 至终态
   ↓
使用 video_url 或管理端下载成片

漫剧人物一致性：定妆图入库一次 → 各集复用同一 asset://。

9. 自检清单

Base URL 为 https://computehub.zhikecn.com/api/v3
使用平台 ch_live_ Key，而非火山 ark- Key
垫图公网可达，或已 Active 的 asset://
正确处理 401 / 402 / 429
Key 勿写入公开前端仓库

控制台：https://computehub.zhikecn.com/ · 本文档由统一算力平台维护。