豆包视频（Doubao）模型格式

# 豆包视频（Doubao）生成 API 文档

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

「豆包视频生成 API 文档」，包含：创建视频任务、查询任务状态、获取视频地址、字段说明、完整 CURL 示例。

---

# 豆包视频生成 API 文档

## 1. 接口概览

该接口用于调用豆包视频生成模型，根据文本提示词生成视频。

当前示例模型：

```text
doubao-seedance-2-0-fast-260128
```

完整流程：

```text
提交生成任务  ->  返回 task_id  ->  查询任务状态  ->  获取 video_url
```

---

# 2. 鉴权方式

所有接口都需要在请求头中携带 API Key。

```http
Authorization: Bearer YOUR_API_KEY
```

示例：

```bash
-H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'
```

注意：不要在公开环境暴露真实 API Key。

---

# 3. 创建视频生成任务

## 请求地址

```http
POST https://api.cxsee.com/v1/videos/generations
```

## 请求 Headers

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 请求 Body

```json
{
  "model": "doubao-seedance-2-0-fast-260128",
  "prompt": "一只橘猫在阳光下午睡，微风吹动窗帘，画面温馨治愈",
  "duration": 5,
  "resolution": "480p",
  "ratio": "16:9"
}
```

## CURL 示例

```bash
curl -X POST https://api.cxsee.com/v1/videos/generations \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "一只橘猫在阳光下午睡，微风吹动窗帘，画面温馨治愈",
    "duration": 5,
    "resolution": "480p",
    "ratio": "16:9"
  }'
```

---

# 4. 创建任务返回示例

```json
{
  "created_at": 1782690393,
  "id": "cgt-20260629074633-8x7r2",
  "model": "doubao-seedance-2-0-fast-260128",
  "object": "video",
  "progress": 0,
  "status": "queued",
  "task_id": "cgt-20260629074633-8x7r2"
}
```

## 返回字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 任务 ID |
| `task_id` | string | 任务 ID，查询任务时使用 |
| `model` | string | 使用的视频生成模型 |
| `object` | string | 对象类型，这里为 `video` |
| `status` | string | 任务状态，初始一般为 `queued` |
| `progress` | number/string | 任务进度 |
| `created_at` | number | 创建时间戳 |

---

# 5. 查询视频生成任务

## 请求地址

```http
GET https://api.cxsee.com/v1/videos/generations/{task_id}
```

其中 `{task_id}` 替换为创建任务时返回的任务 ID。

例如：

```text
cgt-20260629074633-8x7r2
```

## CURL 示例

```bash
curl -X GET https://api.cxsee.com/v1/videos/generations/cgt-20260629074633-8x7r2 \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'
```

---

# 6. 查询任务返回示例

你当前接口返回的是状态信息：

```json
{
  "data": {
    "created_at": 1782690393,
    "error": "",
    "id": "cgt-20260629074633-8x7r2",
    "model": "doubao-seedance-2-0-fast-260128",
    "object": "generation",
    "progress": "100%",
    "status": "SUCCESS",
    "task_id": "cgt-20260629074633-8x7r2",
    "updated_at": 1782690393
  },
  "message": "",
  "success": true
}
```

## 返回字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| `success` | boolean | 请求是否成功 |
| `message` | string | 接口消息 |
| `data.id` | string | 任务 ID |
| `data.task_id` | string | 任务 ID |
| `data.model` | string | 使用的模型 |
| `data.status` | string | 任务状态 |
| `data.progress` | string | 任务进度 |
| `data.error` | string | 错误信息，成功时为空 |
| `data.created_at` | number | 创建时间 |
| `data.updated_at` | number | 更新时间 |

---

# 7. 任务状态说明

| 状态 | 说明 |
|---|---|
| `queued` | 任务排队中 |
| `processing` | 任务生成中 |
| `SUCCESS` | 任务成功 |
| `FAILED` | 任务失败 |
| `succeeded` | 上游任务成功状态 |
| `failed` | 上游任务失败状态 |

你当前任务状态：

```text
SUCCESS
```

进度：

```text
100%
```

说明视频已经生成完成。

---

# 8. 完整任务 JSON 示例

你的内部任务完整信息如下，已整理为结构化示例：

