豆包视频（Doubao）模型格式

# 豆包视频（Doubao）模型格式（视频生成能力）

豆包视频提交 /v1/videos/generations
豆包视频任务查询 /v1/videos/generations/{task_id}

# 视频生成 API 文档（V2）

> 协议风格兼容 OpenAI 异步任务模式（提交任务 + 轮询查询）。

---

## 1. 基础信息

- **Base URL**：`https://api.cxsee.com`
- **认证方式**：Bearer Token
- **鉴权 Header**：
  - `Authorization: Bearer <YOUR_API_KEY>`
- **内容类型**：
  - 请求：`Content-Type: application/json`
  - 响应：`application/json`

---

## 2. 接口总览

| 功能 | 方法 | 路径 |
|---|---|---|
| 提交视频生成任务 | `POST` | `/v2/videos/generations` |
| 查询任务状态（标准） | `GET` | `/v2/videos/generations/{task_id}` |
| 查询任务状态（兼容） | `GET` | `/v2/videos/{task_id}` |

---

## 3. 提交任务

## `POST /v2/videos/generations`

创建一个视频生成异步任务，返回 `task_id`。

### 请求头

```http
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json
```

### 请求体（最小必填）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型名，例如 `doubao-seedance-1-0-lite-t2v-250428` |
| `prompt` | string | 是 | 生成提示词 |

### 请求示例（cURL）

```bash
curl -i --request POST "https://api.cxsee.com/v2/videos/generations" \
  --header "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedance-1-0-lite-t2v-250428",
    "prompt": "A cat walking in snow, cinematic"
  }'
```

### 成功响应示例（`200 OK`）

```json
{
  "id": "cgt-20260308010858-fw465",
  "task_id": "cgt-20260308010858-fw465",
  "object": "video",
  "model": "doubao-seedance-1-0-lite-t2v-250428",
  "status": "queued",
  "progress": 0,
  "created_at": 1772903341
}
```

---

## 4. 查询任务

## `GET /v2/videos/generations/{task_id}`

根据任务 ID 查询状态与结果。

### 请求示例（cURL）

```bash
curl -i --request GET "https://api.cxsee.com/v2/videos/generations/cgt-20260308010858-fw465" \
  --header "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"
```

### 成功响应示例（`200 OK`）

```json
{
  "id": "cgt-20260308010858-fw465",
  "task_id": "cgt-20260308010858-fw465",
  "object": "video",
  "model": "doubao-seedance-1-0-lite-t2v-250428",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1772903341,
  "completed_at": 1772910421,
  "metadata": {
    "url": "https://xxx.mp4"
  }
}
```

> 当 `metadata.url` 可用时，可直接用于下载/播放。

---

## 5. 状态字段说明

| 字段 | 说明 |
|---|---|
| `status=queued` | 任务已排队，尚未开始或状态同步中 |
| `status=running` | 任务执行中 |
| `status=succeeded` | 任务成功，可使用 `metadata.url` |
| `status=failed` | 任务失败，查看错误信息 |

### 客户端建议（重要）

部分上游在短时间内可能出现状态延迟同步。建议客户端判定成功时优先使用以下条件：

1. `status == "succeeded"`，或
2. `progress == 100` 且 `metadata.url` 非空

---

## 6. 错误码与错误响应

统一错误结构示例：

```json
{
  "error": {
    "message": "model is required",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}
```

### 常见错误码

| HTTP 状态码 | code | 说明 |
|---|---|---|
| `400` | `invalid_parameter` | 参数错误（如缺少 model/prompt） |
| `401` | `invalid_api_key` | API Key 无效或缺失 |
| `404` | `task_not_found` | 任务不存在 |
| `429` | `rate_limit_exceeded` | 请求过快或配额不足 |
| `500` | `internal_error` | 服务端/上游异常 |

### 错误示例

#### 400 参数错误

```json
{
  "error": {
    "message": "model is required",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}
```

#### 401 鉴权失败

```bash
curl -i --request GET "https://api.cxsee.com/v2/videos/generations/cgt-xxx" \
  --header "Authorization: Bearer sk-invalid"
```

```json
{
  "error": {
    "message": "invalid api key",
    "type": "unauthorized_error",
    "code": "invalid_api_key"
  }
}
```

#### 404 任务不存在

```json
{
  "error": {
    "message": "task not found",
    "type": "not_found_error",
    "code": "task_not_found"
  }
}
```

#### 429 限流/配额不足

```json
{
  "error": {
    "message": "rate limit exceeded or insufficient quota",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}
```

#### 500 服务异常

```json
{
  "error": {
    "message": "upstream service unavailable",
    "type": "server_error",
    "code": "internal_error"
  }
}
```

---

## 7. 一键测试（提交 + 查询）

> 依赖 `jq`

```bash
TASK_ID=$(curl -sS --request POST "https://api.cxsee.com/v2/videos/generations" \
  --header "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{"model":"doubao-seedance-1-0-lite-t2v-250428","prompt":"A cat walking in snow, cinematic"}' \
  | jq -r '.task_id // .id')

echo "TASK_ID=$TASK_ID"

curl -sS --request GET "https://api.cxsee.com/v2/videos/generations/${TASK_ID}" \
  --header "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" | jq
```

---

## 8. 最佳实践

- 轮询间隔建议：`2~5 秒`
- 建议最大轮询时长：`2~10 分钟`（按业务需要）
- 保留响应头 `x-oneapi-request-id`，便于技术支持排查
- 遇到 `429` 使用指数退避重试（如 1s / 2s / 4s / 8s）

---

上一篇：火山豆包（Doubao）绘画模型格式下一篇：Responses API与Chat API对比