1route.dev1route.dev
1 Route
协议文档

OpenAI Images

使用 OpenAI SDK 或 HTTP 生成、编辑 🎨 GPT Image 图片。

让 AI 来读文档 🥺👉
协议导航

从这里切换协议

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

Key 只会保存在当前浏览器，并随你发送的真实请求使用。

没有 Key？去创建创建时选择 🎨 GPT Image 分组。
POST
$pip install openai
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))
响应
尚未发送请求

生成图片

POSThttps://api.1route.dev/v1/images/generations
默认 https://api.1route.dev频繁超时可改用 https://image-api.1route.dev

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

没有 Key？去创建创建时选择 🎨 GPT Image 分组。
{
  "model": "gpt-image-2.5-flare",
  "prompt": "白色陶瓷咖啡杯的产品照片，柔和侧光，浅灰背景",
  "size": "1024x1024",
  "quality": "high",
  "n": 1,
  "output_format": "png",
  "response_format": "b64_json"
}

model 不加 openai/ 前缀。当前提供 gpt-image-2、gpt-image-2.5-flare、gpt-image-2.5-sunburst；gpt-image-2.5 路由到 Flare。

尺寸与质量

字段用法
prompt图片描述；编辑时说明保留的内容和具体修改
size默认 auto；支持 1K、2K、4K 或 宽x高
quality默认 auto；Image 2 支持 low、medium、high，2.5 系列另支持 xhigh、max
n生成张数，默认 1；与 Studio 统一协议的一任务一图片不同
output_format图片编码：png（默认）、jpeg、webp
output_compressionJPEG / WebP 压缩质量，0 到 100；PNG 不使用
response_format数据交付方式：b64_json 或 url
backgroundauto、opaque、transparent；透明背景使用 PNG 或 WebP
moderation内容审核档位：auto（默认）或 low
user可选的终端用户标识

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

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

Python SDK

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

没有 Key？去创建创建时选择 🎨 GPT Image 分组。
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))

使用参考图

POSThttps://api.1route.dev/v1/images/edits
默认 https://api.1route.dev频繁超时可改用 https://image-api.1route.dev

同一接口接受文件上传或 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。

返回数据

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 交付能力。图片保留 72 小时，过期返回 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。已存结果保留 72 小时。

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
HTTP 状态处理方式
400检查 param 和 code，修改字段、图片或提示词后再提交
401检查 Key 及其所属分组
409幂等值与原请求冲突
410已存图片或结果过期
413减小请求体或参考图
429查看余额、额度与并发限制
500 / 502 / 504查看错误详情；频繁超时可使用备用地址

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

🧩 Studio 统一协议

一套异步图片接口，统一调用 🎨 GPT Image 和 🍌 Nano Banana。

🍌 Gemini Native

使用 Google Gen AI SDK 或 HTTP 调用 🍌 Nano Banana，处理多模态输入和图片返回。