```json
{
  "id": 173,
  "created_at": 1782690393,
  "updated_at": 1782690393,
  "task_id": "cgt-20260629074633-8x7r2",
  "external_task_id": "cgt-20260629074633-8x7r2",
  "platform": "54",
  "user_id": 1,
  "group": "default",
  "channel_id": 105,
  "channel_name": "",
  "quota": 1,
  "action": "generate",
  "status": "SUCCESS",
  "fail_reason": "",
  "submit_time": 1782690393,
  "start_time": 0,
  "finish_time": 1782690519,
  "progress": "100%",
  "properties": {
    "upstream_model_name": "doubao-seedance-2-0-fast-260128",
    "origin_model_name": "doubao-seedance-2-0-fast-260128",
    "query_action": "video",
    "submit_path": "/v1/videos/generations",
    "image_n": 1,
    "duration_seconds": 5
  },
  "data": {
    "id": "cgt-20260629074633-8x7r2",
    "seed": 78938,
    "draft": false,
    "model": "doubao-seedance-2-0-fast-260128",
    "ratio": "16:9",
    "usage": {
      "total_tokens": 108900,
      "completion_tokens": 108900
    },
    "status": "succeeded",
    "content": {
      "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx.mp4"
    },
    "duration": 5,
    "priority": 0,
    "created_at": 1782690393,
    "resolution": "720p",
    "updated_at": 1782690515,
    "service_tier": "default",
    "generate_audio": true,
    "framespersecond": 24,
    "execution_expires_after": 172800
  },
  "PreConsumedQuota": 0,
  "FinalQuota": 925650,
  "QuotaSettled": true,
  "BillingMode": "tiered_expr",
  "BillingExpr": "tier(\"视频生成\", c * 17)",
  "timestamp2string": "2026-06-29 07:46:33",
  "key": "173"
}
```

---

# 9. 获取视频下载地址

根据你提供的完整任务 JSON，生成完成后视频地址位于：

```json
data.content.video_url
```

也就是：

```text
https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx.mp4
```

示例字段：

```json
{
  "data": {
    "content": {
      "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx.mp4"
    }
  }
}
```

如果 API 查询接口完整返回了 `data.content.video_url`，客户端可以直接提取该字段播放或下载视频。

---

# 10. 下载生成的视频

如果已经拿到 `video_url`，可以使用 `curl` 下载：

```bash
curl -L "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx.mp4" -o output.mp4
```

如果 URL 很长，建议用引号包起来：

```bash
curl -L "完整的视频URL" -o doubao-video.mp4
```

---

# 11. 一次完整调用流程

## 第一步：创建任务

```json
{
  "id": "cgt-20260629074633-8x7r2",
  "task_id": "cgt-20260629074633-8x7r2",
  "status": "queued",
  "progress": 0
}
```

---

## 第二步：查询任务

```bash
curl -X GET https://api.cxsee.com/v1/videos/generations/cgt-20260629074633-8x7r2 \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'
```

```json
{
  "data": {
    "id": "cgt-20260629074633-8x7r2",
    "task_id": "cgt-20260629074633-8x7r2",
    "status": "SUCCESS",
    "progress": "100%",
    "model": "doubao-seedance-2-0-fast-260128"
  },
  "message": "",
  "success": true
}
```

---

## 第三步：获取视频 URL

如果接口返回完整数据，视频地址字段为：

```json
data.content.video_url
```

示例：

```json
{
  "data": {
    "status": "succeeded",
    "content": {
      "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx.mp4"
    }
  }
}
```

---

## 第四步：下载视频

```bash
curl -L "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx.mp4" -o output.mp4
```

---

# 12. 请求参数说明

| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
| `model` | string | 是 | `doubao-seedance-2-0-fast-260128` | 视频生成模型 |
| `prompt` | string | 是 | `一只橘猫在阳光下午睡...` | 视频提示词 |
| `duration` | number | 是 | `5` | 视频时长，单位秒 |
| `resolution` | string | 否 | `480p`、`720p` | 视频分辨率 |
| `ratio` | string | 否 | `16:9` | 视频比例 |

---

# 13. 响应结果关键字段说明

| 字段 | 说明 |
|---|---|
| `task_id` | 任务 ID，用于查询任务 |
| `status` | 任务状态 |
| `progress` | 任务进度 |
| `data.content.video_url` | 生成后的视频地址 |
| `data.duration` | 视频时长 |
| `data.resolution` | 实际生成分辨率 |
| `data.framespersecond` | 视频帧率 |
| `data.generate_audio` | 是否生成音频 |
| `data.usage.total_tokens` | 消耗量统计 |
| `finish_time` | 任务完成时间 |
| `fail_reason` | 失败原因 |

---
# 14. 注意事项
查询接口返回 SUCCESS 且 progress 为 100% 时，说明任务已完成。
真正
2. 真正的视频结果地址通常在完整任务数据的：

```text
data.content.video_url
```

3. `video_url` 一般是带签名的临时 URL，有有效期限制。
4. 示例中 `X-Tos-Expires=86400` 表示 URL 有效期约为 `86400` 秒，也就是 24 小时。
5. 如果视频 URL 过期，需要重新查询任务或让服务端重新生成签名 URL。
6. 不建议把 `video_url` 长期存储为永久下载地址。
7. API Key 请勿暴露到前端、小程序、App 客户端或公开代码仓库。
8. 你之前贴出的 API Key 已经泄露，建议尽快在后台重置。

