# Lai.vc 视频生成 API — AI 开发文档

> 本文档面向 AI 编程助手(agent),由价目注册表实时生成,价格与能力永远是当前生效值。
> 固定地址:https://lai.vc/docs/api/videos.md;结构化价目也可运行时 GET https://api.lai.vc/v1/videos/models 获取。
> 图像 API 见 https://lai.vc/docs/api/images.md。

## 认证

所有请求带 `Authorization: Bearer ak-你的密钥`。密钥在 Lai.vc 控制台
「API 与 MCP → 密钥管理」创建(`ak-` 开头,与聊天中转的 `sk-` 是两套)。

> ⚠️ 交给 AI agent 使用前,请给密钥设**消费上限** —— 视频单条最高可达 $60,
> agent 失控循环一次就是几百美元。上限只锁这把密钥,不影响账户余额。

## 关键约束(先读这段,能避开 90% 的坑)

1. **异步**。提交返回 `202` + 任务号,视频通常需要 **2~10 分钟**。
   加 `?wait=true` 可同步等待,但多数客户端会先超时 —— **视频强烈建议走异步轮询**。
2. **成品仅保留 24 小时**,过期自动删除(状态变 `expired`)。
   返回的 URL 有效期不会超过留存期,请及时下载转存到自己的存储。
3. **计费方式看清楚**:`per_generation` 拉长时长不加价(长视频首选);
   `per_second` 按时长成比例涨价;`duration_tiered` 按时长档位阶梯计价。
   一律以各模型价目表为准 —— 同样 15 秒,不同模型可能差十倍以上。
4. **失败自动退款**,无需对账。

## 端点

### 提交生成

```http
POST https://api.lai.vc/v1/videos/generations
Content-Type: application/json
Authorization: Bearer ak-xxx

{
  "model": "lai-2.0-fast",
  "prompt": "一架纸飞机掠过平静的蓝色海面,电影感",
  "mode": "text",
  "duration": 5,
  "resolution": "480p",
  "aspect": "16:9"
}
```

返回 `202`:

```json
{ "id": "…", "status": "queued", "cost_usd": 2.33, "duration": 5, "resolution": "480p" }
```

| 参数 | 必填 | 说明 |
|---|---|---|
| `model` | ✅ | 模型 id,见下方价目表 |
| `prompt` | ✅ | 内容描述,支持中文 |
| `mode` | | `text` 文生 / `frame` 首(尾)帧 / `ref` 参考图。带图时必填 |
| `duration` | | 时长(秒),必须是该模型支持的档 |
| `resolution` | | `480p` / `720p` / `1080p` / `4k`,须在该模型支持范围内 |
| `aspect` | | `16:9` / `9:16` / `1:1` |
| `imageKeys` | | 图片 key 数组,先调上传接口获得;`mode` 非 `text` 时必填。**`frame` 模式按顺序取:第 1 张 = 首帧,第 2 张 = 尾帧(可只传首帧)**;`ref` 模式为无序参考图 |

**参数不合法会直接 400 并说明原因**(不会静默换成别的档位后扣你钱)。

#### 首尾帧(`mode: "frame"` 传两张图)

第 1 张固定为首帧、第 2 张为尾帧,模型生成两者之间的过渡。各模型支持几张见下方「模式」一行的「图片 N-M 张」:
写着 `1-2 张` 的支持首尾帧,`1 张` 的只支持首帧。

```json
{ "model": "grok-imagine-video-1.5-preview", "prompt": "缓慢过渡", "mode": "frame",
  "duration": 6, "resolution": "480p", "imageKeys": ["<首帧 key>", "<尾帧 key>"] }
```

⚠️ 带图模式常有额外收窄(上游限制),**以每个模型 `frame` / `ref` 行列出的时长与分辨率为准**。
例如 Grok Imagine 1.5 的首尾帧与参考图**不支持 1080p**(纯文生可以),选了会 400 而不是扣费后失败。

### 查询结果

```http
GET https://api.lai.vc/v1/videos/generations/{id}
```

