API快连 apikl.ai
首页 控制台

GPT Image 2.5 API 生图接入教程：gpt-image-2.5 文生图、图生图与 4K 调用示例

更新于

想在自己的程序、工作流或插件里调用 GPT Image 2.5 生成图片？API 快连提供 OpenAI 官方格式的生图接口，用 OpenAI SDK 或一条 curl 就能出图。这篇讲清楚 gpt-image-2.5 各分组用什么模型名、4K 大图怎么出、图生图（上传参考图改图）怎么写，并给出 curl、Python、Node.js 示例和常见报错的解决办法。

📌
一句话答案：Base URL 填 https://apikl.ai/v1（带 /v1），文生图请求 /v1/images/generations，图生图请求 /v1/images/edits；model 填你这把 Key 所在分组里的模型名（例如 4K 分组填 gpt-image-2.5-flare-4k），size 填 3840x2160 这类尺寸。不想写代码，直接用控制台里的 专业生图页面。
项目内容
Base URLhttps://apikl.ai/v1；默认线路卡住或超时，换直连线路 https://dc.apikl.ai/v1
文生图POST /v1/images/generations（JSON 请求体）
图生图POST /v1/images/edits（multipart 表单，参考图字段 image[]）
鉴权Authorization: Bearer 你的API Key
接口格式与 OpenAI Images API 相同，可直接用 OpenAI 官方 SDK 的 images.generate / images.edit
返回data[].b64_json（base64 图片）或 data[].url（图片链接），示例代码两种都处理

先选分组：gpt-image-2.5 用哪个模型名

API 快连里一把 Key 只能调它所在分组的模型。生图模型都在单独的生图分组里，先在 控制台 创建 Key 时选好分组，再按下表填模型名：

控制台分组请求里填的 model特点
gpt-image-2.5（生图）gpt-image-2.5-flare
gpt-image-2.5-sunburst		flare 出图快，适合快速出图和反复改；sunburst 主打高画质
gpt-image-2.5-4k（生图）gpt-image-2.5-flare-4k
gpt-image-2.5-sunburst-4k		4K 高清版，同样分 flare（快）和 sunburst（高画质）两个模型
gpt-image-2.5（超分）gpt-image-2.5支持 4K 超分生图
gpt-image-2（生图）gpt-image-2
gpt-image-2.5		生图原生模型，可高并发
⚠️
「gpt-image-2.5-4k」是分组名，不是模型名。把它直接填进 model，或者模型名和 Key 的分组对不上，都会返回 404 Model "xxx" is not supported by any configured account in this group。各分组的价格和最新模型以 模型广场 为准。

文生图：一条 curl 出一张 4K 图

把 sk-你的密钥 换成 gpt-image-2.5-4k（生图）分组的 Key，在终端运行：

BASH
curl -sS "https://apikl.ai/v1/images/generations" \ -H "Authorization: Bearer sk-你的密钥" \ -H "Content-Type: application/json" \ --max-time 600 \ -d '{"model":"gpt-image-2.5-flare-4k","prompt":"一只橘猫坐在窗台上，午后阳光，写实摄影","size":"3840x2160"}' \ -o result.json

返回的 JSON 存在 result.json 里，图片在 data[0].b64_json（base64）或 data[0].url（链接）。用下面这段 Python 把它存成图片文件：

Python
# 把 result.json 里的图片保存成文件（b64_json 和 url 两种返回都能处理）import base64, json, urllib.request data = json.load(open("result.json", encoding="utf-8"))if "data" not in data: raise SystemExit(f"没有出图：{data}")for i, item in enumerate(data["data"]): if item.get("b64_json"): img = base64.b64decode(item["b64_json"]) else: req = urllib.request.Request(item["url"], headers={"User-Agent": "MyApp/1.0"}) img = urllib.request.urlopen(req, timeout=120).read() with open(f"out-{i + 1}.png", "wb") as f: f.write(img) print("已保存", f"out-{i + 1}.png")

Windows 用户：PowerShell 里的 curl 是别名，参数写法不同，请改用 curl.exe，或者直接用下面的 Python / Node.js 示例。

常用参数

参数说明
model必填，见上面的分组表
prompt必填，画面描述，中文英文都可以
size图片尺寸，写成 宽x高，例如 1024x1024、2560x1440、3840x2160；规则见下一节
n一次出几张，默认 1。4K 分组建议保持 1，要多张就并行发多个请求；其它分组一次 1–4 张比较稳
quality可选 low / medium / high / auto，不填由模型决定
output_format可选 png / jpeg / webp，不填默认 png

不要传 stream: true：生图分组不支持流式，会返回 Streaming is not supported by this model on the selected channel.。

4K 怎么出：size 写法与尺寸规则

出多大的图由 size 决定。想要 4K，选 gpt-image-2.5-4k（生图）或 gpt-image-2.5（超分）分组，并把 size 写成 4K 尺寸。下面是常用比例对应的尺寸（和 专业生图页面里的预设一致）：

