# Veo 3.1 — /videos/generations

Veo 3.1 视频生成（异步任务）：一个接口通过参数生成不同类型的视频——不带 image 为文生视频、带 image（作首帧）为图生视频；画质档 tier=lite/fast/quality，分辨率 resolution=720p/1080p/4k（1080p/4k 仅 quality 档），方向 size=16:9/9:16，时长 duration=4s/6s/8s。提交后返回任务号（HTTP 202），轮询 GET /v1/videos/jobs/{id} 直到 status=succeeded，结果在 data[0].url（重托管 mp4 稳定直链）。单条约 1-2 分钟，按条计费（15~285 积分/条）、失败全额退。

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

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

## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型 ID，此处为 veo-3.1。 |
| `prompt` | string | 是 | 视频描述提示词。 |
| `tier` | string | 否 | 画质档：lite（默认，最省）/ fast / quality。 |
| `resolution` | string | 否 | 分辨率：720p（默认）/ 1080p（仅 quality 档；Lite/Fast 只有 720p）。4K 暂未开放。 |
| `size` | string | 否 | 画面方向：16:9（横屏，默认）/ 9:16（竖屏）。 |
| `duration` | string | 否 | 时长：4s / 6s / 8s（默认 8s）。 |
| `image` | string | 否 | 图生视频：带参考图（作为首帧）即走图生视频，可传公网 URL、data: URI 或 base64；不带则为文生视频。 |

## 请求示例
```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": "veo-3.1", "prompt": "a cat surfing a wave at sunset", "tier": "quality", "resolution": "1080p", "size": "16:9", "duration": "8s"}'
# image-to-video: also pass  "image": "https://example.com/first-frame.png"
# 2) poll every ~5s 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": "veo-3.1"
}
```

## 异步视频任务（提交 → 轮询）
一个模型通过参数生成不同类型视频：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 https://nezhagate.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "veo-3.1", "prompt": "一只猫在日落时冲浪", "tier": "quality", "resolution": "1080p", "size": "16:9", "duration": "8s"}'
# 图生视频：额外传 image 参数（首帧参考图，公网 URL / data: / base64）
# 轮询结果
curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```