图像编辑

按提示词修改输入的图片，或以一张、多张图片为参考生成新图。兼容 OpenAI Images API 的 images.edit，请求体有两种写法：multipart/form-data 上传图片文件（OpenAI 官方 SDK 的写法），或 JSON 把图片以 Base64 放在请求体里（LYRouter 的扩展）。支持编辑的是 GPT-Image 和 Gemini Image 两个系列，两种写法都可用；Seedream 不支持本接口，它的图生图请用图像生成的 image 参数。

鉴权

在请求头中携带 API Key：

Authorization: Bearer <API Key>

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

请求头

请求体

两种写法的字段名相同，GPT-Image 和 Gemini 都支持，按调用方便选择即可。

multipart/form-data

• GPT-Image：网关只改写 model 字段，文件和其他字段一个字节都不动，原样发给上游。
• Gemini：网关解析表单，把文件转成 Base64（格式取自文件段的 Content-Type，没有时按文件头识别），再按 JSON 写法转换。所有文件合计不能超过 30 MB，超过返回 400。

JSON

OpenAI 官方的 /images/edits 只收 multipart，JSON 写法是 LYRouter 的扩展，图片以 Base64 放在 image 中。

各模型的处理方式

被丢弃的参数列在响应头 X-Gateway-Unsupported-Parameters 中，请求照常执行；带 X-Gateway-Strict-Parameters: true 时改为返回 400。模型的能力对比和使用场景见多模态能力。

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

透传：请求体原样发给上游，只改写模型名，参数与 OpenAI 图像 API 一致，固定返回 b64_json。

• 耗时：两种写法在网关侧的开销相同（约 0.1 秒），耗时几乎全在上游，单次从 20 秒到 4 分钟以上不等，同样的请求两次耗时也可能差好几倍。客户端超时请设为不低于 300 秒。
• 图片校验：上游会校验图片本身，过小或损坏的图片会被拒绝（例如返回 Invalid image file or mode），请换一张正常的图片重试。

计费：与图像生成相同，按 Token 计，输入文本、输入图片、输出分别计价。编辑比生成多一项输入图片的费用：图片按 32×32 像素一块折算成 Token，记在 usage.input_tokens_details.image_tokens：长边不足 1024 时先放大到长边的 2 倍（最多 1024），像素超过约 152 万时先等比缩小，再按 ceil(宽/32) × ceil(高/32) 计。实测 1024×1024 的图为 1024 Token，8×8 的图为 1 Token。mask 也按同样的规则计入 image_tokens：实测 1024×1024 的原图加同尺寸的 mask，image_tokens 为 2048。同样的 quality 和 size 下，编辑与生成的输出 Token 相同；输出 Token 随 quality 的量级差异见图像生成。

Gemini Image（3 Pro / 3.1 Flash）

契约转换：网关把请求翻译成 Gemini 原生的 generateContent 格式，只使用下表中生效的参数，其余参数丢弃并在响应头中列出。固定返回 b64_json。

• multipart 写法中，所有文件合计不超过 30 MB。OpenAI 官方 SDK 的 images.edit() 总是以 multipart 发送，可以直接用来调用 Gemini。

计费：按 Token 计，输入、输出、思考三项分别计价，输入图片并入「输入」（usage.input_tokens），每张输入图按固定 Token 数计，与图片尺寸无关：生产实测 gemini-3-pro-image 每张 560，gemini-3.1-flash-image 每张 1120，两者相差一倍。思考 Token 的说明见图像生成。

请求示例

multipart/form-data

以 openai/gpt-image-2 为例，上传 cat.png 并把结果保存为文件。Python 示例需要较新版本的 openai SDK：实测 1.58.1 的 images.edit() 不接受 quality，会报 TypeError: edit() got an unexpected keyword argument 'quality'。

curl https://api.lyrouter.com/v1/images/edits \
  --max-time 300 \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -F model=openai/gpt-image-2 \
  -F quality=medium \
  -F image=@cat.png \
  -F prompt="把背景换成雪山"

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,
)
with open("cat.png", "rb") as image:
    result = client.images.edit(
        model="openai/gpt-image-2",
        image=image,
        prompt="把背景换成雪山",
        quality="medium",
    )
