# ComputeHub 开发者接入指南

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

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

---

## 1. 快速开始

### 1.1 获取凭证

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

```http
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` |

将官方 SDK / HTTP 客户端的 Host 换成上表即可；路径保持 `/contents/generations/tasks` 等不变。

### 1.3 最小示例（文生视频）

```bash
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`，成片 URL 在 `content.video_url`（火山临时链接，约 24h）。平台会异步转存到私有 OSS；推荐用 `GET …/tasks/{id}/video` 取 OSS 签名 URL。

**Webhook / callback_url**：经网关创建任务时，若请求体未带 `callback_url`，平台会自动注入 `{PUBLIC_BASE_URL}/api/v3/webhooks/ark/tasks`，任务终态秒级结算用量。业务方无需在火山控制台配置全局回调。

---

## 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` | 预扣金额（分） |

响应 **Body** 与火山 Ark 兼容（创建成功通常仅含 `id`）。

### 2.3 常见 HTTP 状态

| 状态 | 含义 |
|------|------|
| 200 | 成功 |
| 401 | Key 无效 / 已吊销 |
| 402 | 申请单额度不足（`application quota exhausted`） |
| 403 | 无权限（如跨申请单引用素材） |
| 409 | 素材未就绪（未 Active） |
| 429 | QPS / 日调用上限 |
| 4xx/5xx | 参数错误或上游错误（多为 Ark 风格 JSON） |

---

## 3. 模型与参数

### 3.1 模型 ID

平台接受友好 SKU，会自动映射为方舟带日期的模型 ID：

| 平台 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。

### 3.2 常用字段

与官方创建视频任务一致，例如：

- `model` / `duration` / `resolution` / `ratio`
- `content[]`：`text`、`image_url`、`video_url` 等
- `callback_url` 等扩展字段会原样转发给上游；**未传时**网关自动注入平台 Webhook URL（见 §7）