```json
{
  "id": "…", "status": "succeeded",
  "url": "https://…mp4", "expires_at": "2026-07-23T…Z",
  "model": "grok-imagine-video-1.5-preview", "duration": 6, "resolution": "480p", "cost_usd": 0.6
}
```

`status`:`processing` 生成中 | `succeeded` 成功 | `failed` 失败(已退款) | `expired` 已过保留期。

### 上传图片(首尾帧 / 参考图)

```http
POST https://api.lai.vc/v1/videos/uploads
Content-Type: multipart/form-data;  file=@first-frame.png   # 尾帧同样走这个接口,再传一次
# 或 JSON: {"image": "data:image/png;base64,…"}
```

返回 `{ "image_key": "video-src/…" }`,提交时按顺序放进 `imageKeys` 数组(首帧在前、尾帧在后)。
**不接受外链** —— 图片必须先传到我们这里。

### 模型与价目

```http
GET https://api.lai.vc/v1/videos/models
```

## 价目表(每条视频单价,美元)

### Seedance 2.0 Mini(`seedance-2.0-mini`)

- 官Key · 文生 / 首帧 / 首尾帧 · 4~15s · 480p/720p · 最便宜
- 计费:**按时长阶梯(见价目表)**;预估耗时 110s
- 模式:text / frame;画幅:16:9 / 9:16 / 1:1
  - `text`:时长 4/5/6/7/8/9/10/11/12/13/14/15s,分辨率 480p/720p
  - `frame`:时长 4/5/6/7/8/9/10/11/12/13/14/15s,分辨率 480p/720p,图片 1-2 张

| duration \ resolution | 480p | 720p |
|---|---|---|
| 4s | $0.48 | $1.04 |
| 5s | $0.60 | $1.30 |
| 6s | $0.72 | $1.56 |
| 7s | $0.84 | $1.82 |
| 8s | $0.96 | $2.08 |
| 9s | $1.08 | $2.34 |
| 10s | $1.20 | $2.60 |
| 11s | $1.32 | $2.86 |
| 12s | $1.44 | $3.12 |
| 13s | $1.56 | $3.38 |
| 14s | $1.68 | $3.64 |
| 15s | $1.80 | $3.90 |

### Seedance 2.0 Fast(`seedance-2.0-fast`)

- 官Key · 文生 / 首帧 / 首尾帧 · 4~15s · 480p/720p · 画质更好
- 计费:**按时长阶梯(见价目表)**;预估耗时 140s
- 模式:text / frame;画幅:16:9 / 9:16 / 1:1
  - `text`:时长 4/5/6/7/8/9/10/11/12/13/14/15s,分辨率 480p/720p
  - `frame`:时长 4/5/6/7/8/9/10/11/12/13/14/15s,分辨率 480p/720p,图片 1-2 张

| duration \ resolution | 480p | 720p |
|---|---|---|
| 4s | $0.99 | $2.13 |
| 5s | $1.24 | $2.66 |
| 6s | $1.49 | $3.19 |
| 7s | $1.74 | $3.72 |
| 8s | $1.98 | $4.26 |
| 9s | $2.23 | $4.79 |
| 10s | $2.48 | $5.32 |
| 11s | $2.73 | $5.85 |
| 12s | $2.98 | $6.38 |
| 13s | $3.22 | $6.92 |
| 14s | $3.47 | $7.45 |
| 15s | $3.72 | $7.98 |

### Grok Imagine(`grok-imagine-video`)

- 文生 / 首帧图生 · 自带音效 · 极速出片 · 高性价比
- 计费:**按时长阶梯(见价目表)**;预估耗时 30s
- 模式:text / frame;画幅:16:9 / 9:16 / 1:1
  - `text`:时长 6/10/12/15s,分辨率 480p/720p
  - `frame`:时长 6/10/12/15s,分辨率 480p/720p,图片 1-1 张

| duration \ resolution | 480p | 720p |
|---|---|---|
| 6s | $0.60 | $0.90 |
| 10s | $0.70 | $1.05 |
| 12s | $0.80 | $1.20 |
| 15s | $0.90 | $1.35 |

### Grok Imagine 1.5(`grok-imagine-video-1.5-preview`)

