跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt

Use this file to discover all available pages before exploring further.

​
gpt-image-2 API 接入文档

APIYI · 2026-04 官方参考：developers.openai.com/api/docs/guides/image-generation
gpt-image-2 是 OpenAI 最新旗舰图像生成模型，是 gpt-image-1.5 的升级版。核心升级：任意分辨率（含 2K/4K）、更低价格、参考图自动高保真。 APIYI 网关完整兼容 OpenAI Images API 契约，OpenAI 官方 SDK 把 base_url 指过来即可直连，零代码改动。

​
一、模型概览

维度参数
模型名gpt-image-2
速度~120 秒
输出分辨率任意合法尺寸（1K/2K/4K 均支持）
画质档位auto / low / medium / high
输出格式png（默认）/ jpeg / webp
中文提示词✅ 支持
单次出图数量1 张（n=1）
支持能力文生图、参考图编辑、多图融合、mask 局部重绘
不支持透明背景（background: transparent 会报错）

​
二、认证

Authorization: Bearer <你的 APIYI 令牌>
APIYI 控制台创建令牌，兼容全部常规类型。

​
三、端点

端点用途Content-Type
POST https://api.apiyi.com/v1/images/generations文生图application/json
POST https://api.apiyi.com/v1/images/edits参考图编辑 / 多图融合 / mask 重绘multipart/form-data
域名可替换为 b.apiyi.com / vip.apiyi.com 等平台其他网关，行为一致。

​
四、文生图 /v1/images/generations

​
4.1 请求参数

参数类型必填默认说明
modelstring是—固定 gpt-image-2
promptstring是—提示词，支持中英文
sizestring否auto输出尺寸，见 §六
qualitystring否autolow / medium / high / auto
output_formatstring否pngpng / jpeg / webp
output_compressionint否—0–100，仅 jpeg/webp 生效
backgroundstring否autoopaque / auto（不支持 transparent）
moderationstring否autoauto / low（低强度审核）
nint否1仅支持 1

​
4.2 请求示例

curl -X POST "https://api.apiyi.com/v1/images/generations" \
  -H "Authorization: Bearer <你的令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴墨镜的橘猫坐在海边吧台，电影画幅",
    "size": "2048x1152",
    "quality": "high",
    "output_format": "jpeg",
    "output_compression": 85
  }'

​
4.3 响应格式

{
  "created": 1776832476,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 6240,
    "total_tokens": 6282
  }
}
  • 返回字段固定为 b64_json，值是纯 base64 字符串（无 data:image/...;base64, 前缀），客户端需自行拼前缀或直接 decode 写文件。
  • usage 反映实际计费的 token 数；按此数 + 官方单价计算本次调用成本（见 §七）。

​
五、图片编辑 /v1/images/edits

用于改图、多图融合、mask 局部重绘。

​
5.1 请求字段（multipart/form-data）

字段类型必填说明
modeltext是gpt-image-2
prompttext是编辑指令
image[]file是参考图，可重复多次，最多 5 张
maskfile否掩码图（仅对第一张 image 生效，见 §5.3）
sizetext否同 §4.1
qualitytext否同 §4.1
output_formattext否同 §4.1
output_compressiontext否同 §4.1
backgroundtext否同 §4.1
💡 gpt-image-2 对参考图自动启用高保真处理，不要传 input_fidelity 参数（传了会报错）。所以编辑请求的输入 token 会比同尺寸的文生图明显更高。

​
5.2 多图融合

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer <你的令牌>" \
  -F "model=gpt-image-2" \
  -F "prompt=把图1的人物放进图2的场景，保留图3的色彩风格" \
  -F "size=1536x1024" \
  -F "quality=high" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "image[][email protected]"

​
5.3 mask 局部重绘

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer <你的令牌>" \
  -F "model=gpt-image-2" \
  -F "prompt=把天空换成粉色晚霞" \
  -F "image[][email protected]" \
  -F "[email protected]"
mask 要求：
  • 与原图相同尺寸、相同格式，单张 ≤ 50MB
  • 必须带 alpha 通道：透明区域（alpha=0）= 要重绘的部分，不透明区域 = 保留
  • mask 作为”软引导”而非精确边界，模型可能在蒙版周围扩展/收敛
响应格式与 §4.3 相同。

​
六、尺寸（size）详解

​
6.1 预设尺寸

size含义像素
auto自适应（默认）模型决定
1024x1024方形 1:11K
1536x1024横版 3:21K
1024x1536竖版 2:31K
2048x2048方形 1:12K
2048x1152横版 16:92K
3840x2160横版 16:94K
2160x3840竖版 9:164K

​
6.2 自定义尺寸约束

gpt-image-2 接受任意合法尺寸，只需同时满足：
  1. 最大边 ≤ 3840px
  2. 两条边都是 16 的倍数
  3. 长短边比例 ≤ 3:1
  4. 总像素数 ∈ [655,360, 8,294,400]（下限约 0.65MP，上限约 8.3MP）
⚠️ 超过 2560×1440（约 3.69MP）的输出目前标记为实验性，可能不稳定或出现质量波动。
合法示例：1600x1200、1792x1024、2048x1536、3200x1800 非法示例：1000x1000（非 16 倍数）、4000x4000（超上限）、3840x1000（比例超 3:1）

​
6.3 画质（quality）

档位适用场景速度
low草图、缩略图、快速迭代最快
medium日常使用均衡
high终稿、印刷、精细文字/纹理最慢
auto由模型自动选择（默认）—
方形图通常比长方形出得快。

​
七、计费