以官方 [创建视频生成任务](https://www.volcengine.com/docs/82379/1520757) 为准；平台做计量与额度管控。

### 3.3 与直连火山的差异（交付）

| | 直连火山 | 经算力平台 |
|---|---|---|
| 成片地址 | 仅 `content.video_url`（~24h） | 临时 URL + **OSS 归档** |
| 长期取片 | 业务自行转存 | `GET …/tasks/{id}/video` 签名 URL |
| 结算 | 无 | 预扣 → Webhook 实扣 / 轮询兜底 |
| callback | 每次请求自填 | **默认自动注入** |

---

## 4. 垫图 / 垫视频

### 4.1 何时需要

- 漫剧、多镜头：**人物长相 / 服装一致**
- 电商：商品外观贴近实物图
- 指定场景、构图、风格
- 图生视频（静帧驱动）

纯文生、对一致性要求不高时，可不传垫图。

### 4.0 本地图片 / 视频（平台扩展）

火山与平台生成接口都不接受本机路径。平台提供上传接口，把文件存到 OSS 并返回**公网可拉取 URL**，再用于直链或入库：

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

拿到 `url` 后：
- 直链：写入 `image_url.url`
- 或再 `POST /assets` 入库得到 `asset://`

限制：单文件 ≤ 30MB；`image/*`、`video/*`、`audio/*`（mp3/wav 等）。返回的 URL 为 OSS **私有对象签名链接**（约 7 天有效），足够入库与生成拉取；勿当作永久公开地址。

### 4.1 公网 HTTPS 直链

参考图必须公网可访问（火山侧能拉取）。在创建任务的 `content` 中直接写：

```json
{
  "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.3 方式 B：素材库 `asset://`（推荐复用 / 真人合规）

平台封装了火山管控面素材能力。业务仍用 **平台 Bearer Key**，不必持有火山 AK/SK。

**步骤 1 — 入库**

```bash
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"
  }'
# → {"id":"asset-…","asset_url":"asset://asset-…","status":"Pending",…}
```

**步骤 2 — 轮询至 Active**

```bash
curl -s -H "Authorization: Bearer $KEY" "$BASE/assets/asset-…"
# status: Pending → Active（失败则为 Failed）
```

**步骤 3 — 生成时引用**

```json
{
  "type": "image_url",
  "image_url": { "url": "asset://asset-…" },
  "role": "reference_image"
}
```

#### 与直连火山的差异（重要）

| 能力 | 直连火山 | 算力平台 |
|------|----------|----------|
| 视频生成 | Bearer + `/api/v3/contents/generations/tasks` | **一致**（换域名与 Key） |
| 素材入库 | 管控面 AK/SK `CreateAsset` | 平台 `POST /api/v3/assets`（Bearer） |
| `asset://` 引用 | 同项目 API Key | **一致** |

`asset_type` 建议：`Image` / `Video` / `Audio`。

未 Active 前引用会失败；素材归属当前申请单，不可跨团队盗用他人 `asset_id`。

---

## 5. API 一览

| 方法 | 路径 | 说明 | 计费 |
|------|------|------|------|
| POST | `/contents/generations/tasks` | 创建生成任务 | 预扣额度 |
| GET | `/contents/generations/tasks/{id}` | 查询任务 | — |
| GET | `/contents/generations/tasks/{id}/video` | 获取 OSS 落盘成片的签名 URL | — |
| POST | `/media/upload` | 上传本地垫图/垫视频/参考音频 → 公网 URL | 不计费 |
| POST | `/assets` | 上传素材（公网 URL） | 不计费 |
| GET | `/assets/{id}` | 查询素材状态 | 不计费 |

兼容别名（不推荐新接入使用）：`/v1/…`、`/gw/…`、`/sd/assets`。

健康检查（无需 Key）：`GET https://computehub.zhikecn.com/healthz`（经管理面）或网关侧探测。

---

## 6. 额度、吊销与风控

- 创建任务时按估价 **预扣**；成功确认、失败回滚。
- 额度用尽 → **402**。
- Key 被管理员吊销 → **401**。
- 申请单冻结 → 无法调用。
- 单 Key 有 QPS、日调用上限（签发时配置）。

---

## 7. 成片与落盘

1. 任务成功后上游返回临时 `content.video_url`（约 24h）。
2. 平台 Worker 自动转存私有 OSS（通常数分钟内完成）。
3. **推荐取片** — 专用接口（OSS 签名 URL，约 1h 有效，可重复请求）：

```bash
curl -s -H "Authorization: Bearer $KEY" \
  "$BASE/contents/generations/tasks/cgt-…/video"
# → {"task_id":"…","url":"https://…","expires_at":"…","source":"oss_archive"}
```

4. 或轮询 `GET …/tasks/{id}`：落盘完成后响应附带 `archived_video_url` / `archived_video_expires_at`。
5. 管理员可在控制台 **用量统计 → 调用明细 → 预览/下载**。

`404` = 落盘未完成；`410` = 上游链在转存前已过期。

### 7.1 结算时序

```
创建任务 → 预扣 → 方舟终态 Webhook（自动 callback_url）→ 实扣/回滚 → Worker 转存 OSS
```

Webhook 丢失时 Worker 宽限 2min 后退避轮询兜底。

---

## 8. 推荐接入流程

```
申请额度 → 拿到 ch_live_ Key
    ↓
（可选）POST /assets → 轮询 Active
    ↓
POST /contents/generations/tasks
    ↓
轮询 GET …/tasks/{id} 至 succeeded / failed
    ↓
GET …/tasks/{id}/video 取 OSS 成片（或先用 content.video_url）
```

漫剧人物一致性建议：固定角色定妆图 → 入库一次拿 `asset://` → 各集复用同一 ID。

---

## 9. 自检清单

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

---

## 10. 联系与支持

- 额度申请、扩容、Key 吊销：平台管理员  
- 控制台：`https://computehub.zhikecn.com/`  
- 试玩页：控制台 → **Seedance 试玩**（粘贴平台 Key 即可联调）

---

*本文档由统一算力平台维护。接口以线上行为为准；模型 ID 可能随火山发版更新。*