# 望月号池视频生成 API

本文档用于第三方服务端接入望月豆包号池。公开模型只有 `seedance2.0fast` 和 `seedance2.0mini`。

## 1. 接口地址

```text
https://1456719883-78ndn27wdv.ap-guangzhou.tencentscf.com
```

## 2. 注册、凭证和鉴权

1. 在开发者站注册并登录账号。
2. 在“生产凭证”区域创建专属 API 客户端。
3. 只在创建或轮换时保存返回的 `keyId` 和 `secret`，Secret 只显示一次。
4. 第三方请求必须从自己的服务端发出，不要把 Secret 放进浏览器、App 或前端代码。

每个请求携带：

```text
X-Wangyue-Key-Id: YOUR_KEY_ID
X-Wangyue-Timestamp: 1776936222
X-Wangyue-Nonce: a-unique-random-string
X-Idempotency-Key: task-20260819-0001
X-Wangyue-Signature: YOUR_HMAC_SHA256_SIGNATURE
Content-Type: application/json
```

签名原文为以下 6 行，不能省略空行或改变顺序：

```text
METHOD
PATH_WITH_SORTED_QUERY
TIMESTAMP
NONCE
IDEMPOTENCY_KEY
SHA256(STABLE_JSON_BODY)
```

使用 `secret` 做 HMAC-SHA256，输出小写十六进制。`STABLE_JSON_BODY` 是递归按键名排序、数组顺序保持不变后的 JSON。

## 3. 查看模型和价格

```http
GET /v1/pool/api/models
```

只使用以下两个号池模型：

| 模型 ID | 说明 | 默认时长 |
| --- | --- | --- |
| `seedance2.0fast` | 速度优先 | 10 秒 |
| `seedance2.0mini` | 轻量模型 | 15 秒 |

价格以 `/v1/pool/api/models` 的 `fixedPriceMicros` 返回值为准。管理员在管理中心调整价格后，新任务的预扣、结算和开发者站展示会使用最新价格版本。

## 4. 文生视频

```http
POST /v1/pool/api/tasks
```

```json
{
  "type": "doubao_video",
  "idempotencyKey": "task-20260819-0001",
  "payload": {
    "projectId": "demo-project",
    "episodeId": "episode-1",
    "shotId": "shot-1",
    "rowId": "shot-1",
    "prompt": "雨夜霓虹街道，镜头缓慢推进，电影感光影",
    "settings": {
      "model": "seedance2.0fast",
      "duration": 10,
      "aspectRatio": "16:9",
      "resolution": "720P"
    }
  }
}
```

`settings.model` 必须是两个公开模型 ID 之一。`idempotencyKey` 在重试时必须保持不变，否则会创建新任务。

## 5. 图生视频

图片不能直接把公网 URL 塞进任务。先申请号池素材租约：

```http
POST /v1/pool/api/assets/input/lease
```

```json
{
  "fileName": "reference.jpg",
  "contentType": "image/jpeg",
  "byteSize": 123456
}
```

按照租约返回的上传地址上传文件，再调用：

```http
POST /v1/pool/api/assets/{assetId}/confirm
```

随后在任务里使用素材 ID：

```json
{
  "type": "doubao_video",
  "idempotencyKey": "task-20260819-0002",
  "payload": {
    "projectId": "demo-project",
    "rowId": "shot-2",
    "prompt": "保持人物外貌和服装一致，自然缓慢走动",
    "referenceAssetIds": ["ASSET_ID_FROM_UPLOAD_LEASE"],
    "settings": {
      "model": "seedance2.0mini",
      "duration": 15,
      "aspectRatio": "9:16",
      "resolution": "720P",
      "referenceMode": "start_frame"
    }
  }
}
```

支持的画面比例为 `16:9`、`9:16`、`4:3`、`3:4`、`1:1`；分辨率为 `720P`；参考图片最多 9 张。

## 6. 查询任务状态

创建任务后保存返回的任务 ID：

```http
GET /v1/pool/api/tasks/{taskId}
```

状态包括：`queued`、`leased`、`review_required`、`completed`、`failed`、`cancelled`。

## 7. 下载视频

任务状态为 `completed` 后：

```http
GET /v1/pool/api/tasks/{taskId}/result
```

接口返回一次性或短时有效的下载响应，第三方服务应立即保存到自己的对象存储或本地磁盘。

## 8. Webhook（可选）

不配置 Webhook 不影响提交、轮询和下载。需要服务端推送时，在网站的 Webhook 区域填写公开 HTTPS 地址并启用。回调签名使用页面返回的 Webhook Secret，回调请求头为：

```text
X-Wangyue-Webhook-Timestamp
X-Wangyue-Webhook-Id
X-Wangyue-Webhook-Signature
```

## 9. 推荐接入流程

注册账号 → 创建生产 Key → 服务端生成 HMAC 签名 → 提交任务 → 保存任务 ID → 轮询任务状态 → `completed` 后下载并立即保存结果。生产凭证默认支持 8 个并发任务、每日 500 条任务，实际限制以凭证详情为准。