按 token 计费（输入 text + 输入 image + 输出 image 三段之和）。官方按量定价表（每张输出图）：
画质1024×10241024×15361536×1024
Low$0.006$0.005$0.005
Medium$0.053$0.041$0.041
High$0.211$0.165$0.165
2K/4K 无固定每张价，按 token 实计。对比 gpt-image-1.5，同档同尺寸 gpt-image-2 成本低约 20–30%。 输入 token（编辑场景下的参考图）按官方 Vision 计费规则换算；gpt-image-2 因强制高保真，带图编辑的输入 token 明显高于文生图。 流式出图（stream: true + partial_images: N）每张 partial 额外消耗 100 个输出 image token。

​
八、代码示例

​
8.1 Python（OpenAI SDK 直连）

from openai import OpenAI
import base64

client = OpenAI(
    api_key="<你的令牌>",
    base_url="https://api.apiyi.com/v1"
)

# 文生图
resp = client.images.generate(
    model="gpt-image-2",
    prompt="赛博朋克城市雨夜，霓虹招牌，电影画幅",
    size="2048x1152",
    quality="high",
    output_format="jpeg",
    output_compression=85
)

with open("out.jpg", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

​
8.2 Python（多图编辑）

resp = client.images.edit(
    model="gpt-image-2",
    image=[open("person.png", "rb"), open("scene.png", "rb")],
    prompt="把人物融入场景，保持光线一致",
    size="1536x1024",
    quality="high"
)

with open("edited.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

​
8.3 Node.js（原生 fetch）

import fs from 'fs';

const resp = await fetch('https://api.apiyi.com/v1/images/generations', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer <你的令牌>'
    },
    body: JSON.stringify({
        model: 'gpt-image-2',
        prompt: '极简线条风格的猫咪 LOGO',
        size: '1024x1024',
        quality: 'medium'
    })
});

const { data } = await resp.json();
fs.writeFileSync('logo.png', Buffer.from(data[0].b64_json, 'base64'));

​
8.4 浏览器 JS（文生图 → 直接渲染）

const resp = await fetch('https://api.apiyi.com/v1/images/generations', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer <你的令牌>'
    },
    body: JSON.stringify({
        model: 'gpt-image-2',
        prompt: '水彩风的北欧极光',
        size: '1536x1024',
        quality: 'high'
    })
});

const { data } = await resp.json();
document.getElementById('img').src = `data:image/png;base64,${data[0].b64_json}`;

​
8.5 cURL（mask 局部重绘）

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer <你的令牌>" \
  -F "model=gpt-image-2" \
  -F "prompt=把地板换成大理石纹理" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "image[][email protected]" \
  -F "[email protected]" \
  | jq -r '.data[0].b64_json' | base64 -d > room_edited.png

​
九、错误码

状态码含义处理建议
400参数非法（size 不合约束、传了不支持的字段等）按 §六 校验；注意不要传 input_fidelity / background: transparent
401令牌无效检查 Bearer Token
403内容审核拦截调整 prompt 或传 moderation: low
429限流 / 余额不足指数退避重试
5xx网关/后端错误重试 1–2 次
超时长尾客户端超时 ≥ 360 秒（保守值，high + 2K/4K 实测 3-5 分钟）
客户端建议：
  • 超时 360 秒起步（保守值；quality=high + 2K/4K 实测可能 3-5 分钟，按 120s 配置会大量误超时）
  • 5xx 和超时做指数退避，最多重试 2 次
  • 记录响应头 x-request-id，排障时提供给客服

​
十、从 gpt-image-1.5 迁移

  1. model: "gpt-image-1.5" → "gpt-image-2"，其它字段不变即可基本跑通。
  2. 如果原先用了 input_fidelity：移除该参数，新模型强制高保真。
  3. 如果原先用了 background: "transparent"：暂不支持，改用 opaque 或自行后处理抠透明。
  4. 想用 2K/4K：把 size 直接改成 2048x2048 / 3840x2160 等，或传任何符合 §6.2 约束的自定义尺寸。
  5. 成本预期：同档同尺寸应下降 20–30%，实际以 usage 为准。

​
十一、最佳实践

  1. 尺寸优先选预设：§6.1 的 8 个预设经过官方优化，速度和质量更稳定；自定义尺寸留给真有比例需求的场景。
  2. 画质按场景分档：草稿 / 批量 → low；默认 / 终稿 → medium；文字、精细纹理、印刷 → high。
  3. 输出格式选 JPEG：对最终展示无特别要求时，output_format=jpeg + output_compression=85 比 PNG 快且体积小一半以上。
  4. 文字场景用 high：gpt-image-2 的文字渲染是主要卖点，但 low/medium 档位仍可能糊；招牌、海报类场景锁 high。
  5. 编辑场景准备参考图：单张 ≤ 10MB，PNG/JPEG/WebP 均可；参考图数量上限 5 张；prompt 里用”图1/图2”指代顺序。
  6. 异步排队：单次调用可能 1–2 分钟，前端务必给出进度反馈；服务端建议用任务队列解耦。

​
十二、与 gpt-image-2-all 的差异

维度gpt-image-2（官方）gpt-image-2-all（官逆）
性质OpenAI 官方模型官方逆向
计价按 token，见 §七固定 $0.03/张
速度~120s~30s
尺寸控制size 参数，任意合法尺寸无 size 参数，靠 prompt 描述
画质控制quality 档位无
响应b64_json（纯 base64）url（R2 CDN）或带前缀的 b64_json
端点Images API推荐 Chat Completions
适用要精确控尺寸/画质、对官方契约有依赖追求速度、成本、简单易用

​
十三、技术支持

  • APIYI 控制台：api.apiyi.com
  • OpenAI 官方文档：developers.openai.com/api/docs/guides/image-generation
  • 问题排查：联系 APIYI 客服，附 x-request-id

​
附：变更日志

  • 2026-04 首次发布，同步 OpenAI gpt-image-2 模型上线。