with open("cat-snow.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
print(result.usage)

import { createReadStream, writeFileSync } from "node:fs";
import OpenAI, { toFile } 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.edit({
  model: "openai/gpt-image-2",
  // 用 toFile 指明图片类型：直接传 createReadStream 时文件段的类型是 application/octet-stream，上游返回 400
  image: await toFile(createReadStream("cat.png"), "cat.png", { type: "image/png" }),
  prompt: "把背景换成雪山",
  quality: "medium",
});
writeFileSync("cat-snow.png", Buffer.from(result.data[0].b64_json, "base64"));
console.log(result.usage);

JSON

以 google/gemini-3-pro-image 为例，把图片转成 Base64 放进请求体：

printf '{"model":"google/gemini-3-pro-image","prompt":"把背景换成雪山","image":"data:image/png;base64,%s"}' \
  "$(base64 < cat.png | tr -d '\n')" > body.json
curl https://api.lyrouter.com/v1/images/edits \
  --max-time 300 \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @body.json

import base64
import os
import httpx

with open("cat.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()
resp = httpx.post(
    "https://api.lyrouter.com/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['LYROUTER_API_KEY']}"},
    json={
        "model": "google/gemini-3-pro-image",
        "prompt": "把背景换成雪山",
        "image": f"data:image/png;base64,{b64}",  # 多张图时传数组
    },
    timeout=300,
)
resp.raise_for_status()
with open("cat-snow.png", "wb") as f:
    f.write(base64.b64decode(resp.json()["data"][0]["b64_json"]))

import { readFileSync, writeFileSync } from "node:fs";

const b64 = readFileSync("cat.png").toString("base64");
const resp = await fetch("https://api.lyrouter.com/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "google/gemini-3-pro-image",
    prompt: "把背景换成雪山",
    image: `data:image/png;base64,${b64}`, // 多张图时传数组
  }),
  signal: AbortSignal.timeout(300_000),
});
const result = await resp.json();
if (!resp.ok) throw new Error(JSON.stringify(result.error));
writeFileSync("cat-snow.png", Buffer.from(result.data[0].b64_json, "base64"));

响应

响应格式与图像生成相同：成功时图片在顶层 data 数组中，以 b64_json 返回；出错时返回 error 对象。下面的 200 是 GPT-Image 的编辑结果（上文 multipart 示例，未传 size），400 是开启严格模式时给 Gemini 传了它不支持的 quality，403 是模型未开通，或使用了虚拟模型、Auto。

{
  "created": 1791950400,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…" }
  ],
  "size": "1254x1254",
  "quality": "medium",
  "output_format": "png",
  "background": "opaque",
  "usage": {
    "input_tokens": 1036,
    "input_tokens_details": { "text_tokens": 12, "image_tokens": 1024 },
    "output_tokens": 2058,
    "total_tokens": 3094
  }
}

{
  "error": {
    "message": "unsupported parameters for this model: 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"
  }
}

单价以控制台模型广场为准，每次调用的实际扣费在请求日志中查看。

响应头

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

网关行为

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

• 两种请求体：GPT-Image 的 multipart 请求只改写 model 字段，文件原样转发；JSON 请求原样转发。Gemini 的两种写法都先归一成同一组字段，再翻译成 Gemini 的格式，因此行为完全相同。
• 只用指定的模型：图像接口不会改用其他模型。同一模型有多个通道时，失败后依次尝试其他通道；虚拟模型、Auto 智能路由和工作空间默认模型的回退都不用于图像接口，见失败重试与备用模型。
• 丢弃参数与严格模式：只有 Gemini 会丢弃参数，并在响应头 X-Gateway-Unsupported-Parameters 中列出；带 X-Gateway-Strict-Parameters: true 时改为直接返回 400、不调用上游、不计费。GPT-Image 的参数全部原样转发，是否被接受由上游判断。
• 上游在成功响应里声明错误：Gemini 的上游拒绝请求时可能返回 HTTP 200 而没有图片。网关把它改写成错误响应：上游拒绝时 error.code 为 upstream_rejected，error.message 是上游原文；没有产出图片时为 upstream_no_artifact，并带 upstream_finish_reason（如 NO_IMAGE、SAFETY）。upstream_status 保留上游原本的 200。这类错误不换通道重试，请按提示修改提示词或图片。
• 上游错误原样返回：GPT-Image 的参数和图片错误由上游返回，格式和错误码以上游为准。上游返回错误状态却没有响应体时，网关补一个错误体，带 upstream_status 和 generated_by: "ai-gateway"；上游提供了请求 ID 时还带 upstream_request_id，向服务商报障时提供它。
• 日志中不保存图片：请求和响应中的 Base64 图片在日志里替换成 [base64 <字节数>B #<CRC32>] 摘要，日志详情里看不到图片不代表请求失败，图片在响应体里。
• 超时：编辑同样是同步返回，GPT-Image 系列常需数分钟。客户端超时请设为不低于 300 秒；客户端超时后不要立即重复提交，先在请求日志中确认上一次请求的结果。

常见错误

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

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