# WAN3 接口说明

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



## 连接信息 [#连接信息]

| 项目   | 值                                    |
| ---- | ------------------------------------ |
| 服务地址 | `https://video.1route.dev`           |
| 鉴权   | `Authorization: Bearer YOUR_API_KEY` |
| 请求格式 | `application/json`                   |
| 模型列表 | `GET /v1/models`                     |
| 创建任务 | `POST /v1/videos`                    |
| 查询任务 | `GET /v1/videos/{id}`                |

新接入统一使用 `/v1/videos`。旧兼容路径可能存在，但一个项目里不要混用两套路径。

## 先查询模型 [#先查询模型]

```bash
curl "https://video.1route.dev/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

只使用返回列表里存在的模型。模型可见不等于每个时刻都有可用生成容量。

## 文生视频 [#文生视频]

```json
{
  "model": "wan3.0-video-480p",
  "prompt": "一只红色风筝在绿色田野上方飘动，镜头缓慢推进，画面连续。",
  "seconds": "2",
  "aspect_ratio": "16:9"
}
```

## 图片生成视频 [#图片生成视频]

```json
{
  "model": "wan3.0-image-480p",
  "prompt": "图1中的人物自然眨眼并轻轻转头，镜头稳定，保持人物外观一致。",
  "seconds": "2",
  "aspect_ratio": "9:16",
  "reference_images": [
    {
      "url": "https://media.example.com/person.jpg"
    }
  ]
}
```

首尾帧使用 `role`：

```json
{
  "model": "wan3.0-video-720p",
  "prompt": "从首帧自然过渡到尾帧，保持人物身份和服装一致。",
  "seconds": "5",
  "aspect_ratio": "adaptive",
  "reference_images": [
    {
      "url": "https://media.example.com/start.jpg",
      "role": "first_frame"
    },
    {
      "url": "https://media.example.com/end.jpg",
      "role": "last_frame"
    }
  ]
}
```

图片最多 10 张。可用角色为 `reference_image`（默认）、`first_frame`、`last_frame`。尽量只传必要素材。

## 图片、视频和音频参考 [#图片视频和音频参考]

```json
{
  "model": "wan3.0-video-480p",
  "prompt": "图1人物参考视频1的动作和运镜，参考音频1的节奏。",
  "seconds": "10",
  "aspect_ratio": "9:16",
  "reference_images": [
    {
      "url": "https://media.example.com/character.jpg"
    }
  ],
  "reference_videos": [
    {
      "url": "https://media.example.com/motion.mp4",
      "duration": 5
    }
  ],
  "reference_audios": [
    {
      "url": "https://media.example.com/rhythm.mp3"
    }
  ]
}
```

这个请求按 15 秒计费：10 秒成片 + 5 秒参考视频。image 系列传参考视频会被拒绝。

## 参数 [#参数]

| 字段                    | 类型        | 说明                                  |
| --------------------- | --------- | ----------------------------------- |
| `model`               | string，必填 | `GET /v1/models` 返回的 WAN3 名称        |
| `prompt`              | string，必填 | 视频描述，可用“图1”“视频1”“音频1”引用顺序           |
| `seconds`             | string，必填 | 2–30 的整数秒，例如 `"10"`                 |
| `aspect_ratio`        | string    | `16:9`、`9:16`、`1:1`、`adaptive`      |
| `reference_images`    | object\[] | `url`，可选 `role`；最多 10 张             |
| `reference_videos`    | object\[] | `url` 和明确的整数 `duration`/`seconds`   |
| `reference_audios`    | object\[] | 含 `url` 的参考音频                       |
| `size` / `resolution` | string    | 兼容字段；实际档位以模型名的 480p/720p/1080p 后缀为准 |

推荐只传 `seconds`，不要同时传冲突的 `duration`。素材必须是服务端能直接下载的公网 HTTP/HTTPS 地址；生产使用 HTTPS。

高级 `input.media` 允许类型 `first_frame`、`last_frame`、`reference_image`、`reference_audio`、`reference_video`，但新接入优先用上面的 `reference_*` 字段。不要把同一个参考视频同时放到两种字段里。

## 创建任务 [#创建任务]

```bash
curl -X POST "https://video.1route.dev/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "wan3.0-image-480p",
    "prompt": "图1主体自然抬头，镜头缓慢推进。",
    "seconds": "2",
    "reference_images": [
      {"url": "https://media.example.com/reference.jpg"}
    ]
  }'
```

成功响应：

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

立即持久化完整 `id`，同时记录响应头 `X-Oneapi-Request-Id`。创建请求不能自动重试。

## 查询与完成响应 [#查询与完成响应]

```bash
curl "https://video.1route.dev/v1/videos/task_EXAMPLE" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

建议每 15 秒查询一次。等待状态为 `queued`、`in_progress`；完成为 `completed`；失败为 `failed`；本站缓存失效后可能显示 `expired`。

```json
{
  "id": "task_EXAMPLE",
  "task_id": "task_EXAMPLE",
  "object": "video",
  "model": "wan3.0-image-480p",
  "status": "completed",
  "progress": 100,
  "expires_at": 1780000300,
  "metadata": {
    "url": "https://video.1route.dev/v1/videos/task_EXAMPLE/content?expires=...&sig=..."
  }
}
```

下载时完整使用 `metadata.url`，不要自行拼接。签名链接不需要额外的 API Key。详情见 [任务与下载](/zh/docs/tasks/)。

## 完整 Python 客户端 [#完整-python-客户端]

[下载 wan3\_client.py](/examples/wan3_client.py)

默认模式只验证模型并展示请求；使用 `--create --confirm-cost` 才创建任务。已有任务使用 `--task-id task_...`，完全跳过创建步骤。

```bash
# 私密地设置 Key
set WAN3_API_KEY=sk-你的密钥

# 仅检查模型并预览请求，不生成
python wan3_client.py --model wan3.0-video-480p --seconds 2

# 已确认页面价格和费用后，只创建一次
python wan3_client.py --model wan3.0-video-480p --seconds 2 \
  --prompt "红色风筝在绿色田野上方飘动" --create --confirm-cost

# 程序关闭后继续原任务，不会新建
python wan3_client.py --task-id task_EXAMPLE
```

PowerShell 设置环境变量请使用 `$env:WAN3_API_KEY="..."`。不要把真实 Key 写入命令截图、教程或代码仓库。