# Lai.vc 图像生成 API — AI 开发文档

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

## 基础

- 接入点:`https://api.lai.vc`
- 鉴权:每个请求带 `Authorization: Bearer ak-...`(AutoKey,用户在 lai.vc 控制台「API 与 MCP → 密钥管理」创建;与聊天中转的 sk- 令牌不通用)
- 计费:按张计费,提交即从账户余额预扣;**生成失败自动全额退款;被拒的请求(4xx)不计费**
- 产物:只返回图片 URL(**7 天有效**),不返回 base64;提醒用户及时转存
- 错误体:OpenAI 风格 `{"error":{"message":"...","type":"invalid_request_error","code":"..."}}`

## 端点一览

| 方法 | 路径 | 用途 |
|---|---|---|
| POST | /v1/images/generations | 提交生图任务(**默认同步**等待出图返回 200,最长 240s;`?wait=false` 或 `?async=1` 走异步 202 + 任务号) |
| GET | /v1/images/generations/{id} | 查询任务状态与结果 |
| GET | /v1/images/models | 模型能力 + 结构化价目表 |
| POST | /v1/images/uploads | 上传参考图 → image_key |

## POST /v1/images/generations

请求体(JSON):

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| prompt | string | 是 | 提示词,≤2000 字 |
| model | string | 否 | 模型 id,见下方价目表;缺省 `gpt-image-2-official` |
| aspect | string | 否 | 画幅,**各模型支持档见价目表**(如 16:9 / 9:16 / 21:9 / auto 智能构图);缺省 1:1;传了不支持的档自动回退 1:1 |
| quality | string | 否 | 分辨率档:1k / 2k / 3k / 4k(各模型支持档见价目表) |
| grade | string | 否 | 品质档:low / medium / high,与分辨率**正交**,同分辨率下价差可达 10 倍(仅部分模型支持) |
| n | number | 否 | 张数 1–4,缺省 1;费用 = 单价 × n;带参考图时强制 1 |
| imageKeys | string[] | 否 | 参考图 key 数组(先调 /v1/images/uploads 拿 image_key),最多 10 张,只认本账户上传的。**字段名只认 imageKeys,写成 image_key / image_keys 或传字符串会 400**,不会静默按文生图处理 |

档位容错:传了该模型不支持的 quality/grade 会自动回退到支持档,不报错也不会按错误档位计费。要精确控制费用,按价目表传参。

默认**同步**:等到出图再返回 200(单张通常 30~70s)。经 api.lai.vc(Cloudflare)接入时同步最长等 90s、经 fast-*.lai.vc 直连最长 240s;超时返回 status=processing + 任务号,继续轮询即可。加 `?wait=false`(或 `?async=1`、请求头 `Prefer: respond-async`)才是异步,立即返回 202:

```json
{ "id": "任务号", "ids": ["…"], "status": "queued", "model": "…", "cost_usd": 0.24, "created": 1753142400 }
```

同步模式返回 200,响应体 `{ "status": "succeeded|failed|processing", "data": [任务对象…] }`;`data[0].url` 即成品直链(与 OpenAI images 响应同形,通用客户端可直接用)。
**若 240s 内未完成返回 status="processing":任务仍在跑,继续用任务号轮询,绝不要重复提交(重复提交会再次计费)。**

## GET /v1/images/generations/{id}

建议 3 秒轮询间隔。任务对象:

```json
{
  "id": "…",
  "status": "processing | succeeded | failed",
  "model": "…",
  "size": "1:1/2k/medium",
  "cost_usd": 0.7,
  "url": "https://…(仅 succeeded,7 天有效)",
  "error": "失败原因(仅 failed,此时已自动退款)",
  "created": 1753142400
}
```

## POST /v1/images/uploads

图生图/改风格/多图合成的前置步骤。PNG/JPG/WebP,单张 ≤12MB。不接受外链 URL,必须先上传。

- multipart:`file` 字段
- 或 JSON:`{"image": "data:image/png;base64,…"}`(也接受纯 base64)

返回 `{"image_key": "image-src/…", "bytes": 123}`,提交生成时放进 `imageKeys` 数组。

## 模型与价目表(USD/张,实时生效)

### GPT Image 2(`gpt-image-2-official`)

- 通用生图 · 支持参考图/图生图 · 1K/2K/4K
- 参考图:支持,最多 10 张;预估耗时 60s
- 画幅:auto(智能构图) / 1:1 / 3:2 / 4:3 / 16:9 / 21:9 / 2:1 / 2:3 / 3:4 / 9:16 / 1:2

