# 图像生成

来源: https://platform.lyrouter.com/ai_gateway/docs/images-generations
更新日期: 2026-10-19

根据文本提示词生成图片，也可以附带参考图做图生图。兼容 OpenAI Images API 的 `images.generate`：OpenAI 官方 SDK 把 Base URL 改成 `https://api.lyrouter.com/v1` 即可调用，图片在同一个响应里返回，不需要轮询。目前可用 Seedream 5.0、GPT-Image、Gemini Image 三个系列，参数写法和返回形式因系列而异，见下文各模型小节。

`POST /v1/images/generations`

## 鉴权

在请求头中携带 API Key：

```text
Authorization: Bearer <API Key>
```

`Bearer` 区分大小写。也可以改用 `x-api-key: <API Key>`，两者同时存在时只读 `Authorization`。API Key 在工作空间的 **API 密钥** 页面创建，只用于 LYRouter 鉴权，不会转发给上游服务商。完整说明见[接入地址与鉴权](https://platform.lyrouter.com/ai_gateway/docs/call-gateway)。

## 请求头

| 请求头 | 必填 | 说明 |
| --- | --- | --- |
| `Content-Type` | 是 | `application/json` |
| `X-Gateway-Strict-Parameters` | 否 | 设为 `true`（只认小写）时，请求中有会被网关丢弃的参数就直接返回 400 `unsupported_parameters`，不调用上游、不计费。哪些参数会被丢弃见下文「各模型的处理方式」 |

## 请求体

各模型共用的参数如下，每个参数在各系列上是否生效见后面的模型小节。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 图像模型 ID，例如 `bytedance/doubao-seedream-5.0-lite`。只能写具体的模型 ID：虚拟模型 `@vmodel/<名称>` 和 `lyrouter/auto` 在图像接口上返回 403。可用模型在模型广场查看，或调用[列出模型](https://platform.lyrouter.com/ai_gateway/docs/models) |
| `prompt` | string | 是 | 提示词。Seedream pro 做图层拆分时可以省略 |
| `size` | string | 否 | 输出尺寸，写成宽高（如 `2048x2048`）或档位名（如 `2K`）。可用写法和取值范围因模型而异，见各模型小节 |
| `n` | integer | 否 | 生成张数。GPT-Image 原样转发给上游，最大 10。Seedream 目前不能用它一次生成多张：`n` 会转发给上游，但只出 1 张，不报错，也不列进 `X-Gateway-Unsupported-Parameters`，需要多张请发多次请求。Gemini 会丢弃 |
| `quality` | string | 见说明 | 生成质量，GPT-Image 系列使用，取值逐模型不同，`gpt-image-2` 必填；Gemini 会丢弃 |
| `response_format` | string | 否 | `url` 或 `b64_json`，只对 Seedream 生效（默认 `url`）。GPT-Image、Gemini 固定返回 `b64_json`，网关丢弃这个参数 |
| `image` | string \| array | 否 | 参考图，用于图生图。Seedream 接受公网 URL 或 `data:image/<格式>;base64,<数据>`；Gemini 也接受，写法见[图像编辑](https://platform.lyrouter.com/ai_gateway/docs/images-edits) |
| `user` | string | 否 | 终端用户标识。Seedream、GPT-Image 原样转发；Gemini 会丢弃 |

表中没有的其他参数：Seedream、GPT-Image 原样转发给上游，是否生效取决于模型；Gemini 一律丢弃。

### 各模型的处理方式

网关按模型决定怎样处理请求体，这决定了哪些参数能生效：

| 模型系列 | 模型 ID | 处理方式 | 网关丢弃的参数 | 返回的图片 |
| --- | --- | --- | --- | --- |
| Seedream 5.0 | `bytedance/doubao-seedream-5.0-pro`<br>`bytedance/doubao-seedream-5.0-lite` | 透传 | 无 | `url`（默认）或 `b64_json` |
| GPT-Image | `openai/gpt-image-2`<br>`openai/gpt-image-2.5-flare`<br>`openai/gpt-image-2.5-sunburst` | 透传 | `response_format`；2.5 两个模型另丢弃 `stream`、`stream_options` | `b64_json` |
| Gemini Image | `google/gemini-3-pro-image`<br>`google/gemini-3.1-flash-image` | 契约转换 | 除 `model`、`prompt`、`size`、`image` 外的全部参数；`size` 无法匹配时也会丢弃 | `b64_json` |

- **透传**：请求体原样发给上游，只改写模型名，服务商支持的其他参数也可以传。参数不被上游接受时，返回的是上游自己的错误。
- **契约转换**：网关把参数翻译成服务商的格式，翻译不了的参数丢弃。
- 被丢弃的参数列在响应头 `X-Gateway-Unsupported-Parameters` 中，请求照常执行；带 `X-Gateway-Strict-Parameters: true` 时改为返回 400。透传给上游的参数不受这个请求头影响。

模型的能力对比和使用场景见[多模态能力](https://platform.lyrouter.com/ai_gateway/docs/multimodal)。模型以模型广场为准，下文按系列列出各自的参数与限制。

### Seedream 5.0（pro / lite）

火山方舟的 Seedream 模型，透传，默认返回图片 URL，单次生成约 20 秒。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `size` | string | 默认 `2K`。推荐写档位名，宽高比在 `prompt` 里用文字描述：pro 为 `1K`、`1.5K`、`2K`，lite 为 `2K`、`3K`、`4K`。也可以写 `宽x高`：pro 要求总像素在 [921600, 4624220] 之间，lite 要求不少于 3686400（最小正方形是 `1920x1920`，常见的 `1024x1024` 会被拒绝），宽高比都要在 [1/16, 16] 之间。两种写法不能混用 |
| `response_format` | string | `url`（默认）或 `b64_json` |
| `image` | string \| array | 参考图，公网 URL 或 `data:image/<格式>;base64,<数据>`（`<格式>` 须小写），建议不超过 10 张，限制见下表 |
| `output_format` | string | `png` 或 `jpeg`。图层拆分时只控制底图格式，图层固定为 PNG |
| `background` | string | `opaque`（默认）或 `transparent`。只用于图生图，且只能输入 1 张带透明通道的图 |
| `watermark` | boolean | `true` 时在右下角加「AI生成」水印。不传时默认加水印，不需要时传 `false` |
| `layer_decomposition` | boolean | 仅 pro，默认 `false`。`true` 时把 1 张输入图拆成 1 张底图和最多 16 个带透明通道的 PNG 图层，`image` 必填且只能 1 张，`size` 只能写档位名（默认 `auto`） |
| `optimize_prompt_options.mode` | string | 仅 pro。`standard`（默认）或 `fast`（更快、质量略低） |

参考图的限制：

| 限制 | 生图 | 图层拆分 |
| --- | --- | --- |
| 格式 | jpeg、png、webp、bmp、tiff、gif、heic、heif | png、jpeg |
| 总像素（宽 × 高） | [196, 36000000] | [262144, 36000000] |
| 宽、高 | 不小于 14 px | — |
| 宽高比（宽/高） | [1/16, 16] | [1/16, 16] |
| 单张大小 | ≤ 30 MB | ≤ 30 MB |
| 张数 | 建议不超过 10 张；超过时服务商目前不拒绝，但输出可能异常 | 仅 1 张 |

- pro 支持交互编辑：在 `prompt` 里用 `<point>x y</point>` 或 `<bbox>x1 y1 x2 y2</bbox>`（坐标归一化到 0～999）指定要改的位置。
- 图层拆分的响应在 `data[]` 中同时返回底图和图层，带 `z_index`、`bounding_box`、`name`、`description` 等字段；每次请求预占 17 张的限流额度，完成后按实际张数返还。各档位对应的像素、坐标换算和还原方法见[多模态能力](https://platform.lyrouter.com/ai_gateway/docs/multimodal#seedream-5-0-pro-lite-火山方舟)。
- 火山方舟的其他参数也可以直接写在请求体里。用 OpenAI Python SDK 时放进 `extra_body`，例如 `extra_body={"watermark": False}`。

**计费**：按张计。pro 按分辨率分档：1K 与 1.5K（≤ 261 万像素）一档、2K 一档，图层拆分另有两档（同样按 1K/1.5K 与 2K 分），按实际产出的张数（底图 + 各图层）计；pro 的参考图单独计一项，每次请求的第 1 张参考图不收费，超出部分按张计（数的是输入的参考图，不是出图张数）。lite 不分档。`1.5K` 与 `1K` 同价且出图更好，没有特殊要求时优先用 `1.5K`。

```bash
curl https://api.lyrouter.com/v1/images/generations \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/doubao-seedream-5.0-lite",
    "prompt": "一只戴墨镜的柴犬坐在冲浪板上，黄昏海面，电影感，横幅构图",
    "size": "2K",
    "watermark": false
  }'
```

### GPT-Image（2 / 2.5-flare / 2.5-sunburst）

透传，参数与 OpenAI 图像 API 一致，固定返回 `b64_json`。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `quality` | string | 取值逐模型不同，见下表。建议所有 GPT-Image 模型都显式传入 |
| `size` | string | 只接受 `宽x高`，不接受档位名（传 `4K` 返回 `Invalid size '4K'. Expected WIDTHxHEIGHT, for example '1824x1024'.`）；须满足下文四条硬约束，否则返回 400 |
| `n` | integer | 生成张数，最大 10 |
| `background` | string | `transparent`、`opaque` 或 `auto` |
| `output_format` | string | 输出格式。`gpt-image-2` 只接受 `png`、`jpeg`，传 `webp` 返回 400 `Invalid value: 'webp'. Supported values are: 'png' and 'jpeg'.`；2.5 系列接受 `png`、`jpeg`、`webp` |
| `moderation` | string | `auto` 或 `low` |
| `user` | string | 终端用户标识 |
| `response_format` | — | 网关丢弃并在响应头中列出：这个系列固定返回 `b64_json`，上游对该参数时而接受、时而报错 |
| `stream`、`stream_options` | — | 2.5 系列由网关丢弃（上游开启流式会使请求失败）；`gpt-image-2` 也不要传 `stream` |

`quality` 的取值：

| 模型 | 取值 | 默认 |
| --- | --- | --- |
| `gpt-image-2` | `low`、`medium`、`high`、`auto` | 无，必填：不传会间歇性返回 400（`INVALID_REQUEST_BODY`）；`auto` 实测等同 `low` |
| `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` | `low`、`medium`、`high`、`xhigh`、`max`、`auto` | `low`（`auto` 实测等同 `low`） |

`xhigh`、`max` 两档是否可用由上游账号能力决定，可能被拒；收到 `Invalid value: 'xhigh'` 时改用 `high`。

`size` 的四条硬约束，由服务商校验，任一不满足返回 400：

| 约束 | 服务商报错原文 | 示例 |
| --- | --- | --- |
| 宽和高都能被 16 整除 | `Invalid size '<宽>x<高>'. Width and height must both be divisible by 16.` | `1008x1008` 可用；`1254x1254`、`1312x1199` 被拒 |
| 最长边不超过 3840 | `Invalid size '<宽>x<高>'. The longest edge must be less than or equal to 3840.` | `3840x2160` 可用；`4096x4096`、`1024x4096` 被拒 |
| 总像素不少于约 100 万 | `Invalid size '<宽>x<高>'. Requested resolution is below the current minimum pixel budget.` | `1008x1008`（约 102 万）可用；`512x1024`（约 52 万）被拒 |
| 总像素不超过约 830 万 | `Invalid size '<宽>x<高>'. Requested resolution exceeds the current pixel budget.` | `3840x2160`（约 829 万）可用；`3840x2176`（约 836 万）被拒 |

- **耗时**：一次生成实测约 20～60 秒，偶有更长（最长一次约 83 秒）；参数错误导致的上游 400 实测在 2 秒内返回。客户端超时请按分钟设置，不低于 300 秒。

**计费**：按 Token 计，输入文本、输入图片、输出分别计价，上游在 `usage.input_tokens_details` 中分开上报文字与图片 Token，所以同样长度的提示词，带图与不带图费用不同。缓存命中另有一项单价；2.5 系列的 `usage` 不含缓存字段，不产生这一项。

输出 Token 主要由 `quality` 决定：`1024x1024` 时 2.5 系列 `low` 输出 196 Token、`max` 输出 7024 Token，最高档约为最低档的 36 倍。同名档位在两代模型上不是同一个量：2.5 系列的 `high` 与 `gpt-image-2` 的 `medium` 输出 Token 相同，跨模型比较请比 Token，不要比档位名。另外，GPT-Image 不是像素越多越贵（只适用于 GPT-Image）：输出 Token 不随像素增加，例如 `1024x1536`（约 157 万像素）的输出 Token 比 `1024x1024`（约 105 万像素）还少。

### Gemini Image（3 Pro / 3.1 Flash）

契约转换：网关把请求翻译成 Gemini 原生的 `generateContent` 格式，只使用下表中生效的参数，其余参数丢弃并在响应头中列出。固定返回 `b64_json`，不能返回 URL。单次生成实测 20～250 秒（`gemini-3-pro-image`），偶有超过 300 秒仍未返回。

| 参数 | 是否生效 | 说明 |
| --- | --- | --- |
| `prompt` | 生效 | 必填，不写或为空返回 400 `prompt is required for this model` |
| `size` | 生效 | 写法见下表 |
| `image` | 生效 | 参考图，写法见[图像编辑](https://platform.lyrouter.com/ai_gateway/docs/images-edits) |
| `n` | 丢弃 | 需要多张图请发多次请求 |
| `quality` | 丢弃 | Gemini 没有对应参数 |
| `response_format` | 丢弃 | 只能返回 `b64_json` |
| `user` 及其他参数 | 丢弃 | — |

`size` 的写法决定了比例和分辨率：

| 写法 | 网关的处理 | 效果 |
| --- | --- | --- |
| 档位名：`1K`、`2K`、`4K` | 原样作为分辨率档位 | 控制分辨率，宽高比由上游默认 |
| `宽x高`，如 `1376x768` | 匹配最接近的支持比例（误差 2% 以内），再按长边向上取分辨率档位 | 同时控制比例和分辨率 |
| 宽高比超出 2% 误差，如 `1000x700` | 整个 `size`（比例和档位）都不下发，`size` 计入丢弃参数 | 返回 200、照常出图并计费，但比例和分辨率都是上游默认值，唯一的信号是响应头 `X-Gateway-Unsupported-Parameters: size`；严格模式下返回 400 |
| 比例字符串，如 `16:9` | 当作档位名原样传给上游 | 上游不认识，返回 400（`upstream_rejected`）。要 16:9 请写该比例的宽高，如 `1376x768` |

`512` 档在生产环境被服务商拒绝（两个模型都是），不要使用。

支持的宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`、`1:4`、`4:1`、`1:8`、`8:1`。写宽高时按长边向上取档，超过 4K 的按 4K；长边不超过 704 时网关会映射到 `512` 档，同样可能被拒绝，请让长边大于 704。同一档位在两个模型上的输出 Token 不同：

| 长边 | 档位 | `gemini-3-pro-image` 输出 Token | `gemini-3.1-flash-image` 输出 Token |
| --- | --- | --- | --- |
| ≤ 1376 | `1K` | 1120 | 1120 |
| ≤ 2816 | `2K` | 1120（2K 档不生效，与 1K 相同） | 1680 |
| 更大（封顶） | `4K` | 2000 | 2520 |

出图尺寸由服务商按比例档和分辨率档决定，不等于请求的宽高，例如 `gemini-3-pro-image` 请求 `4096x2304` 实际出图 `5504x3072`；请以返回图片的实际宽高为准。

例如 `1024x1024` 映射为 1:1 + `1K`，`2048x2048` 映射为 1:1 + `2K`。要 16:9 + 4K 请写 `4096x2304`，不要照抄 `5632x3072`：它的比例是 1.833，偏离 16:9 超过 2%，整个 `size` 会被丢弃。生产环境建议带 `X-Gateway-Strict-Parameters: true`，让这种请求改为返回 400。

**计费**：按 Token 计，输入、输出、思考三项分别计价；带参考图时，输入图片并入「输入」。思考 Token 只在上游返回时出现（`gemini-3-pro-image`），位于 `usage.output_tokens_details.reasoning_tokens`，`usage.total_tokens` 包含它。思考 Token 每次不同，由模型自行决定：生产实测 115～316 个、中位约 220，约占单次费用的 1.5%，预算时可按每次约 220 个估算。

```json
{
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…" }],
  "usage": {
    "input_tokens": 7,
    "output_tokens": 1120,
    "total_tokens": 1339,
    "output_tokens_details": { "reasoning_tokens": 212 }
  }
}
```

## 请求示例

下面以 `openai/gpt-image-2` 为例，把返回的 Base64 图片保存为文件。换成 Seedream 时，图片默认以 URL 返回，读取 `data[0].url` 并及时下载。

**请求示例**

cURL:
```bash
curl https://api.lyrouter.com/v1/images/generations \
  --max-time 300 \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "一只戴墨镜的柴犬坐在冲浪板上，黄昏海面，电影感",
    "size": "1024x1024",
    "quality": "medium"
  }'
```

Python:
```python
import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com/v1",
    timeout=300,
)
result = client.images.generate(
    model="openai/gpt-image-2",
    prompt="一只戴墨镜的柴犬坐在冲浪板上，黄昏海面，电影感",
    size="1024x1024",
    quality="medium",
)
with open("shiba.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
print(result.usage)
```

Node.js:
```js
import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com/v1",
  timeout: 300_000,
});
const result = await client.images.generate({
  model: "openai/gpt-image-2",
  prompt: "一只戴墨镜的柴犬坐在冲浪板上，黄昏海面，电影感",
  size: "1024x1024",
  quality: "medium",
});
writeFileSync("shiba.png", Buffer.from(result.data[0].b64_json, "base64"));
console.log(result.usage);
```

## 响应

成功时返回 OpenAI Images 格式的对象，图片在顶层 `data` 数组中；出错时返回 `error` 对象。下面的 200 分别是 Seedream（返回 URL）和 GPT-Image（返回 Base64），400 是开启严格模式时给 Gemini 传了它不支持的参数，403 是模型未开通，或使用了虚拟模型、Auto。

**响应示例**

200（url）:
```json
{
  "model": "doubao-seedream-5-0-260128",
  "created": 1789454321,
  "data": [
    {
      "url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/…",
      "size": "1920x1920"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 14400,
    "total_tokens": 14400
  }
}
```

200（b64_json）:
```json
{
  "created": 1791950400,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…" }
  ],
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "background": "opaque",
  "usage": {
    "input_tokens": 29,
    "input_tokens_details": { "text_tokens": 29, "image_tokens": 0 },
    "output_tokens": 1756,
    "total_tokens": 1785
  }
}
```

400:
```json
{
  "error": {
    "message": "unsupported parameters for this model: n,quality",
    "type": "invalid_request_error",
    "code": "unsupported_parameters"
  }
}
```

403:
```json
{
  "error": {
    "message": "Model is not available in the model plaza",
    "type": "access_denied",
    "code": "model_not_available"
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `created` | Unix 时间戳（秒）。Gemini 不返回这个字段 |
| `model` | 服务商侧的模型名（Seedream 返回），例如 `doubao-seedream-5-0-260128`，与请求中的模型 ID 不同 |
| `data` | 产物数组，只生成一张时也是数组 |
| `data[].url` | 图片下载地址，Seedream 默认返回。这是服务商签发的临时地址，约 24 小时后失效，请及时下载保存 |
| `data[].b64_json` | Base64 编码的图片。GPT-Image、Gemini 固定返回；Seedream 在 `response_format` 为 `b64_json` 时返回 |
| `data[].size` | 实际生成的尺寸（Seedream 返回） |
| `data[].output_format` | 图片格式（Seedream pro 返回） |
| `size`、`quality`、`output_format`、`background` | 本次实际使用的生成参数（GPT-Image 返回） |
| `usage` | 计量信息，字段随模型变化，见下表 |

### usage 的字段

| 模型系列 | `usage` 中的字段 | 计量方式 |
| --- | --- | --- |
| Seedream | `generated_images`（生成张数）、`output_tokens`、`total_tokens`；pro 带参考图时另有 `input_images`（输入的参考图张数） | 按张 |
| GPT-Image | `input_tokens`、`input_tokens_details.text_tokens` / `image_tokens`、`output_tokens`、`total_tokens` | 按 Token |
| Gemini | `input_tokens`、`output_tokens`、`total_tokens`，有思考 Token 时另有 `output_tokens_details.reasoning_tokens` | 按 Token |

不要假设某个字段一定存在，读取前先判断。各模型的计费方式见上文模型小节，单价以控制台模型广场为准，每次调用的实际扣费在[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中查看。

### 响应头

| 响应头 | 说明 |
| --- | --- |
| `X-Gateway-Unsupported-Parameters` | 网关丢弃了参数时出现，值为逗号分隔的参数名，例如 `n,quality`。请求照常执行，列出的参数没有生效 |

配置了配额时，响应还会带 `x-aigw-quota-*` 系列响应头，见[网关扩展请求头与响应头](https://platform.lyrouter.com/ai_gateway/docs/gateway-headers)。

这样读取被丢弃的参数（Python、Node.js 沿用上文示例中的 `client`）：

**读取被丢弃的参数**

cURL:
```bash
curl -sS -D - -o result.json https://api.lyrouter.com/v1/images/generations \
  --max-time 300 \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.1-flash-image","prompt":"一片绿色的叶子，扁平风格","size":"1376x768","n":2}'
# 响应头中出现：X-Gateway-Unsupported-Parameters: n
```

Python:
```python
raw = client.images.with_raw_response.generate(
    model="google/gemini-3.1-flash-image",
    prompt="一片绿色的叶子，扁平风格",
    size="1376x768",
    n=2,
)
print(raw.headers.get("X-Gateway-Unsupported-Parameters"))  # n
result = raw.parse()
```

Node.js:
```js
const { data: result, response } = await client.images
  .generate({
    model: "google/gemini-3.1-flash-image",
    prompt: "一片绿色的叶子，扁平风格",
    size: "1376x768",
    n: 2,
  })
  .withResponse();
console.log(response.headers.get("X-Gateway-Unsupported-Parameters")); // n
```

## 网关行为

与直接调用上游相比，经 LYRouter 调用有以下差别：

- **只用指定的模型**：图像接口不会改用其他模型。同一模型有多个通道时，失败后依次尝试其他通道；虚拟模型、Auto 智能路由和工作空间默认模型的回退都不用于图像接口，见[失败重试与备用模型](https://platform.lyrouter.com/ai_gateway/docs/fallback)。
- **丢弃参数与严格模式**：网关只丢弃上文「各模型的处理方式」中列出的参数，并在响应头 `X-Gateway-Unsupported-Parameters` 中列出。生产环境建议检查这个响应头，或者带上 `X-Gateway-Strict-Parameters: true`，让请求在出现会被丢弃的参数时直接返回 400、不调用上游、不计费。用 SDK 时通过 `extra_headers={"X-Gateway-Strict-Parameters": "true"}`（Python）或请求选项 `{ headers: { "X-Gateway-Strict-Parameters": "true" } }`（Node.js）传入。透传给上游的参数不受这个请求头影响，参数是否被接受由上游判断。
- **上游在成功响应里声明错误**：Gemini 的上游拒绝请求时可能返回 HTTP 200 而没有图片。网关把它改写成错误响应，状态码取上游声明的错误：上游拒绝时 `error.code` 为 `upstream_rejected`，`error.message` 是上游原文；没有产出图片时为 `upstream_no_artifact`，并带 `upstream_finish_reason`（如 `NO_IMAGE`、`SAFETY`）。`upstream_status` 保留上游原本的 200。这类错误不换通道重试，请按提示修改提示词或参数：

  ```json
  {
    "error": {
      "message": "upstream produced no image (finishReason: NO_IMAGE)",
      "type": "invalid_request_error",
      "code": "upstream_no_artifact",
      "upstream_status": 200,
      "upstream_finish_reason": "NO_IMAGE",
      "generated_by": "ai-gateway"
    }
  }
  ```

- **上游错误原样返回**：透传模型的参数错误由上游返回，格式和错误码以上游为准，例如 Seedream 返回 `{"error":{"code":"InvalidParameter","message":"..."}}`。上游返回错误状态却没有响应体时，网关补一个错误体，带 `upstream_status` 和 `generated_by: "ai-gateway"`；上游提供了请求 ID 时还带 `upstream_request_id`，向服务商报障时提供它。
- **日志中不保存图片**：请求和响应中的 Base64 图片在日志里替换成 `[base64 <字节数>B #<CRC32>]` 摘要，日志详情里看不到图片不代表请求失败，图片在响应体里。返回 URL 的模型，URL 保留在日志中。
- **超时**：图像接口同步返回，Seedream 约 20 秒，GPT-Image 系列实测约 20～60 秒，Gemini 实测 20～250 秒、偶有超过 300 秒。客户端超时请按分钟设置，不低于 300 秒，不要沿用文本接口的 30 秒；客户端超时后不要立即重复提交，先在[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中确认上一次请求的结果。

## 常见错误

网关返回的错误为 `{"error":{"message":"...","type":"...","code":"..."}}`；透传模型的参数错误由上游返回，格式以上游为准。

| 状态码 | `error.message` | `error.code` | 原因与处理 |
| --- | --- | --- | --- |
| 400 | `you must provide a model parameter` | `missing_model` | 没有写 `model`，工作空间也没有默认模型。图像接口请总是写明模型 ID |
| 400 | `unsupported parameters for this model: <参数名>` | `unsupported_parameters` | 带了 `X-Gateway-Strict-Parameters: true`，且请求中有会被丢弃的参数。删掉列出的参数，或换用支持它们的模型 |
| 400 | `prompt is required for this model` | `invalid_parameter` | 调用 Gemini 时没有写 `prompt` 或为空 |
| 400 | 上游原文，例如 `Request contains an invalid argument.` | `upstream_rejected` | Gemini 的上游拒绝了请求，例如 `size` 写成了 `16:9`。按原文修改参数 |
| 400 | `upstream produced no image (finishReason: <原因>)` | `upstream_no_artifact` | Gemini 没有产出图片，按 `upstream_finish_reason` 修改提示词或内容后重试 |
| 400 | ``The parameter `size` specified in the request is not valid: image size must be at least 3686400 pixels`` | `InvalidParameter` | Seedream lite 的尺寸低于下限。改用 `2K` 档位或更大的宽高，如 `1920x1920` |
| 400 | `Invalid size '<宽>x<高>'. Width and height must both be divisible by 16.` | — | GPT-Image 的宽或高不是 16 的倍数，由上游返回 |
| 400 | `Invalid size '<宽>x<高>'. The longest edge must be less than or equal to 3840.`、`Invalid size '<宽>x<高>'. Requested resolution is below the current minimum pixel budget.`、`Invalid size '<宽>x<高>'. Requested resolution exceeds the current pixel budget.` | — | GPT-Image 的 `size` 最长边超过 3840，或总像素不在约 100 万到约 830 万之间，由上游返回。按上文 `size` 的四条硬约束调整 |
| 400 | `Invalid size '4K'. Expected WIDTHxHEIGHT, for example '1824x1024'.` | — | 给 GPT-Image 传了档位名。改写成 `宽x高` |
| 400 | `Invalid value: 'xhigh'` | — | 上游账号不支持 `xhigh` / `max` 这两档 `quality`（是否可用由上游账号能力决定）。改用 `high` |
| 400 | 上游原文 | `INVALID_REQUEST_BODY` | GPT-Image 请求体不合法，先检查是否传了 `quality`：`gpt-image-2` 不传会间歇性返回 400 |
| 400 | `This model does not support the images API` | `unsupported_model_api` | 模型声明的接口类型（[列出模型](https://platform.lyrouter.com/ai_gateway/docs/models)中的 `api_types`）不含图像接口，例如用对话模型调用本接口。没有声明 `api_types` 的对话模型不会触发这条，请求会转发给上游，可能返回 404 `upstream_not_found`，或返回没有图片的 200（如 `{"data":{"content":null}}`）。图像接口请只用图像模型 |
| 403 | `Model is not available in the model plaza` | `model_not_available` | 工作空间没有开通这个模型，或者写了 `@vmodel/<名称>`、`lyrouter/auto`。请管理员在模型广场开通，或改写已开通的具体模型 ID |

- 401 / 403 鉴权问题见[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)，429 见[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。
- 500 / 504 是连接上游失败或等待上游超时，响应体是 HTML 页面而不是 JSON，见[超时与流式中断](https://platform.lyrouter.com/ai_gateway/docs/stream-errors)。
- 完整列表见[错误码与请求标识](https://platform.lyrouter.com/ai_gateway/docs/errors)。