# Wan 3.0 — /videos/generations

通义万相 Wan 3.0 视频生成（异步任务）：一个接口按参数切换玩法——不带素材为文生视频，带一张参考图为首帧生视频，带两张为首尾帧，带多张为多图参考，带参考视频则是视频改写。时长 duration=2–30 的任意整数秒，分辨率 resolution=480P / 720P / 1080P（默认 720P，每档单价不同），画幅 size=16:9 / 9:16 / 1:1 / 4:3 / 3:4，带首帧时可传 size=adaptive 让成片跟随参考图的比例。最多 10 张参考图、5 段参考视频、5 段参考音频（后两者总时长各 ≤15 秒）。提交后返回任务号（HTTP 202），轮询 GET /v1/videos/jobs/{id} 直到 status=succeeded，结果在 data[0].url（重托管 mp4 稳定直链）。按秒计费：输出时长 + 各参考视频时长，参考图与参考音频不计费；失败全额退。

**端点:** `POST https://nezhagate.com/v1/videos/generations`

## 认证
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型 ID，此处为 wan3.0-video。 |
| `prompt` | string | 是 | 视频内容、镜头与运动的描述。最长 5000 字节（UTF-8，中文一个字算 3 字节）。可用 @Image1 / @Video1 / @Audio1 按顺序点名参考素材，例如「@Image1 的角色参照 @Video1 的运镜」；不点名则由模型自行取用。 |
| `duration` | integer | 否 | 时长秒数，2–30 的任意整数（默认 2）。也可写作 seconds。按秒计费。 |
| `resolution` | string | 否 | 分辨率：480P / 720P / 1080P（默认 720P）。每秒单价 480P $0.09 / 720P $0.12 / 1080P $0.16。 |
| `size` | string | 否 | 画幅：16:9 / 9:16 / 1:1 / 4:3 / 3:4（默认 16:9）。也可写作 aspect_ratio。带首帧时可传 adaptive，成片直接跟随参考图的比例。本模型不支持 21:9。 |
| `image` | string | 否 | 图生视频：单张参考图默认作首帧，可传公网 URL、data: URI 或 base64；不带则为文生视频。 |
| `images` | array | 否 | 多张参考图，最多 10 张，不计费。传两张及以上时默认作主体 / 场景参考。超过上限直接报错，不会截断。也可写作 reference_images。注意：参考图里出现的每个人物都会被当成候选主体，场景参考图最好不要带其他人。 |
| `image_role` | string | 否 | 参考图用法：first_frame（作首帧，传两张时第二张作尾帧）或 reference（作主体 / 场景参考）。不传时：1 张按 first_frame，2 张及以上按 reference。同时给参考视频时必须用 reference。 |
| `video_references` | array | 否 | 参考视频，最多 5 段，总时长 ≤ 15 秒。每段写成 {"url": "...", "duration": 5}，duration 必填（单位秒）——参考视频按其时长与输出时长一并计费。只接公网 http(s) 链接；带参考视频时，参考总时长 + 输出时长 ≤ 30 秒。可与参考图同时使用。 |
| `audio_reference` | string / array | 否 | 参考音频的公网 http(s) 链接，最多 5 段，总时长 ≤ 15 秒，不计费。必须与参考图或参考视频一起使用。 |
| `prompt_extend` | boolean | 否 | 提示词智能改写，不传时由上游决定（默认开启）。提示词已经写得很细时传 false 可以避免被改写。 |

## 请求示例
```bash
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "wan3.0-video", "prompt": "a paper crane unfolding over a misty lake", "duration": 5, "resolution": "720P", "size": "16:9"}'
# image-to-video: also pass  "image": "https://example.com/first-frame.png"
# 2) poll every ~15s until status=succeeded, then read data[0].url
curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

## 响应示例
```json
{
  "id": "img_3f9a...c2",
  "object": "video.generation.job",
  "status": "queued",
  "model": "wan3.0-video"
}
```

## 异步视频任务（提交 → 轮询）
一个模型通过参数生成不同类型视频：tier=lite/fast/quality、resolution=720p/1080p/4k（1080p/4k 仅 quality 档）、size=16:9/9:16、duration=4s/6s/8s；带 image 参数即图生视频（以图为首帧）。提交后返回 HTTP 202 与任务号，轮询 GET /v1/videos/jobs/{id} 直到 status=succeeded，结果在 data[0].url（重托管 mp4，约 1-2 分钟）。按条计费、失败全额退。

```bash
# 提交任务（文生视频）
curl __BASE__/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "wan3.0-video", "prompt": "一只猫在日落时冲浪", "tier": "quality", "resolution": "1080p", "size": "16:9", "duration": "8s"}'
# 图生视频：额外传 image 参数（首帧参考图，公网 URL / data: / base64）
# 轮询结果
curl __BASE__/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```