OpenAI Images

协议导航

从这里切换协议

让 AI 帮我选

01StudioStudio 统一协议推荐六个模型统一调用，查询进度、获取结果和取消任务。02OpenAIOpenAI Images当前已有 OpenAI Images 工作流或 SDK。03GoogleGemini NativeGoogle SDK、多轮编辑和原生多模态结构。

import jsonfrom openai import OpenAIapi_key = "YOUR_API_KEY"api_base = "https://api.1route.dev"payload = {    "model": "gpt-image-2.5-flare",    "prompt": "Editorial portrait of a woman in profile beside a wind-bent tree, late afternoon light, deep cobalt coat, pale concrete wall, subtle film grain, restrained color palette, clean composition, vertical 4:5.",    "size": "auto",    "n": 1,    "output_format": "png",    "response_format": "b64_json"}client = OpenAI(api_key=api_key, base_url=f"{api_base}/v1", max_retries=0, timeout=1500)response = client.images.generate(**payload)result = response.model_dump(mode="json", exclude_none=True)print(json.dumps(result, ensure_ascii=False, indent=2))

生成图片

使用 Authorization: Bearer YOUR_API_KEY 认证，发送 JSON。非流式请求会一直等待到图片生成完成，然后返回 data[]。

{
  "model": "gpt-image-2.5-flare",
  "prompt": "白色陶瓷咖啡杯的产品照片，柔和侧光，浅灰背景",
  "size": "1024x1024",
  "quality": "high",
  "n": 1,
  "output_format": "png",
  "response_format": "b64_json"
}

model 不加 openai/ 前缀。GPT Image 使用 gpt-image-2、2.5 和 2.6 系列基础模型名；2.5、2.6 分别提供 Flare 与 Sunburst，裸名固定指向对应 Flare。实际可用模型与尺寸以所选渠道的图片目录为准。

请使用基础模型名，通过 size 选择尺寸，无需添加尺寸后缀。目录的支持档位与自动尺寸标记决定可选参数；例如 Adobe 渠道仅开放 1K 与自动尺寸。

尺寸与质量

常用像素尺寸包括 1024x1024、1536x1024、1024x1536、2048x2048、3840x2160。具体尺寸按像素范围映射到 1K / 2K / 4K 路由档位；size 决定尺寸，quality 决定质量，两者不是同一个开关。

🎨 GPT Image 自定义尺寸的原生范围：边长为 16 的倍数，最长边不超过 3840，长宽比不超过 3:1，总像素为 655,360 到 8,294,400。使用符合范围的尺寸，便于准确控制输出。

GPT Image 2.6 官方能力

gpt-image-2.6-flare 和 gpt-image-2.6-sunburst 使用以下请求参数；本站裸名 gpt-image-2.6 固定指向 Flare。可用性、支持尺寸与价格以所选渠道的当前图片目录为准。

2.6 的生成与编辑可使用 complexity，取值为 low、medium、high；省略时由上游默认使用 high。它控制画面复杂度，与 quality 分开。调用支持该能力的模型时，可在工作台的附加 JSON 字段中传入。

2.6 仅文生图还支持 output_format: "svg"（矢量）和 "gif"（动画）。SVG 必须使用 n: 1。两种格式均不支持流式、partial_images、output_compression 或 prompt_rewriter，也不能作为编辑的输出格式。只有 GIF 使用 frame_count（2–64，默认 9）与 frame_duration_ms（20–2000，默认 200）；帧时长由上游按 10 ms 取整。

以下有条件适用的示例与浏览器、代码生成器共用请求构造器。工作台对当前供应模型继续提供 raster 格式选项。

{  "complexity": "medium",  "model": "gpt-image-2.6-flare",  "prompt": "A simple flat vector icon of a white ceramic cup",  "size": "auto",  "n": 1,  "output_format": "svg",  "response_format": "b64_json"}

{  "complexity": "medium",  "frame_count": 9,  "frame_duration_ms": 200,  "model": "gpt-image-2.6-flare",  "prompt": "A seamless looping animation of steam rising from a ceramic cup",  "size": "auto",  "n": 1,  "output_format": "gif",  "response_format": "b64_json"}

Base64 直接解码保存为 output.svg 或 output.gif，或下载原始 URL。SVG 的 MIME 为 image/svg+xml，GIF 为 image/gif；保留原始字节，才能保留矢量内容或动画。实际输出信息读取响应，不按请求帧数推算 usage 或费用。

模型能力见 OpenAI 官方图片生成指南。

Python SDK

安装 openai。SDK 的 base_url 需要加 /v1；备用地址同样加 /v1。

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.1route.dev/v1",
    max_retries=0,
    timeout=1500,
)
result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="白色陶瓷咖啡杯的产品照片，柔和侧光，浅灰背景",
    size="1024x1024",
    response_format="b64_json",
)
Path("output.png").write_bytes(base64.b64decode(result.data[0].b64_json))

使用参考图

同一接口接受文件上传或 JSON 图片地址。参考图按提交顺序处理，可在提示词中用“第一张图”“第二张图”区分各自用途。

上传本地文件

使用 multipart/form-data，多张图片重复 image[] 字段；单张也可使用 image。其他参数作为表单字段提交。让 HTTP 库设置包含 boundary 的 Content-Type。

from pathlib import Path

