# 推荐接入统一接口格式

视频模型通常有两类接入方式：官方格式和 YutoAPI 统一格式。新项目优先推荐统一格式，因为它把不同视频模型的提交、查询、状态和结果字段收敛到同一套接口，前端和后端只需要维护一套任务流程。

## 为什么推荐统一格式

- 提交任务统一使用 `POST /v2/videos/generations`。
- 查询任务统一使用 `GET /v2/videos/generations/{task_id}`。
- 状态字段统一为 `NOT_START`、`SUBMITTED`、`QUEUED`、`IN_PROGRESS`、`SUCCESS`、`FAILURE`。
- 结果字段统一放在 `data.output` 或 `data.outputs`，便于业务侧下载、入库或展示。
- 后续切换模型时通常只需要替换 `model` 和少量模型参数。

## 适合使用统一格式的场景

- 你要同时接入多个视频模型，例如 Seedance、Veo、Grok、Sora 或其他视频能力。
- 你的业务侧希望统一保存任务 ID、进度、失败原因和结果 URL。
- 你不想在客户端为每个模型维护一套不同的状态枚举和返回解析逻辑。
- 你希望先跑通通用视频生成，再按需补充官方格式的高级参数。

如果你的业务必须完全复用某个官方 SDK、官方字段或官方回调结构，可以继续使用对应模型的官方格式页面。

## 统一格式请求示例

提交视频生成任务：

```bash
curl --request POST \
  --url '{BaseURL}/v2/videos/generations' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedance-1-0-pro-250528",
    "prompt": "一名侦探进入昏暗房间，检查桌上的线索，电影感镜头，16:9",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720P"
  }'
```

返回：

```json
{
  "task_id": "f186f65a-8657-4e83-b0e3-67facf1b2576"
}
```

查询任务：

```bash
curl --request GET \
  --url '{BaseURL}/v2/videos/generations/f186f65a-8657-4e83-b0e3-67facf1b2576' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

完成时示例：

```json
{
  "task_id": "f186f65a-8657-4e83-b0e3-67facf1b2576",
  "status": "SUCCESS",
  "fail_reason": "",
  "progress": "100%",
  "data": {
    "output": "https://example.com/output.mp4"
  }
}
```

## 图片或视频作为输入

统一格式会根据输入字段判断任务类型：

- 只有 `prompt`：文生视频。
- 带 `images`：图生视频、首帧/参考图视频生成。
- 带 `videos`：视频转视频或视频编辑类任务。

示例：

```json
{
  "model": "doubao-seedance-1-0-pro-250528",
  "prompt": "让画面中的人物向前走，镜头缓慢推进",
  "images": ["https://example.com/start-frame.png"],
  "duration": 5,
  "aspect_ratio": "16:9"
}
```

## 和官方格式的选择

| 接入方式 | 推荐场景 | 相关页面 |
| --- | --- | --- |
| 统一格式 | 多模型接入、统一任务系统、减少适配成本 | [统一格式接口介绍](/api/doc-7324259) |
| Seedance 官方格式 | 已按火山引擎 / Seedance 官方字段开发，需要保留官方字段结构 | [创建任务-官方格式](/api/api-343680647)、[查询-官方格式](/api/api-343680865) |

## 接入建议

- 后端保存 `task_id`、`model`、`status`、`progress`、`fail_reason` 和最终结果 URL。
- 客户端不要阻塞等待生成完成，提交任务后轮询查询接口。
- 轮询间隔建议递增退避，例如 2 秒、4 秒、8 秒。
- 当 `status` 为 `SUCCESS` 或 `FAILURE` 时停止轮询。
- 不要把 API Key 写入前端公开代码、日志、GitHub 或截图。