| quality | 单价 |
|---|---|
| 1k(1K) | $0.10 |
| 2k(2K) | $0.36 |
| 4k(4K) | $0.56 |

### GPT Image 2.5 Flare(`gpt-image-2-5`)

- 2.5 Flare · 光影更真实 · 多图参考合成 · 1K(2K/4K 维护中)
- 参考图:支持,最多 10 张;预估耗时 60s
- 画幅:auto(智能构图) / 1:1 / 3:2 / 4:3 / 16:9 / 21:9 / 2:1 / 2:3 / 3:4 / 9:16 / 1:2

| quality | 单价 |
|---|---|
| 1k(1K) | $0.16 |

### GPT Image 2.5 Sunburst(`gpt-image-2-5-sunburst`)

- 2.5 Sunburst · 另一种画风取向 · 多图参考合成 · 1K(2K/4K 维护中)
- 参考图:支持,最多 10 张;预估耗时 60s
- 画幅:auto(智能构图) / 1:1 / 3:2 / 4:3 / 16:9 / 21:9 / 2:1 / 2:3 / 3:4 / 9:16 / 1:2

| quality | 单价 |
|---|---|
| 1k(1K) | $0.16 |

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

- 极速出图 · 5 秒级 · 2K 同价 · 高性价比
- 参考图:不支持;预估耗时 8s
- 画幅:1:1 / 3:2 / 4:3 / 16:9 / 2:3 / 3:4 / 9:16

| quality | 单价 |
|---|---|
| 1k(1K) | $0.10 |
| 2k(2K) | $0.15 |

### Grok Imagine HD(`grok-imagine-image-quality`)

- 高清档 · 细节增强 · 2K 大图
- 参考图:不支持;预估耗时 12s
- 画幅:1:1 / 3:2 / 4:3 / 16:9 / 2:3 / 3:4 / 9:16

| quality | 单价 |
|---|---|
| 1k(1K) | $0.20 |
| 2k(2K) | $0.30 |

### Gemini 3 Pro(`gemini-3-pro-image`)

- 顶级质感 · 电影级细节 · 支持画幅 & 改图
- 参考图:支持,最多 10 张;预估耗时 90s
- 画幅:1:1 / 2:3 / 3:2 / 16:9

| quality | 单价 |
|---|---|
| 1k(1K) | $0.24 |
| 2k(2K) | $0.48 |
| 4k(4K) | $0.96 |

### Gemini 3.1 Flash(`gemini-3.1-flash-image`)

- 极速出图 · 高质量 · 支持画幅 & 改图
- 参考图:支持,最多 10 张;预估耗时 60s
- 画幅:1:1 / 2:3 / 3:2 / 16:9

| quality | 单价 |
|---|---|
| 1k(1K) | $0.20 |
| 2k(2K) | $0.40 |
| 4k(4K) | $0.80 |

## 查询余额

```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 | 密钥缺失/无效,检查 Authorization 头 |
| 402 | insufficient_quota | 账户余额不足,提示用户充值 |
| 402 | key_quota_exceeded | 这把 key 的消费上限用尽(账户余额不受影响),提示用户在控制台调高 |
| 403 | key_disabled / key_expired | 密钥已停用/过期 |
| 403 | ip_denied | 来源 IP 不在该密钥白名单 |
| 403 | scope_denied | 密钥未开通该能力 |
| 400 | invalid_request | 参数错误,看 message |
| 404 | not_found | 任务不存在或不属于本账户 |
| 500 | server_error | 服务端异常,稍后重试 |

## 给 agent 的行为准则

1. **按需选档,先报价再生成**:草图/占位图用最便宜档(见上方价目表,如 gpt-image-2-official 的 1k/low),用户明确要高质量才上高档;每次生成前把所选档位价格告诉用户。
2. **同步即可**:默认等到出图返回,客户端 HTTP 超时请设 ≥300s;批量几百张或要做进度条再用异步(`?async=1` + 3s 轮询)。
3. **失败不要自动重试提交**:failed 已自动退款,把 error 告诉用户,由用户决定是否重试。
4. **拿到 url 第一时间下载/转存**(7 天过期),并把图片保存路径告诉用户。
5. 除非用户明确要求,单次任务不要生成超过 4 张。