图像生成

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

鉴权

在请求头中携带 API Key：

Authorization: Bearer <API Key>

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

请求头

请求体

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

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

各模型的处理方式

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

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

模型的能力对比和使用场景见多模态能力。模型以模型广场为准，下文按系列列出各自的参数与限制。

Seedream 5.0（pro / lite）

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

参考图的限制：

• pro 支持交互编辑：在 prompt 里用 <point>x y</point> 或 <bbox>x1 y1 x2 y2</bbox>（坐标归一化到 0～999）指定要改的位置。
• 图层拆分的响应在 data[] 中同时返回底图和图层，带 z_index、bounding_box、name、description 等字段；每次请求预占 17 张的限流额度，完成后按实际张数返还。各档位对应的像素、坐标换算和还原方法见多模态能力。
• 火山方舟的其他参数也可以直接写在请求体里。用 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。

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 的取值：

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

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

• 耗时：一次生成实测约 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 秒仍未返回。

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

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 请求 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 个估算。

{
  "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 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"
  }'

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)

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。

{
  "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
  }
}

{
  "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
  }
}

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

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

usage 的字段

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

响应头

配置了配额时，响应还会带 x-aigw-quota-* 系列响应头，见网关扩展请求头与响应头。

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

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

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()

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 智能路由和工作空间默认模型的回退都不用于图像接口，见失败重试与备用模型。

• 丢弃参数与严格模式：网关只丢弃上文「各模型的处理方式」中列出的参数，并在响应头 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。这类错误不换通道重试，请按提示修改提示词或参数：

  复制代码

  {
    "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 秒；客户端超时后不要立即重复提交，先在请求日志中确认上一次请求的结果。

常见错误

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

• 401 / 403 鉴权问题见401 / 403：鉴权与权限，429 见429：限流与配额。
• 500 / 504 是连接上游失败或等待上游超时，响应体是 HTML 页面而不是 JSON，见超时与流式中断。
• 完整列表见错误码与请求标识。