OpenAI 图像格式

RouteAPI 通过 OpenAI 兼容的 images 端点提供图像生成能力。本页介绍所有厂商共用的请求格式，以及 OpenAI gpt-image 系列——当前在售的是 gpt-image-2。其他厂商的请求会被适配到同一组端点，模型特有的行为单独说明：Nano Banana 介绍 Gemini 图像模型，Seedream 介绍火山引擎 Seedream。

一个模型能否生成图像，可以在模型列表中看到：其 supported_endpoint_types 包含 image-generation。字段的读法见模型。

端点

POST /v1/images/generations
POST /v1/images/edits

完整地址：

https://api.routeapi.ai/v1/images/generations
https://api.routeapi.ai/v1/images/edits

/v1/images/generations 接收 JSON 请求体。/v1/images/edits 接收 multipart/form-data——或者在 OpenAI 兼容渠道上，接收通过 URL 或 Base64 引用图像的 JSON 请求体（见 JSON 编辑）。

生成图像

请求参数

字段	类型	必填	说明
`model`	string	是	来自 `GET /v1/models` 的模型 ID，例如 `gpt-image-2`
`prompt`	string	是	待生成图像的文本描述
`n`	integer	否	图像数量，上限 `128`。省略或为 `0` 时按 `1` 处理
`size`	string	否	输出尺寸，如 `1024x1024`、`1024x1536`，或 `1K` / `2K` 这类档位，取决于模型。在 JSON 请求体中请用 `x` 作为分隔符——使用全角 `×` 会被拒绝并返回 `400`
`quality`	string	否	质量等级，如 `standard`、`hd`、`high`、`medium`、`low` 或 `auto`。可接受的值取决于模型
`response_format`	string	否	`url` 或 `b64_json`。会原样转发给上游；模型实际采用哪个值由供应商决定
`style`	string	否	风格提示（例如 `vivid` 或 `natural`）。仅对接受该参数的模型有意义
`user`	string	否	终端用户标识，转发给上游
`watermark`	boolean	否	是否给输出加水印，仅对支持该参数的供应商有效

网关还能识别的字段包括 background、output_format、output_compression、input_fidelity、moderation 和 partial_images，请求中带上时会转发给 OpenAI 兼容上游。网关不认识的 JSON 字段会被丢弃、不会转发，除非该渠道开启了请求体透传。

请求示例

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A calico cat playing a piano on a small stage, soft studio lighting",
    "size": "1024x1024",
    "n": 1
  }'

Python（OpenAI SDK）

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="A calico cat playing a piano on a small stage, soft studio lighting",
    size="1024x1024",
    n=1,
)

for item in result.data:
    print(item.url or item.b64_json[:40])

响应

OpenAI 兼容渠道会原样返回上游响应体。取决于模型，data[] 中会出现 b64_json、url 或两者，读到哪个用哪个。

{
  "created": 1740000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 4160,
    "total_tokens": 4172
  }
}

字段	说明
`created`	生成时间的 Unix 时间戳
`data`	生成的图像数组，每张图一项
`data[].url`	上游返回 URL 时的图像地址
`data[].b64_json`	上游返回 Base64 时的图像字节
`data[].revised_prompt`	模型给出改写 prompt 时返回
`usage`	token 用量，仅在上游返回时存在

url / b64_json 用哪个读哪个，不要假设两者都会出现；解析时把 usage 当作可选字段。

编辑图像

POST /v1/images/edits 根据 prompt 修改已有图像，可选传入遮罩。

multipart 字段

字段	类型	必填	说明
`model`	string	是	来自 `GET /v1/models` 的模型 ID
`image`	file	是	源图像。重复该字段或使用 `image[]` 可传多张
`prompt`	string	是	描述编辑指令
`mask`	file	否	标记待编辑区域的遮罩图。遮罩语义由上游模型定义
`n`	integer	否	结果数量，上限 `128`（默认 `1`）
`size`	string	否	输出尺寸，规则与生成相同
`quality`	string	否	模型接受的质量等级
`watermark`	boolean	否	是否给输出加水印

其他表单字段会原样转发给 OpenAI 兼容上游，因此 response_format、input_fidelity 等参数可以透传。

multipart 请求示例

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F model="gpt-image-2" \
  -F prompt="Replace the background with a sunset beach" \
  -F image=@"cat.png" \
  -F size="1024x1024"

Python（OpenAI SDK）

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

with open("cat.png", "rb") as image:
    result = client.images.edit(
        model="gpt-image-2",
        image=image,
        prompt="Replace the background with a sunset beach",
        size="1024x1024",
    )

print(result.data[0].b64_json[:40])

JSON 编辑

在 OpenAI 兼容渠道上，/v1/images/edits 也接受 JSON 请求体。RouteAPI 会下载或解码每个图像引用，并在上游重建 multipart 请求——当图像已经托管在 URL 上或是 Base64 字符串时，用这种方式。

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Repaint this photo as a watercolor illustration",
    "images": [
      { "image_url": "https://example.com/photo.png" }
    ],
    "size": "1024x1024"
  }'

images 中每一项可以包含 image_url（或 url），值为 http(s) 链接或 data:image/...;base64,... 字符串。mask 使用相同的结构。该路径要求 images 数组，单独的 image 字段不会被读取。其他渠道族可能仍然要求真正的 multipart 请求体，因此在依赖 JSON 编辑前，请先测试目标模型。

同一端点上的其他厂商

端点以及 prompt / n / size 这套请求格式是共用的，但各厂商适配器对它们的映射方式不同。

厂商系列	页面
Google Gemini 图像模型（`gemini--image`）	Nano Banana
火山引擎 Seedream（`seedream-5.0-pro`、`seedream-5.0-lite`）	Seedream

计费

gpt-image 模型按 token 计费：生成的图像计为输出 token，按输出价格收费；prompt 和参考图计为输入 token。尺寸更大、质量更高的输出会消耗更多 token。完整规则见模型定价，具体采用哪种方式以模型详情页为准。

在按尺寸分档的按张计费模型上，价格在选渠道之前根据你请求的 size 对应的像素数确定；n 按张计费，省略或无法识别的 size 会回退到最高单价。

错误与限制

状态码	含义	常见原因
400	请求无效	缺少 `model`、`n` 超过 `128`、模型不支持该 `size`、在 JSON 请求体中用 `×` 作为尺寸分隔符
401	认证失败	API Key 缺失、无效、过期或额度耗尽
403	余额或额度不足	`insufficient_user_quota` 或 `pre_consume_token_quota_failed`；充值或提高 Key 额度
429	触发限流	降低并发
500	转换或内部错误	请求无法为所选渠道转换，或编辑请求没有可用图像
501	`api_not_implemented`	端点存在但不受支持

POST /v1/images/variations 不受支持，会返回 501，错误码为 api_not_implemented，请改用基于 prompt 的编辑。/v1/images/edits 至少需要一张图像，image、image[] 以及 image[0] 形式的表单字段名均可识别。

接下来

Nano Banana — Gemini 图像模型，包括原生 generateContent 调用方式。
Seedream — 火山引擎 Seedream 的尺寸、连续生成与编辑。
模型 — 查找图像模型并确认 image-generation 支持。
模型定价 — 按 token 与按张计费、尺寸档位。
常见错误 — 共用的状态码与错误响应体格式。