比例1K2K4K
1:1 方图1024x10242048x20482880x2880
16:9 横屏1280x7202560x14403840x2160
9:16 竖屏720x12801440x25602160x3840
3:2 横图1536x10242160x14403456x2304
2:3 竖图1024x15361440x21602304x3456
4:31024x7682048x15363200x2400
21:9 超宽1280x5442560x10883840x1600

自己定尺寸时注意这几条，否则可能被拒或被调整：

  • 宽和高都是 16 的倍数；
  • 最长边不超过 3840；
  • 长宽比不超过 3:1；
  • 总像素在 655,360（约 1024×640）到 8,294,400（3840×2160）之间。

计费按尺寸分档：最长边不超过 1024 算 1K，不超过 2048 算 2K，更大算 4K。各档价格以模型广场为准。

⏱
4K 图一般要 30 秒到 2 分钟，偶尔更久。程序里的超时请设到 5 分钟以上（示例里是 600 秒），不要设 60 秒。默认线路对生图接口有保活，正常不会被掐断；如果网络环境容易断，可以把 Base URL 换成直连线路 https://dc.apikl.ai/v1，效果一样。

图生图：上传参考图改图

图生图请求 /v1/images/edits，用 multipart 表单上传参考图，字段名是 image[]，其余参数和文生图一样：

BASH
curl -sS "https://apikl.ai/v1/images/edits" \ -H "Authorization: Bearer sk-你的密钥" \ --max-time 600 \ -F "model=gpt-image-2.5-sunburst-4k" \ -F "prompt=把这张照片改成水彩画风格，保留人物姿势" \ -F "size=2160x3840" \ -F "image[][email protected]" \ -o result.json

多张参考图（比如「人物 + 衣服」「产品 + 场景」）就重复写 image[]，在提示词里说清楚第几张图是什么：

BASH
curl -sS "https://apikl.ai/v1/images/edits" \ -H "Authorization: Bearer sk-你的密钥" \ --max-time 600 \ -F "model=gpt-image-2.5-flare" \ -F "prompt=让第一张图里的模特穿上第二张图里的外套，白色背景" \ -F "size=1024x1536" \ -F "image[][email protected]" \ -F "image[][email protected]" \ -o result.json
  • 参考图支持 png、jpg、webp。图片越大上传越慢：参考图太大、太多或网络慢时，会因为没传完被断开，返回 400 Failed to read request body。建议每张压到几 MB 以内、一次 1–4 张。
  • 只想改局部，可以再带一个 mask 字段（和原图同尺寸、带透明通道的 png，透明部分就是要重画的区域）；局部重绘的效果因模型而异，以实际出图为准。
  • 图生图同样需要 Key 所在分组有这个模型，4K 分组就填 gpt-image-2.5-flare-4k 或 gpt-image-2.5-sunburst-4k。

用 OpenAI SDK 调用（Python）

先安装 pip install openai，把 Key 放进环境变量 APIKL_KEY（macOS / Linux：export APIKL_KEY=sk-你的密钥；Windows PowerShell：$env:APIKL_KEY="sk-你的密钥"）。下面一段同时演示文生图和图生图：

Python
# pip install openaiimport base64, os, urllib.requestfrom openai import OpenAI client = OpenAI( api_key=os.environ["APIKL_KEY"], base_url="https://apikl.ai/v1", timeout=600, # 4K 图可能要一两分钟，超时留足) def save(result, prefix): for i, item in enumerate(result.data): if item.b64_json: img = base64.b64decode(item.b64_json) else: req = urllib.request.Request(item.url, headers={"User-Agent": "MyApp/1.0"}) img = urllib.request.urlopen(req, timeout=120).read() with open(f"{prefix}-{i + 1}.png", "wb") as f: f.write(img) # 文生图：4K 横图result = client.images.generate( model="gpt-image-2.5-flare-4k", prompt="一只橘猫坐在窗台上，午后阳光，写实摄影", size="3840x2160",)save(result, "cat") # 图生图：传一张或多张参考图with open("photo.png", "rb") as f: result = client.images.edit( model="gpt-image-2.5-sunburst-4k", image=[f], prompt="把这张照片改成水彩画风格，保留人物姿势", size="2160x3840", )save(result, "watercolor")

参考图有多张时，image 传多个打开的文件即可，SDK 会按 image[] 上传。

用 Node.js 调用（不装 SDK）

Node.js 18 及以上自带 fetch，不用装任何包。保存成 image.mjs，运行 APIKL_KEY=sk-你的密钥 node image.mjs（Windows PowerShell 先设环境变量，再运行 node image.mjs）：