---

# 15. 完整成功返回结构建议

建议查询任务接口在任务成功后直接返回视频结果，方便客户端使用。

## 推荐返回格式

```json
{
  "success": true,
  "message": "",
  "data": {
    "id": "cgt-20260629074633-8x7r2",
    "task_id": "cgt-20260629074633-8x7r2",
    "model": "doubao-seedance-2-0-fast-260128",
    "object": "generation",
    "status": "SUCCESS",
    "progress": "100%",
    "created_at": 1782690393,
    "updated_at": 1782690515,
    "content": {
      "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx.mp4"
    },
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "framespersecond": 24,
    "generate_audio": true,
    "usage": {
      "total_tokens": 108900,
      "completion_tokens": 108900
    }
  }
}
```

## 客户端重点读取字段

```text
data.status
data.progress
data.content.video_url
```

---

# 16. 失败返回示例

如果任务生成失败，可能返回：

```json
{
  "success": true,
  "message": "",
  "data": {
    "id": "cgt-20260629074633-8x7r2",
    "task_id": "cgt-20260629074633-8x7r2",
    "model": "doubao-seedance-2-0-fast-260128",
    "object": "generation",
    "progress": "100%",
    "status": "FAILED",
    "error": "generation failed",
    "created_at": 1782690393,
    "updated_at": 1782690519
  }
}
```

或者内部任务结构中：

```json
{
  "task_id": "cgt-20260629074633-8x7r2",
  "status": "FAILED",
  "fail_reason": "generation failed",
  "progress": "100%"
}
```

## 失败时应检查字段

| 字段 | 说明 |
|---|---|
| `status` | 任务状态 |
| `error` | 对外错误信息 |
| `fail_reason` | 内部失败原因 |
| `message` | 接口消息 |
| `task_id` | 问题排查用任务 ID |

---

# 17. HTTP 状态码建议

| HTTP 状态码 | 说明 |
|---|---|
| `200` | 请求成功 |
| `400` | 请求参数错误 |
| `401` | API Key 无效或未传 |
| `403` | 无权限访问该模型或任务 |
| `404` | 任务不存在 |
| `429` | 请求过于频繁或额度不足 |
| `500` | 服务端内部错误 |
| `502` | 上游服务错误 |
| `504` | 上游服务超时 |

---

# 18. 参数校验建议

创建任务时建议校验以下参数。

## model

必填，当前示例：

```text
doubao-seedance-2-0-fast-260128
```

## prompt

必填，不能为空。

示例：

```text
一只橘猫在阳光下午睡，微风吹动窗帘，画面温馨治愈
```

## duration

必填，单位为秒。

示例：

```json
{
  "duration": 5
}
```

建议支持值以实际模型能力为准，例如：

```text
5、10
```

## resolution

可选，视频分辨率。

示例：

```text
480p
720p
```

注意：你创建任务时传的是 `480p`，但完整任务 JSON 里返回的是：

```text
720p
```

这说明服务端或上游可能做了默认分辨率映射，文档里建议注明“实际分辨率以返回结果为准”。

## ratio

可选，视频宽高比。

示例：

```text
16:9
9:16
1:1
```

---

# 19. 轮询查询建议

视频生成是异步任务，创建任务后不要立即认为已经完成，需要轮询查询。

## 建议轮询逻辑

```text
1. 调用 POST /v1/videos/generations 创建任务
2. 获取 task_id
3. 每 3-5 秒调用一次 GET /v1/videos/generations/{task_id}
4. 如果 status 为 SUCCESS，读取 data.content.video_url
5. 如果 status 为 FAILED，读取 error 或 fail_reason
6. 如果长时间未完成，客户端提示用户稍后查看
```

## Shell 轮询示例

```bash
TASK_ID="cgt-20260629074633-8x7r2"
API_KEY="sk-xxxxxxxxxxxxxxxx"

while true; do
  curl -s -X GET "https://api.cxsee.com/v1/videos/generations/${TASK_ID}" \
    -H "Authorization: Bearer ${API_KEY}"

echo
  sleep 5
done
```

## 带 jq 的轮询示例

