# 统一视频 API

https://video-doc.1route.dev/zh/docs/video-api



## 接入入口 [#接入入口]

服务地址为 `https://video.1route.dev`，使用本站视频 Key：`Authorization: Bearer YOUR_API_KEY`。创建任务使用 JSON。

[完整 OpenAPI](/openapi.json) · [全站 38 个模型目录](/video-models.json)

| 操作          | 方法与路径                                  |
| ----------- | -------------------------------------- |
| 查看 Key 可用模型 | `GET /v1/models`                       |
| 创建一次视频任务    | `POST /v1/videos`                      |
| 查询同一个任务     | `GET /v1/videos/{id}`                  |
| 下载 / 查看视频头  | `GET` / `HEAD /v1/videos/{id}/content` |

字段名称统一；各型号的分辨率、秒数、素材上限和计费单位仍有区别。更换模型前先核对目录和 Key 权限。目录中 `null` 表示未确认，并非无限制。

## 公共请求字段 [#公共请求字段]

| 字段             | 新客户端使用的类型 | 说明                                            |
| -------------- | --------- | --------------------------------------------- |
| `model`        | string    | 本站公开模型 ID                                     |
| `prompt`       | string    | 非空画面描述                                        |
| `seconds`      | integer   | 生成秒数，必须符合型号范围或枚举                              |
| `resolution`   | string    | 按型号选择；未定义时省略                                  |
| `aspect_ratio` | string    | 按型号选择；不支持画幅控制的型号省略                            |
| `images`       | array     | 图片 URL，或含 `url` 的对象                           |
| `videos`       | array     | 视频 URL，或含 `url`、`seconds` 的对象；WAN3 官转必须用带时长对象 |
| `audios`       | array     | 音频 URL，或含 `url` 的对象；MP3 要求按型号目录               |

仅向支持对应素材的型号传该字段。图片对象可在支持的型号上增加 `role: first_frame / last_frame / reference_image`；不支持的角色会被拒绝。WAN3 官转和 Seedance Token 支持该角色结构，MiniMax 与混合型号只接受默认 `reference_image`。

公共素材契约使用无需登录的 HTTP(S) 直链。本站没有承诺通用 multipart、base64 或素材预检接口；不要把其他服务的上传接口直接套用到本站。

下面是 WAN3 官转的最小结构示例，素材地址是占位符，不要直接提交付费请求：

```json
{
  "model": "wan3.0-video-720p",
  "prompt": "参考图片中的场景，跟随视频中的镜头移动",
  "seconds": 5,
  "aspect_ratio": "16:9",
  "images": [{"url": "https://YOUR_MEDIA_HOST/reference.jpg", "role": "first_frame"}],
  "videos": [{"url": "https://YOUR_MEDIA_HOST/reference.mp4", "seconds": 3}]
}
```

此示例按 8 秒计算：5 秒输出 + 3 秒参考视频。其他按次或按 Token 型号不套用这条公式。WAN3 官转参考视频最多 5 个、单个及合计最多 15 秒，输出加参考视频最多 30 秒；原有去重和计费约束保留。

## 旧客户端兼容 [#旧客户端兼容]

| 旧字段                | 推荐字段                 |
| ------------------ | -------------------- |
| `duration`         | `seconds`            |
| `ratio`            | `aspect_ratio`       |
| `reference_images` | `images`             |
| `reference_videos` | `videos`             |
| `reference_audios` | `audios`             |
| `size`             | 型号支持时使用 `resolution` |

整数数字字符串（如 `"5"`）仍可用，新程序请发送数字 `5`。不要同时发送新旧字段；值冲突会被拒绝。WAN3 官转的分辨率由模型名后缀决定，`size/resolution` 不能改变型号档位；原有 Seedance 多图版保持固定 720p 的兼容行为。

Seedance Token 的原生 `content` 和显式 `metadata` 扩展保留。普通未知顶层字段会被拒绝；不要用扩展覆盖公共计费参数。其目录中的 1–3600 秒仅是网关校验边界，不是生成能力承诺，实际型号和分组可能有更窄限制。

## 任务响应和取片 [#任务响应和取片]

创建成功后保存 `id` 与响应头 `X-Oneapi-Request-Id`。程序使用 `id`，不要依赖旧 `task_id` 别名。

```json
{
  "id": "task_EXAMPLE",
  "object": "video",
  "model": "wan3.0-video-720p",
  "status": "queued",
  "progress": 0,
  "created_at": 1780000000
}
```

每 15 秒查询同一 ID：`queued` 排队、`in_progress` 处理中、`completed` 可交付、`failed` 失败、`expired` 缓存过期。生成完成但交付仍在准备时，可能继续显示 `in_progress`；需人工处理的交付错误有独立错误码，不能据此假定已退款。

完成后读取 `metadata.url`，原样使用本站签名链接下载 MP4，不附加 Key。文件就绪后约保留 10 分钟，单个签名最长约 5 分钟；`expires_at` 是文件到期时间。不要依赖顶层 `url` 一定存在。下载支持 Range 和 HEAD。

## 统一错误读取 [#统一错误读取]

HTTP 失败优先读取 `error.code`、`error.message`、`error.type`：

```json
{
  "error": {
    "code": "video_request_failed",
    "message": "Video request failed. Check task records or contact support before retrying.",
    "type": "api_error"
  }
}
```

任务提交错误暂时保留同内容的顶层 `code/message/data`，用于兼容旧程序。任务查询成功但生成失败时，HTTP 可以为 200，视频对象中 `status: failed` 和 `error` 描述任务失败。

本站 Key 鉴权失败为 401；生成服务内部凭据故障返回 502，不要求下游盲目更换本站 Key。公开错误不包含服务来源、内部任务编号或密钥。创建请求超时、5xx 或未收到 ID 时不要自动重复 POST，先核查任务记录；GET 可以退避重查。

更具体的能力与计费见 [WAN3](/zh/docs/models/)、[MiniMax](/zh/docs/minimax-models/)、[Seedance 按次](/zh/docs/seedance-flat/)及[混合型号](/zh/docs/mixed-models/)。