Node.js
// Node.js 18 及以上，自带 fetch / FormData / Blob；保存为 image.mjs 运行import { readFileSync, writeFileSync } from "node:fs"; const BASE = "https://apikl.ai/v1";const headers = { Authorization: `Bearer ${process.env.APIKL_KEY}` }; async function save(res, prefix) { const data = await res.json(); if (!res.ok) throw new Error(`没有出图 ${res.status}: ${JSON.stringify(data)}`); for (const [i, item] of data.data.entries()) { const buf = item.b64_json ? Buffer.from(item.b64_json, "base64") : Buffer.from(await (await fetch(item.url)).arrayBuffer()); writeFileSync(`${prefix}-${i + 1}.png`, buf); }} // 文生图const gen = await fetch(`${BASE}/images/generations`, { method: "POST", headers: { ...headers, "Content-Type": "application/json" }, body: JSON.stringify({ model: "gpt-image-2.5-flare-4k", prompt: "一只橘猫坐在窗台上，午后阳光，写实摄影", size: "3840x2160", }), signal: AbortSignal.timeout(600_000),});await save(gen, "cat"); // 图生图（不要手动设置 Content-Type，fetch 会自动带上 multipart 边界）const form = new FormData();form.append("model", "gpt-image-2.5-sunburst-4k");form.append("prompt", "把这张照片改成水彩画风格，保留人物姿势");form.append("size", "2160x3840");form.append("image[]", new Blob([readFileSync("photo.png")], { type: "image/png" }), "photo.png");const edit = await fetch(`${BASE}/images/edits`, { method: "POST", headers, body: form, signal: AbortSignal.timeout(600_000),});await save(edit, "watercolor");

也可以用 OpenAI 官方 Node SDK（npm install openai），把 baseURL 设成 https://apikl.ai/v1，调用 client.images.generate / client.images.edit，参数和 Python 一样。

在工具里用：生图网页、Codex 与其它客户端

  • 不写代码：控制台左侧的专业生图页面（专业生图）填好 Key 就能用，支持文生图、参考图、1K/2K/4K 尺寸选择。用 4K 分组的 Key 时，把配置里的模型名改成 gpt-image-2.5-flare-4k 或 gpt-image-2.5-sunburst-4k；主线路老超时就切「GPT 生图 · 直连线路（超时用）」那一档。
  • Codex：Codex 内置的 Image Gen 只认 OpenAI 官方账号，用第三方 API 会 403。让 Codex 在终端调用上面的接口即可，写法见 Codex 配置教程里的「在 Codex 中通过 API 快连生成图片」。
  • 其它支持「OpenAI 兼容生图」的工具：接口地址填 https://apikl.ai/v1，模型名按分组表填。注意要选「Images / 图片生成接口」，不要选「Chat 对话接口」——这些生图模型不支持 /v1/chat/completions。

常见报错

报错原因怎么办
404 Model "xxx" is not supported by any configured account in this group模型名和 Key 的分组对不上，或把分组名当成了模型名对照上面的分组表改 model，或换对应分组的 Key
400 ... rejected by upstream safety checks
451 ... blocked by the content safety policy		提示词或参考图触发了内容安全审核调整提示词，避开敏感、真人名人、版权角色等内容后重试
400 Failed to read request body参考图太大、太多或网络慢，上传没传完压缩参考图、减少张数；换直连线路 dc.apikl.ai
Streaming is not supported ...传了 stream: true去掉 stream 参数（工具里关闭「流式」）
This model is not supported on the Chat Completions endpoint用对话接口调了生图模型改用 /v1/images/generations
429 Concurrency limit exceeded同时发出的请求太多降低并发，稍等再试
403 insufficient balance余额不足（并发多时会为进行中的请求预留额度）充值，或减少同时进行的请求
503 No available compatible accounts该分组暂时没有可用线路稍后重试；急用可换同模型的其它分组 Key
超时 / 5244K 图耗时长，客户端超时设得太短超时设到 5 分钟以上，或换直连线路

生图失败一般不扣费；使用记录里能看到每张图的扣费明细。更多状态码见 API 报错大全。

常见问题

gpt-image-2.5-4k 和在 gpt-image-2.5 分组里传 4K 尺寸有什么区别？

两个分组的模型不同：gpt-image-2.5-4k（生图）分组是专门出 4K 高清图的版本；gpt-image-2.5（生图）分组同样可以传大尺寸。想要稳定的 4K 大图，用 4K 分组或超分分组。价格不同，以模型广场为准。

一把 Key 能同时调生图和聊天模型吗？

不能。一把 Key 只绑一个分组，生图分组的 Key 只能调生图模型。需要聊天和生图，就在控制台建两把 Key，账户余额是共用的。

返回的图片链接能存多久？

如果返回的是 url，请拿到后尽快下载保存，不要把链接长期当图床用；返回 b64_json 时图片就在响应里，直接解码保存。

支持透明背景吗？

gpt-image 系列在这个接口上不保证透明背景，建议生成纯白或纯色背景，再用抠图工具处理。

→