- 文生 / 首尾帧 / 参考图 · 旗舰画质 · 自带音效
- 计费:**按时长阶梯(见价目表)**;预估耗时 40s
- 模式:text / frame / ref;画幅:16:9 / 9:16 / 1:1
  - `text`:时长 6/10/12/15s,分辨率 480p/720p/1080p
  - `frame`:时长 6/10/12/15s,分辨率 480p/720p,图片 1-2 张
  - `ref`:时长 6/10/12/15s,分辨率 480p/720p,图片 1-7 张

| duration \ resolution | 480p | 720p | 1080p |
|---|---|---|---|
| 6s | $0.96 | $1.68 | $3.00 |
| 10s | $1.60 | $2.80 | $5.00 |
| 12s | $1.92 | $3.36 | $6.00 |
| 15s | $2.40 | $4.20 | $7.50 |

### Veo 3.1 Pre(`veo3.1-pre`)

- 文生 / 首帧 / 参考图 · 4/6/8s
- 计费:**按次(拉长时长不加价)**;预估耗时 90s
- 模式:text / frame / ref;画幅:16:9 / 9:16
  - `text`:时长 4/6/8s,分辨率 720p/1080p/4k
  - `frame`:时长 4/6/8s,分辨率 720p/1080p/4k,图片 1-1 张
  - `ref`:时长 4/6/8s,分辨率 720p,图片 1-3 张

| duration \ resolution | 720p | 1080p | 4k |
|---|---|---|---|
| 4s | $1.70 | — | — |
| 6s | $1.70 | — | — |
| 8s | $1.70 | $2.00 | $4.40 |

### Veo 3.1 Lite(`veo3.1-lite`)

- 文生 / 首帧 / 参考图 · 4/6/8s · 轻量预览 · 最便宜
- 计费:**按次(拉长时长不加价)**;预估耗时 70s
- 模式:text / frame / ref;画幅:16:9 / 9:16
  - `text`:时长 4/6/8s,分辨率 720p/1080p
  - `frame`:时长 4/6/8s,分辨率 720p/1080p,图片 1-1 张
  - `ref`:时长 4/6/8s,分辨率 720p,图片 1-3 张

| duration \ resolution | 720p | 1080p |
|---|---|---|
| 4s | $0.80 | — |
| 6s | $0.80 | — |
| 8s | $0.80 | $1.20 |


## 查询余额

```http
GET https://api.lai.vc/v1/account/balance
```

任何有效 AutoKey 都能查(不要求特定能力域)。生成前不确定余额是否充足,先查它比撞 402 更省事。

```json
{
  "account": { "balance_usd": 62.72, "used_total_usd": 1.04 },
  "key": { "name": "…", "limit_usd": 5, "used_usd": 0.1, "remaining_usd": 4.9, "expires_at": null }
}
```

- `account.balance_usd`:账户可用余额,**生成实际扣这里**(所有密钥共享)。
- `key.remaining_usd`:本密钥消费上限的剩余($limit − $used);`null` = 该密钥不限额。

## 错误码

| HTTP | code | 含义 |
|---|---|---|
| 401 | `invalid_api_key` | 密钥无效或格式错误 |
| 403 | `key_disabled` / `key_expired` / `ip_denied` / `scope_denied` | 密钥被停用 / 过期 / IP 不在白名单 / 未开通视频能力 |
| 402 | `key_quota_exceeded` | 该密钥消费上限用尽(账户余额不受影响) |
| 402 | `insufficient_quota` | 账户余额不足 |
| 400 | `invalid_request` | 参数不合法(时长/分辨率不被该模型支持等) |
| 404 | `not_found` | 任务不存在 |

遇到 401/403/402 **不要重试** —— 重试不会成功,先检查密钥配置或充值。

## MCP(推荐给 AI 编程工具)

不想自己写 HTTP,可直接挂官方 MCP:

```bash
claude mcp add laivc --env LAIVC_API_KEY=ak-xxx -- npx -y @laivc/mcp
```

提供 `list_video_models` / `generate_video` / `get_video`(以及对应的图像工具)。