gpt-image-2 图像生成与编辑
OpenAI 兼容的 gpt-image-2 文生图 + 图像编辑 API:base_url 切换即用,多入口节点就近接入,与现有 QCode API Key 共享计费
需要 API Key? 前往注册 →端点与 Base URL →
本页目录
QCode.cc 提供与 OpenAI Images API 请求 / 响应格式兼容的 gpt-image-2 服务(个别参数行为不同,见 与 OpenAI 官方 API 的差异),覆盖两个端点:
- 文生图
POST /v1/images/generations— JSON 请求,纯文本生成图像 - 图像编辑
POST /v1/images/edits— multipart 上传 1-8 张源图(可选 mask),按 prompt 重绘 / 修改 / 多图融合(2026 年 5 月上线)
gpt-image-2 是 OpenAI 于 2026 年 4 月发布的最新图像模型,文字渲染是目前所有公开图像模型里最强的(中英文字符都可以稳定画在图里)。
ℹ️ OpenAI 于 2026-09-08 发布了 gpt-image-2.5(API 模型名
gpt-image-2.5-flare/gpt-image-2.5-sunburst)。本服务接受gpt-image-2.5、gpt-image-2.5-flare、gpt-image-2.5-sunburst作为兼容模型名,已按新名字配置的客户端可以直接使用。这些名字都可以用,计费相同;xhigh/max画质档按high处理,4K / 任意分辨率等 2.5 专属能力暂不支持。
QCode.cc 接入特性:
- OpenAI SDK 直接可用:替换
base_url即可,请求 / 响应格式与 OpenAI 一致(含 multipart edits 接口);个别参数行为不同,见文末差异表 - 多区域接入:全球智能路由(api)/ 亚洲(韩国 / 台湾 / 香港)/ 北美与欧洲(洛杉矶),按你所在网络环境就近选择
- API Key 统一:复用你已有的 QCode.cc
cr_开头密钥,与 Claude Code / Codex 同一份配额账户 - 后台用量统一:图像调用与对话调用合并显示在客户后台 Dashboard,并提供独立自助查询页
- 两端点共享配额:
generations和edits共用每个 API Key 每日 100 张上限与 2 并发上限
典型场景:海报生成、配图、产品图、UI mockup、社交媒体素材、图像编辑(局部修改 / 多图融合 / 抠图换背景 / 高保真重绘)。
快速开始¶
文生图(generations)¶
3 行 Python 完成第一张图:
from openai import OpenAI
import base64
client = OpenAI(
base_url="https://api.qcode.cc/qcode-img/v1",
api_key="cr_YOUR_QCODE_API_KEY",
timeout=180.0, # 单图通常 20-80s,偶尔超过 100s;至少设 180s
)
result = client.images.generate(
model="gpt-image-2",
prompt="A cyberpunk Tokyo street at night, neon reflecting in rain puddles",
size="1024x1024",
quality="low",
n=1,
)
with open("output.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
图像编辑(edits)¶
上传现有图片 + prompt,可选 mask 做局部重绘:
from openai import OpenAI
import base64
client = OpenAI(
base_url="https://api.qcode.cc/qcode-img/v1",
api_key="cr_YOUR_QCODE_API_KEY",
timeout=180.0,
)
result = client.images.edit(
model="gpt-image-2",
image=open("cat.png", "rb"),
mask=open("mask.png", "rb"), # 可选:PNG alpha,透明区域是要重绘的部分
prompt="put a tiny crown on the cat",
size="1024x1024",
quality="high",
)
with open("edited.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
⚠️ 必须显式设置 timeout ≥ 180s:OpenAI SDK 默认超时较短,gpt-image-2 推理时间显著长于传统文生图(详见下方 生成耗时)。
接入入口¶
gpt-image-2 服务(generations + edits 通用)在 QCode.cc 的所有接入域上都可用,只需把 {base} 拼成 {base}/qcode-img/v1:
| 用户位置 | 推荐 base_url | 协议 | 备注 |
|---|---|---|---|
| 中国大陆 | https://api.qcode.cc/qcode-img/v1 |
HTTPS | 默认推荐 |
| 香港 / 东南亚 | https://asia.qcode.cc/qcode-img/v1 |
HTTPS | 亚洲节点(韩国 / 台湾 / 香港就近) |
| 北美 / 欧洲 | https://us.qcode.cc/qcode-img/v1 |
HTTPS | 洛杉矶节点 |
所有入口路由到同一服务与计费体系,用量与额度统一。各入口对单次请求时长没有 100 秒限制,服务端单次请求最长等待 180 秒。
qcode-img是图像生成与编辑专属路径前缀,与 Anthropic 协议的/api、OpenAI 协议的/openai/v1平行。
API 规范¶
通用请求头¶
| Header | 必需 | 值 |
|---|---|---|
Authorization |
✓ | Bearer cr_xxxxxxxxxxxxxxxx(你的 QCode.cc API Key) |
Content-Type |
✓ | application/json(generations)multipart/form-data(edits) |
生成接口 /v1/images/generations¶
端点:POST {base_url}/images/generations
Content-Type:application/json
请求体:
{
"model": "gpt-image-2",
"prompt": "A small ceramic vase with sunflower, photorealistic",
"size": "1024x1024",
"quality": "low",
"n": 1
}
字段:
| 字段 | 类型 | 必需 | 默认 | 取值 |
|---|---|---|---|---|
model |
string | ✗ | gpt-image-2 |
gpt-image-2(也接受 gpt-image-2-low / -medium / -high,等价于设置 quality;以及兼容名 gpt-image-2.5 / gpt-image-2.5-flare / gpt-image-2.5-sunburst,都可以用、计费相同);其他模型名返回 400 unsupported_model |
prompt |
string | ✓ | — | 图像描述,支持中英多语言 |
size |
string | ✗ | 1024x1024 |
auto / 1024x1024 / 1024x1536 / 1536x1024 / 2048x2048;非法值返回 422。输出尺寸通常与请求的 size 一致,个别情况下返回的尺寸会不同(例如 1254×1254),请以返回图片的实际尺寸为准 |
quality |
string | ✗ | medium |
low / medium / high(xhigh / max 按 high 处理);不影响价格(见 计费规则) |
n |
integer | ✗ | 1 | 单次生成数(1 – 4);> 4 返回 400(不会静默截断) |
background |
string | ✗ | auto |
auto / opaque;transparent 返回 400(模型无法生成透明通道) |
response_format |
string | ✗ | b64_json |
仅 b64_json;传 url 返回 400 |
output_compression |
integer | ✗ | — | 0 – 100,对 JPEG / WebP 生效;越界返回 400 |
stream / partial_images |
— | ✗ | — | 暂不支持;传入返回 400 |
图像编辑接口 /v1/images/edits¶
端点:POST {base_url}/images/edits
Content-Type:multipart/form-data(上传文件用 form-data,不能用 JSON)
字段:
| 字段 | 类型 | 必需 | 默认 | 取值 / 说明 |
|---|---|---|---|---|
model |
string | ✗ | gpt-image-2 |
可省略;编辑接口始终使用 gpt-image-2 |
image |
file(× N) | ✓ | — | 源图(PNG / JPEG / WebP);支持 1 – 8 张多图融合(多张时重复同名字段:-F image=@a.png -F image=@b.png) |
mask |
file | ✗ | — | PNG alpha 蒙版,透明区域是要重绘的部分;mask 像素分辨率需与 image 一致(系统会自动缩放);仅对单图有意义 |
prompt |
string | ✓ | — | 编辑指令(中英多语言) |
size |
string | ✗ | auto |
auto / 1024x1024 / 1024x1536 / 1536x1024 / 2048x2048。输出尺寸通常与请求的 size 一致,个别情况下返回的尺寸会不同(例如 1254×1254),请以返回图片的实际尺寸为准;非法值返回 422 |
quality |
string | ✗ | auto |
auto / low / medium / high(xhigh / max 按 high 处理);不影响价格 |
n |
integer | ✗ | 1 | 单次生成数(1 – 4);> 4 返回 400(不会静默截断) |
background |
string | ✗ | auto |
auto / opaque。gpt-image-2 不支持 transparent(模型无法生成 alpha 通道,传入返回 400) |
output_format |
string | ✗ | png |
png / jpeg / webp |
output_compression |
integer | ✗ | — | 0 – 100,对 JPEG / WebP 生效(PNG 忽略);越界返回 400 |
input_fidelity |
string | ✗ | — | 无需传入:模型恒以高保真处理输入图;传 low / high 会被忽略,其他值返回 400 |
response_format |
string | ✗ | b64_json |
仅接受 b64_json(传 url 返回 400) |
user |
string | ✗ | — | 终端用户 ID 透传(用于滥用检测) |
上传体积上限:单文件 ≤ 25 MB;多文件合计 ≤ 50 MB(超过返 413 image_too_large)。
响应(两端点格式相同)¶
{
"created": 1777135432,
"data": [
{
"b64_json": "iVBORw0KGgo...(base64 PNG/JPEG/WebP, 1-3 MB)",
"revised_prompt": "A small ceramic vase with sunflower..."
}
]
}
b64_json:图片的 base64 编码数据,前端可直接<img src="data:image/<format>;base64,...">渲染revised_prompt:模型对原始 prompt 的优化版本(可选展示给用户参考)
错误响应¶
错误响应符合 OpenAI 标准 schema:
{
"error": {
"type": "rate_limit_error",
"code": "image_daily_limit",
"message": "Daily image generation count limit reached..."
}
}
| HTTP | code | 含义 | 计费 |
|---|---|---|---|
| 400 | invalid_json / missing_prompt |
请求体不是合法 JSON / 缺少 prompt |
否 |
| 400 | unsupported_model |
模型名不支持(支持 gpt-image-2 及其兼容名 gpt-image-2.5 / -flare / -sunburst;gpt-image-1、dall-e-3 等返回此错误) |
否 |
| 400 | stream_not_supported |
传了 stream=true 或 partial_images |
否 |
| 400 | unsupported_background / unsupported_response_format / unsupported_n / unsupported_output_compression |
参数取值不支持(见各接口参数表) | 否 |
| 400 | invalid_multipart / invalid_content_type |
编辑接口的表单格式错误(须为 multipart/form-data) |
否 |
| 400 | content_policy_violation 等 |
内容审核拒绝了本次请求,请修改 prompt 或图片 | 否 |
| 401 | invalid_api_key / key_disabled / key_expired |
API Key 无效 / 已禁用 / 已过期 | 否 |
| 413 | image_too_large |
上传单文件 > 25 MB,或多文件合计 > 50 MB | 否 |
| 422 | unsupported_size |
size 取值不支持(合法值见各接口参数表) |
否 |
| 429 | crs_daily_exhausted / crs_total_exhausted |
账户当日 / 累计预算已用尽 | 否 |
| 429 | image_daily_limit |
每个 API Key 每日 100 张上限(generations + edits 共用,可申请提升) | 否 |
| 429 | concurrency_exhausted |
每个 API Key 并发上限 2(可申请提升) | 否 |
| 501 | endpoint_not_implemented |
编辑接口临时维护关闭 | 否 |
| 503 | image_provider_unavailable |
图像服务暂时不可用;响应带 Retry-After,按 超时与重试 处理 |
否 |
| 503 | service_overloaded / billing_backend_unavailable |
服务繁忙 / 计费后端暂不可用,请稍后重试 | 否 |
| 504 | upstream_timeout |
编辑请求超过 180 秒仍未完成 | 否 |
代码示例¶
Python(OpenAI SDK,推荐)¶
文生图:
from openai import OpenAI
import base64
client = OpenAI(
base_url="https://api.qcode.cc/qcode-img/v1",
api_key="cr_YOUR_QCODE_API_KEY",
timeout=180.0,
)
result = client.images.generate(
model="gpt-image-2",
prompt="A cyberpunk Tokyo street at night, neon reflecting in rain puddles",
size="1024x1024",
quality="low",
n=1,
)
img_bytes = base64.b64decode(result.data[0].b64_json)
with open("output.png", "wb") as f:
f.write(img_bytes)
print("已保存 output.png")
图像编辑(单图 + mask 局部重绘):
from openai import OpenAI
import base64
client = OpenAI(
base_url="https://api.qcode.cc/qcode-img/v1",
api_key="cr_YOUR_QCODE_API_KEY",
timeout=180.0,
)
result = client.images.edit(
model="gpt-image-2",
image=open("cat.png", "rb"),
mask=open("mask.png", "rb"),
prompt="put a tiny crown on the cat",
size="1024x1024",
quality="high",
extra_body={"output_format": "png"},
)
img = base64.b64decode(result.data[0].b64_json)
with open("edited.png", "wb") as f:
f.write(img)
图像编辑(多图融合,2 – 8 张):
result = client.images.edit(
model="gpt-image-2",
image=[
open("scene.png", "rb"), # 第一张:场景背景
open("product.png", "rb"), # 第二张:要植入的产品
],
prompt="Place the product naturally into the scene, match the lighting and shadows.",
size="1536x1024",
quality="high",
)
curl¶
文生图:
curl https://api.qcode.cc/qcode-img/v1/images/generations \
-H "Authorization: Bearer cr_YOUR_QCODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A cyberpunk Tokyo street at night",
"size": "1024x1024",
"quality": "low",
"n": 1
}' \
| jq -r ".data[0].b64_json" | base64 -d > output.png
图像编辑:
curl https://api.qcode.cc/qcode-img/v1/images/edits \
-H "Authorization: Bearer cr_YOUR_QCODE_API_KEY" \
-F "model=gpt-image-2" \
-F "image=@cat.png" \
-F "mask=@mask.png" \
-F "prompt=put a tiny crown on the cat" \
-F "size=1024x1024" \
-F "quality=high" \
-F "output_format=png" \
| jq -r ".data[0].b64_json" | base64 -d > edited.png
多图融合(重复 -F image=@ 即可):
curl https://api.qcode.cc/qcode-img/v1/images/edits \
-H "Authorization: Bearer cr_YOUR_QCODE_API_KEY" \
-F "model=gpt-image-2" \
-F "image=@scene.png" \
-F "image=@product.png" \
-F "prompt=Place the product naturally into the scene" \
-F "size=1536x1024" \
-F "quality=high"
JavaScript / Node.js / 浏览器¶
文生图:
const r = await fetch("https://api.qcode.cc/qcode-img/v1/images/generations", {
method: "POST",
headers: {
"Authorization": "Bearer cr_YOUR_QCODE_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gpt-image-2",
prompt: "A cyberpunk Tokyo street at night",
size: "1024x1024",
quality: "low",
n: 1,
}),
});
const json = await r.json();
const dataUrl = "data:image/png;base64," + json.data[0].b64_json;
document.querySelector("img").src = dataUrl;
图像编辑(浏览器 FormData):
const fd = new FormData();
fd.append("model", "gpt-image-2");
fd.append("image", imageFile); // File 对象,来自 <input type="file">
fd.append("mask", maskFile); // 可选
fd.append("prompt", "put a tiny crown on the cat");
fd.append("size", "1024x1024");
fd.append("quality", "high");
fd.append("output_format", "png");
const r = await fetch("https://api.qcode.cc/qcode-img/v1/images/edits", {
method: "POST",
headers: { "Authorization": "Bearer cr_YOUR_QCODE_API_KEY" },
// 不要手动设 Content-Type — FormData 会自动加上含 boundary 的 multipart/form-data
body: fd,
});
const json = await r.json();
const dataUrl = "data:image/png;base64," + json.data[0].b64_json;
document.querySelector("img").src = dataUrl;
限额规则¶
默认限额¶
| 维度 | 默认值 | 说明 |
|---|---|---|
| 每日图片数 | 100 张 / 天 / Key | 北京时间 0 点重置;generations + edits 共用此上限 |
| 并发数 | 2 同时进行中 | 超出返 429 concurrency_exhausted;generations + edits 共用 |
| 上传体积(仅 edits) | 单文件 25 MB / 多文件合计 50 MB | 超出返 413 image_too_large |
| 账户预算 | 共用 QCode.cc 账户的 dailyCostLimit / totalCostLimit |
超出返 429 crs_daily_exhausted |
默认限额对绝大多数用户充足。如需提升请联系客服。
用量查询¶
- 客户后台 Dashboard:与 chat 调用统一展示(最近使用时间、当日费用、累计费用、模型分布)
- 自助查询页:https://api.qcode.cc/qcode-img/usage — 输入 API Key 查近 30 天用量、详细调用列表、ECharts 趋势图(API Key 仅在浏览器本地存储,不上传)
计费规则¶
计费方式¶
generations 与 edits 相同,按输出图片张数计费:
| 计费项 | 单价 |
|---|---|
| 每张输出图片 | $0.30 |
- 每张输出图片 $0.30:一次生成
n张即n × $0.30 size/quality/ 输入图片张数 /mask/ prompt 长度都不影响价格gpt-image-2、gpt-image-2-low/-medium/-high,以及兼容名gpt-image-2.5/-flare/-sunburst,价格完全相同- 自 2026-10-07 起每张 $0.30(2026-10-06 起曾为每张 $0.15,此前按 token 计费)
失败不计费¶
任何失败请求都不计费:4xx(含内容审核拒绝)/ 5xx、超时、客户端断开(连接关闭)均不扣费。
货币¶
费用以 USD 计算,账户结算遵循 QCode.cc 主账户的货币策略(人民币 / 美元)。
生成耗时与超时设置¶
gpt-image-2 是基于推理的模型,生成时间明显长于传统文生图模型。单张通常 20–80 秒,偶尔超过 100 秒,个别接近 180 秒。
实践建议:
- OpenAI Python SDK 默认超时较短,必须显式设置
timeout=180.0或更高 - 浏览器
fetch没有默认超时;若用AbortController设了超时,至少给 180 s - 如果请求经过你自己的反向代理 / 网关,请把它的读超时调到 ≥ 180 s
超时与重试¶
- 503
image_provider_unavailable:图像服务暂时不可用,不计费。请按响应头Retry-After(秒)等待后重试,建议指数退避(30 s → 60 s → 120 s),最多 3 次;持续失败请联系客服 - 504
upstream_timeout/ 客户端超时:单次生成超过 180 秒。可直接重试;多次超时请简化 prompt 或减少输入图数量 - 429
crs_daily_exhausted/crs_total_exhausted:账户额度用完,处理方式与对话接口相同:个人套餐等北京时间 0 点重置或买加油包,按量包续买,详见 错误码参考 - 429
image_daily_limit/concurrency_exhausted:按响应头Retry-After等待;持续触发请联系客服 - 失败请求不计费,重试不会产生重复扣费
Prompt 编写要点¶
文生图(generations)¶
- 支持中英多语言:可直接写中文 prompt,也可英文,混合也可
- 细节越具体越好:环境、构图、光线、风格、镜头距离 / 焦段 / 视角等
- 避免品牌名 / 知名人物:模型可能拒绝或返回模糊结果(OpenAI 内容策略限制)
- 文字渲染:
gpt-image-2文字渲染能力极强,可在图中嵌入英文 / 中文标题、短句、海报文字(写在 prompt 中即可,无需特殊语法) - 内容审核:违反内容政策的 prompt 会返回 400(如
content_policy_violation),不计费
示例:
A vintage poster in Bauhaus style, bold black text "MORNING COFFEE" centered,
warm orange and cream color palette, geometric shapes, slightly textured paper background
图像编辑(edits)¶
- mask 是"哪里要改",不是"改成什么":透明区域 = 要重绘的部分,不透明区域保留原图。prompt 描述目标。mask 像素分辨率需与
image一致(系统会自动缩放) - 多图融合时 prompt 要明确每张图的角色:例如 "First image is the scene, second image is the product to be placed in" — gpt-image-2 会按顺序理解多张输入
- 无需传
input_fidelity:gpt-image-2 恒以高保真处理输入图,自动保留原图人物面孔、品牌 logo、文字、商品细节(传low/high会被忽略,其他值返回 400) - 不给 mask 时:整张图按 prompt 重绘(保留原图的语义结构,但所有区域都可能被改)
示例:
# 局部修复:把猫加上小皇冠,其他保持原样
prompt = "Put a tiny golden crown on the cat's head. Keep everything else unchanged."
mask = (alpha PNG with only the head area transparent)
与 OpenAI 官方 API 的差异¶
| 维度 | OpenAI 官方 | QCode.cc |
|---|---|---|
| SDK 兼容性 | — | ✅ 请求 / 响应格式兼容,替换 base_url 即可;以下各行为差异点 |
| 计费 | 按 token | 每张输出图片 $0.30,n 张即 n × $0.30 |
/v1/images/generations(文生图) |
✅ | ✅ |
/v1/images/edits(图像编辑) |
✅ | ✅ 支持 1 – 8 张多图融合、mask 局部重绘 |
size |
— | 输出尺寸通常与 size 一致,个别情况不同,以返回图片实际尺寸为准 |
quality |
— | 不影响价格 |
background=transparent |
— | ❌ 返回 400 |
response_format=url |
— | ❌ 仅 b64_json |
stream + partial_images(增量返回) |
✅ | ⏳ 暂不支持,传入返回 400 |
/v1/images/variations(纯变体生成) |
✅(DALL·E 端点) | ⏳ 暂不支持(可用 edits 配合描述性 prompt 近似实现) |
gpt-image-2.5(flare / sunburst) |
✅(2026-09-08 发布) | ✅ 接受兼容模型名,这些名字都可以用、计费相同;xhigh / max 按 high 处理,2.5 专属能力(4K 等)暂不支持 |
在线 Playground¶
https://api.qcode.cc/qcode-img/ — 浏览器即可试用:
- 文生图 + 图像编辑 两个模式都可视化操作(上传图、选 quality、调整 background / output_format 等)
- 输入 API Key + Prompt 立即生成
- 中英双语切换
- 默认
low质量 - 含完整 API 调用文档(curl / Python / JavaScript 三个 tab + 参数表 + 错误码表)
- 一键下载生成的 PNG / JPEG / WebP
常见问题¶
Q:返回 503 image_provider_unavailable 怎么办?
A:图像服务暂时不可用,失败请求不计费。请按响应头 Retry-After 等待后重试(建议 30 秒起指数退避,最多 3 次)。持续失败请联系客服。
Q:支持 gpt-image-2.5(flare / sunburst)吗?
A:可以直接使用 gpt-image-2.5、gpt-image-2.5-flare、gpt-image-2.5-sunburst 这些模型名,这些名字都可以用、计费相同;xhigh / max 画质档按 high 处理,4K 等 2.5 专属能力暂不支持。
Q:为什么输出图片的尺寸和我传的 size 不一致?
A:输出尺寸通常与请求的 size 一致,个别情况下返回的尺寸会不同(例如 1254×1254),请以返回图片的实际尺寸为准。需要固定尺寸时请在本地裁剪或缩放。
Q:quality 会影响价格吗?
A:quality 不影响价格——无论 low 还是 high,都是每张输出图片 $0.30。
Q:失败的请求会扣费吗? A:不会。4xx / 5xx、超时、内容审核拒绝和客户端断开都不计费。
相关文档¶
- 接入点与 API 格式 — QCode.cc 全部接入域、协议路径、curl 自测方法
- 计费说明 — 套餐、配额、费用规则
开始使用 QCode
一把 API Key 同时用于 Claude Code、Codex 等工具;按 token 计费,各模型单价见 qcode.cc/models