图像

Lovely Router 提供 OpenAI Images API：POST /v1/images/generations 和 POST /v1/images/edits。把 OpenAI SDK 指向 https://lovelyrouter.com/v1，并使用你的 Lovely Router 密钥。请求按 OpenAI 的定义原样传递，因此 OpenAI 的 Images API 参考同样适用，但有下方列出的限制。

模型#

GPT Image 模型支持生成和编辑，也支持参考图；z-image-turbo-nsfw-v2 只支持生成。quality 对 GPT Image 2.5 模型和 z-image-turbo-nsfw-v2 不起作用。

图像模型只响应 Images API。发送到 Chat Completions 时会返回 404，并提示改用 /v1/images/generations。GPT Image 模型由 gpt-value 渠道分组提供，z-image-turbo-nsfw-v2 由 creative-hosted 提供，绑定到其他分组的密钥无法使用。

生成图像#

curl https://lovelyrouter.com/v1/images/generations \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor painting of a red fox in a snowy birch forest at dawn",
    "size": "1024x1024",
    "quality": "medium"
  }' | jq -r '.data[0].b64_json' | base64 --decode > fox.png

精简后的响应：

{
  "created": 1792064388,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…" }],
  "background": "auto",
  "model": "gpt-image-2",
  "output_format": "png",
  "quality": "medium",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 19,
    "input_tokens_details": { "text_tokens": 19, "image_tokens": 0 },
    "output_tokens": 1756,
    "output_tokens_details": { "image_tokens": 1756, "text_tokens": 0 },
    "total_tokens": 1775
  }
}

图像始终以 base64 形式在 b64_json 中返回，response_format: "url" 会被忽略。生成一张图像通常需要 40 秒到 2 分钟，另加在队列中等待的时间，因此请把 HTTP 客户端的超时设为至少十分钟（网关会在九分钟内响应）。一张 3840×2160 的 PNG 约 14 MB，转成 base64 约 18 MB。如果想先提交、稍后再取，而不是一直保持连接，请使用图像任务。

尺寸和质量#

• size：1024x1024、1536x1024、1024x1536、2048x2048、3840x2160，或任意 WIDTHxHEIGHT：两边都是 16 的倍数，长边不超过 3840 像素且不超过短边的三倍，总像素在 655,360 到 8,294,400 之间。auto 由模型自行选择。
• quality：low、medium、high 或 auto（默认）。所有质量的价格相同。
• output_format：png（默认）、jpeg 或 webp。output_compression（0 到 100）适用于 jpeg 和 webp。
• background：transparent 可与 png 和 webp 一起使用。

一次生成多张#

设置 n（1 到 10），一个请求即可得到同一提示词的多张图片，生成和编辑都适用。图片会一起在 data 中返回。

result = client.images.generate(
    model="gpt-image-2",
    prompt="A watercolor painting of a red fox in a snowy birch forest at dawn",
    n=4,
)
for i, image in enumerate(result.data):
    with open(f"fox-{i + 1}.png", "wb") as f:
        f.write(base64.b64decode(image.b64_json))

• 每张图片按单张价格计费，四张就是四倍价格。提交时会预留全部 n 张的价格，只按实际得到的图片收费。
• 每个渠道会用尽可能少的模型调用生成这些图片。GPT Image 模型的 n: 4 通常和一张图片耗时差不多；托管模型会在同一块 GPU 上依次生成。
• 如果有部分图片未能生成，你会得到已生成的那些，并只为它们付费。此时图像任务为 status: "succeeded"，error.type 为 "incomplete"，错误信息会说明缺了几张。
• 每张图片都计入每个账户最多可同时排队或生成中的 20 张图片。

编辑图像#

所有模型都支持编辑，包括 GPT Image 2.5。以 multipart/form-data 把一张或多张图像（以及可选的 mask）发送到 POST /v1/images/edits。模型、提示词和其他选项的用法与生成相同。要给模型多张图作为参考，请看参考图。

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=gpt-image-2 \
  -F image=@fox.png \
  -F prompt="Make it night with a full moon" \
  -F quality=medium | jq -r '.data[0].b64_json' | base64 --decode > fox-night.png

使用 GPT Image 2.5 时，把 model 设为 gpt-image-2.5-flare 或 gpt-image-2.5-sunburst，并省略 quality（这些模型会忽略它）：

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=gpt-image-2.5-flare \
  -F image=@fox.png \
  -F prompt="把它改成夜晚，加上一轮满月" | jq -r '.data[0].b64_json' | base64 --decode > fox-night.png

编辑与生成的价格相同。

参考图#