```bash
TASK_ID="cgt-20260629074633-8x7r2"
API_KEY="sk-xxxxxxxxxxxxxxxx"

while true; do
  RESPONSE=$(curl -s -X GET "https://api.cxsee.com/v1/videos/generations/${TASK_ID}" \
    -H "Authorization: Bearer ${API_KEY}")

STATUS=$(echo "$RESPONSE" | jq -r '.data.status')
  PROGRESS=$(echo "$RESPONSE" | jq -r '.data.progress')
  VIDEO_URL=$(echo "$RESPONSE" | jq -r '.data.content.video_url // empty')

echo "status=${STATUS}, progress=${PROGRESS}"

if [ "$STATUS" = "SUCCESS" ]; then
    echo "video_url=${VIDEO_URL}"
    break
  fi

if [ "$STATUS" = "FAILED" ]; then
    echo "$RESPONSE" | jq
    break
  fi

sleep 5
done
```

---

# 20. Python 调用示例

## 创建任务

```python
import requests

api_key = "sk-xxxxxxxxxxxxxxxx"

url = "https://api.cxsee.com/v1/videos/generations"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

payload = {
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "一只橘猫在阳光下午睡，微风吹动窗帘，画面温馨治愈",
    "duration": 5,
    "resolution": "480p",
    "ratio": "16:9",
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

## 查询任务

```python
import requests

api_key = "sk-xxxxxxxxxxxxxxxx"
task_id = "cgt-20260629074633-8x7r2"

url = f"https://api.cxsee.com/v1/videos/generations/{task_id}"

headers = {
    "Authorization": f"Bearer {api_key}",
}

response = requests.get(url, headers=headers)
print(response.json())
```

## 创建并轮询直到完成

```python
import time
import requests

api_key = "sk-xxxxxxxxxxxxxxxx"
base_url = "https://api.cxsee.com"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

create_resp = requests.post(
    f"{base_url}/v1/videos/generations",
    headers=headers,
    json=payload,
)

create_data = create_resp.json()
task_id = create_data["task_id"]

print("task_id:", task_id)

while True:
    query_resp = requests.get(
        f"{base_url}/v1/videos/generations/{task_id}",
        headers={"Authorization": f"Bearer {api_key}"},
    )

result = query_resp.json()
    data = result.get("data", {})

status = data.get("status")
    progress = data.get("progress")
    video_url = data.get("content", {}).get("video_url")

print("status:", status, "progress:", progress)

if status == "SUCCESS":
        print("video_url:", video_url)
        break

if status == "FAILED":
        print("failed:", data.get("error") or data.get("fail_reason"))
        break

time.sleep(5)
```

---

# 21. JavaScript 调用示例

## 创建任务

```javascript
const apiKey = "sk-xxxxxxxxxxxxxxxx";

const response = await fetch("https://api.cxsee.com/v1/videos/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedance-2-0-fast-260128",
    prompt: "一只橘猫在阳光下午睡，微风吹动窗帘，画面温馨治愈",
    duration: 5,
    resolution: "480p",
    ratio: "16:9"
  })
});

const data = await response.json();
console.log(data);
```

## 查询任务

```javascript
const apiKey = "sk-xxxxxxxxxxxxxxxx";
const taskId = "cgt-20260629074633-8x7r2";

const response = await fetch(
  `https://api.cxsee.com/v1/videos/generations/${taskId}`,
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${apiKey}`
    }
  }
);

const data = await response.json();
console.log(data);
```

---

# 22. 前端展示建议

客户端可以根据任务状态展示不同文案。

| 状态 | 前端文案 |
|---|---|
| `queued` | 任务排队中 |
| `processing` | 视频生成中 |
| `SUCCESS` | 视频生成完成 |
| `FAILED` | 视频生成失败 |
| 其他 | 等待处理中 |

如果返回了 `video_url`，可以直接用于 HTML5 video 播放：

```html
<video controls src="https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx.mp4"></video>
```

注意：如果前端直接使用 `video_url`，需要考虑 URL 过期和跨域访问问题。

---

# 23. 最终精简版文档

## 创建任务

```json
{
  "id": "cgt-20260629074633-8x7r2",
  "task_id": "cgt-20260629074633-8x7r2",
  "status": "queued",
  "progress": 0
}
```

## 查询任务

```bash
curl -X GET https://api.cxsee.com/v1/videos/generations/cgt-20260629074633-8x7r2 \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'
```

返回成功：

```json
{
  "success": true,
  "data": {
    "id": "cgt-20260629074633-8x7r2",
    "task_id": "cgt-20260629074633-8x7r2",
    "status": "SUCCESS",
    "progress": "100%",
    "content": {
      "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx.mp4"
    }
  }
}
```

## 下载视频

```bash
curl -L "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/xxx.mp4" -o output.mp4
```

---

# 24. 一句话说明

调用 `POST /v1/videos/generations` 创建豆包视频生成任务，保存返回的 `task_id`，再调用 `GET /v1/videos/generations/{task_id}` 查询任务，任务状态为 `SUCCESS` 后，从 `data.content.video_url` 获取生成的视频下载地址。

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