result = client.images.edit(
    model="gpt-image-2.5-sunburst",
    prompt="保留第一张图的人物，让她穿上第二张图中的外套",
    image=[
        ("person.png", Path("person.png").read_bytes(), "image/png"),
        ("coat.png", Path("coat.png").read_bytes(), "image/png"),
    ],
    size="1024x1536",
    response_format="b64_json",
)
Path("edited.png").write_bytes(base64.b64decode(result.data[0].b64_json))

最多 16 张参考图，支持 PNG、JPEG、WebP，每张不超过 50 MiB。整个请求体上限为 512 MiB；图片与 Base64 编码后的请求大小要分别计算。

图片 URL 与 Data URL

使用 application/json，图片放在 images[].image_url。公网 URL 和完整 Data URL 可以混用：

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "保留杯子的标识，把背景换成第二张图中的桌面",
  "images": [
    { "image_url": "https://your-image-host.example/cup.png" },
    { "image_url": "data:image/png;base64,<图片数据>" }
  ],
  "size": "1024x1024",
  "response_format": "url"
}

JSON 编辑通过 SDK 的通用请求方法发送，或选择工作台中的 httpx、requests、fetch。不要把 JSON images 传成 SDK 的文件参数 image。

from openai.types import ImagesResponse

result = client.post("/images/edits", body=payload, cast_to=ImagesResponse)
print(result.data[0].url)

图片地址由服务端下载。此接口不接受 file_id。

遮罩与局部修改

遮罩对应第一张参考图。PNG 透明区域表示要编辑的部分，尺寸必须与第一张图一致，文件不超过 4 MiB。文件上传使用 mask 文件字段；JSON 使用：

{
  "mask": { "image_url": "data:image/png;base64,<遮罩数据>" }
}

同时在 prompt 里描述修改内容。gpt-image-2 的参考图始终按高保真处理，不需要发送 input_fidelity。

markup 标注层

支持该能力的 GPT Image 2.5 与 2.6 模型可在编辑时使用一个 markup 标注层。它是覆盖第一张参考图的透明 PNG，与遮罩不同。按图片方向信息解释后，标注图宽高必须与首张参考图一致，至少一个像素不完全不透明，文件不超过 50 MiB；首张参考图与标注图均最多 16,777,216 像素。不能与 mask 或 prompt_rewriter 同时使用。

multipart 使用一个名为 markup 的 PNG 文件字段。JSON 编辑使用 markup.image_url，支持公网 URL 或完整 PNG Data URL：

{
  "model": "gpt-image-2.5-flare",
  "prompt": "按标注层修改对应内容，保留图片其余部分",
  "images": [{ "image_url": "https://your-image-host.example/product.png" }],
  "markup": { "image_url": "data:image/png;base64,<透明 PNG 标注图数据>" }
}

在工作台正常提供参考图，将 markup 放入附加 JSON 字段；上传的参考图会作为 Data URL 放进这次 JSON 请求。本站不支持 markup.file_id，返回 unsupported_file_id 且 param=markup.file_id，请改用 image_url。标注层不能代替必需的参考图。

返回数据

Base64

{
  "created": 1788940800,
  "data": [{ "b64_json": "<完整图片数据>" }],
  "size": "1024x1024",
  "quality": "high",
  "output_format": "png",
  "usage": {
    "input_tokens": 20,
    "output_tokens": 1000,
    "total_tokens": 1020,
    "input_tokens_details": { "text_tokens": 20, "image_tokens": 0 }
  }
}

created 是 Unix 秒时间戳。逐项读取 data[]，将 b64_json 解码为字节保存；它不含 data:image/...;base64, 前缀。工作台只折叠显示，复制和下载保留完整数据。

size、quality、background、output_format 是上游返回的生成信息，按实际响应读取。usage 是 token 用量，不是金额；input_tokens_details 可区分文字与参考图输入。部分响应不包含这些可选字段。若出现 revised_prompt，它表示实际使用的改写提示词。

图片 URL

请求设为 response_format: "url" 后，读取 data[].url：

{
  "created": 1788940800,
  "data": [{ "url": "https://api.1route.dev/v1/images/files/media_example" }]
}

这是本站提供的 URL 交付能力。图片保留 24 小时，过期返回 410 result_expired。下载后可永久存到自己的存储。媒体地址支持 GET / HEAD。output_format 和 response_format 相互独立，例如 JPEG 图片也可以通过 Base64 返回。

流式返回

生成与编辑都可发送 stream: true。partial_images 为 0 到 3，控制中间预览图的数量；生成较快时，实际预览图可能少于请求数量。

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="一张有手写标题的咖啡海报",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type == "image_generation.completed":
        Path("output.png").write_bytes(base64.b64decode(event.b64_json))

HTTP 响应为 SSE。生成事件包括 image_generation.partial_image 与 image_generation.completed；编辑对应 image_edit.partial_image 与 image_edit.completed。预览事件的 partial_image_index 是预览序号，最终图片以 completed 事件为准。连接中的 error 事件表示错误，不能只检查最初的 HTTP 200。

流式请求不返回 Studio jobId，也没有 Studio 的查询与取消接口。需要持久化任务状态时使用 Studio 统一协议。

幂等与错误

非流式请求支持 Idempotency-Key：同一 Key、同一幂等值和相同请求等待或复用原结果；客户端断开后再次使用相同幂等值仍会等待或复用原任务，不会重复生图；不同请求复用幂等值返回 409。流式请求携带此头返回 400。已存结果保留 24 小时。

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

编辑常见错误码包括 edit_image_required、edit_too_many_images、edit_image_too_large、edit_mask_dimensions_mismatch。内容限制错误可能带 moderation_blocked；应修改提示词或输入，而不是重复发送同一请求。