最多可给模型 16 张图作为参考，例如产品、Logo、人物或风格，并在提示词中说明每张图要用哪部分。每张图作为一个 image[] 文件发送；向 OpenAI SDK 传入列表时，SDK 就是这样发送的。

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=gpt-image-2.5-flare \
  -F "image[]=@mug.png" \
  -F "image[]=@table.jpg" \
  -F prompt="把第一张图里的杯子放在第二张图的木桌上，清晨光线" \
  | jq -r '.data[0].b64_json' | base64 --decode > mug-on-table.png

也可以发送 JSON，用 URL 或 base64 data: URL 给出图片：

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "同一个角色，现在在挥手，扁平插画",
    "images": [
      {"image_url": "https://example.com/character.png"},
      {"image_url": "data:image/png;base64,iVBORw0KGgo..."}
    ]
  }' | jq -r '.data[0].b64_json' | base64 --decode > waving.png

• image 也接受一个 URL 或 URL 列表，mask 接受一个。不支持以 file_id 指定的图片。
• URL 在请求到达时下载一次，必须可公开访问，并在 20 秒内响应。
• 输入图片为 PNG、JPEG 或 WebP，合计不超过 50 MB。
• 发往 POST /v1/images/generations 且带有输入图片的请求会按编辑处理。

定价#

GPT Image 模型为 每张 $0.04，z-image-turbo-nsfw-v2 为 每张 $0.03，与尺寸和质量无关，生成和编辑价格相同。响应中的 usage 仅供参考，不影响价格。渠道分组的倍率同样适用（gpt-value 和 creative-hosted 均为 ×1.00）。

GET /v1/models 以 pricing.per_image（美元）显示当前价格。每次调用都会在日志中显示其费用。

提交图片时，其价格会先从余额中预留，图片完成后再释放。使用 n 时预留全部 n 张的价格，只按实际得到的图片收费。请求被拒绝、任务被取消或没有生成图像时不收费。图像一旦生成就会计费，即使你的客户端在收到之前已断开连接。

请求如何排队#

每个图像请求都会进入队列，图像容量一有空闲就开始，因此一批同时到达的请求会依次等待，而不会失败。POST /v1/images/generations 和 POST /v1/images/edits 会保持连接直到图片完成，最长 9 分钟。若届时仍未完成，会返回 504，并在 x-lovely-image-job 响应头和错误信息中给出任务 id；图片会继续生成，完成后计费，你可以通过 GET /v1/images/jobs/{id} 获取。

• 每个账户最多可同时有 20 张图片在排队或生成中，带 n 的请求按其每张图片计算。会超过 20 张的请求返回 429，直到有图片完成。
• 30 分钟内无法开始的图片会以 429 失败，不收费。
• 每个响应都带有 x-lovely-request-id 响应头（即任务 id），可在日志中找到对应调用。

图像任务#

图像任务与上述请求相同，只是不必一直保持连接：先提交，再轮询或长轮询。适合批量生成，或客户端无法等待数分钟的场景。

curl https://lovelyrouter.com/v1/images/jobs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "A watercolor painting of a red fox in a snowy birch forest at dawn", "size": "1536x1024"}'

请求体与 POST /v1/images/generations 的字段相同。带有输入图片即为编辑，与 POST /v1/images/edits 相同：以 multipart/form-data 附带 image 文件，或在 JSON 中使用 images。加上 wait（0 到 300 秒，可放在请求体或 ?wait= 中）可在返回前等待任务：在时限内完成则返回 200，否则返回 202。

然后等待它完成。wait 会让请求一直等到任务完成或超时：

curl "https://lovelyrouter.com/v1/images/jobs/img_8c1f0e2a9b7d4f3e6a5c2b1d?wait=60" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

已完成的任务状态为 status: "succeeded"，带有 charge_usd，以及包含图片 url、content_type、bytes、size 和 usage 的 result。result.images 列出任务的每张图片及各自的 url、content_type 和 bytes：n 大于 1 时，第一张在 /content，其余在 /content/1、/content/2 等。用同一个密钥从该 URL 下载图片文件：

curl -o fox.png https://lovelyrouter.com/v1/images/jobs/img_8c1f0e2a9b7d4f3e6a5c2b1d/content \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Playground 使用图像任务：切换到 Images，无需写代码即可试用提示词和编辑。

限制#

• 每个请求最多 10 张图像（n）。需要更多时请发送多个请求或任务。
• 不支持流式。stream: true 返回 400，暂不提供部分图像（partial images）。
• 不支持变体。POST /v1/images/variations（仅 DALL·E 2）返回 404。
• 密钥的每分钟请求数限制适用于提交图片。每个账户最多可同时有 20 张图片在排队或生成中。