GPT-Image-2 图像生成

• 模型名：gpt-image-2（固定）
• 接口：POST https://apimaster.ai/v1/images/generations（与 OpenAI 官方 相同）
• 模式：支持 同步兼容 与 异步提交 两种调用方式（见下）

不要用 /v1/chat/completions 调用本模型；若误用会返回 400 并提示改用 Images API。

调用模式

模式	端点	适用场景
同步兼容（推荐）	POST https://apimaster.ai/v1/images/generations	与 OpenAI SDK 一致，一次请求直接返回 { "data": [{ "url" }] }（平台在服务端轮询等待）
异步提交	POST https://apimaster.ai/v1/images/generations/async	长任务、批量流水线；立即返回 task_id，客户端自行轮询

两种模式请求体相同（model、prompt、size、resolution 等）。

快速开始（同步，OpenAI 兼容）

curl -s "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格"
  }'

成功响应（OpenAI 格式）

{
  "created": 1717500000,
  "data": [
    { "url": "https://apimaster.ai/imgs/....png" }
  ]
}

OpenAI Python SDK 示例：

from openai import OpenAI
client = OpenAI(base_url="https://apimaster.ai/v1", api_key="YOUR_API_KEY")
resp = client.images.generate(model="gpt-image-2", prompt="a corgi on the moon")
print(resp.data[0].url)

客户端超时建议

档位	建议 HTTP 读超时
1k 默认	≥ 180 秒
2k / medium	≥ 300 秒
4k / high	≥ 600 秒

认证

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求参数

字段	类型	必填	说明
model	string	是	固定 gpt-image-2
prompt	string	是	画面描述（中英文）；会经平台安全审核
n	integer	否	生成张数；默认 1，使用高级参数时支持 1–4
size	string	否	比例，默认 1:1；见下表
resolution	string	否	1k / 2k / 4k，默认 1k
image_urls	array	否	参考图；传入后为图生图
official_fallback	boolean	否	标准请求失败重试时是否允许升级到官方能力渠道，默认 false

高级参数（自动路由官方渠道）

对外统一使用 model: "gpt-image-2"。当请求包含下列任一字段时，平台会自动路由到支持完整 OpenAI 参数的上游渠道：

字段	类型	默认	说明
quality	string	auto	low / medium / high；4K + high 可能 >120s
background	string	auto	opaque / transparent（部分上游不支持透明，会降级为 auto）
moderation	string	auto	low 为更宽松审核
output_format	string	png	jpeg / webp
output_compression	integer	—	0–100，仅 jpeg/webp
n	integer	1	1–4 张（与上表 n 共用）
mask_url	string	—	遮罩图 URL，局部重绘；须与首张参考图同尺寸，需带 Alpha

高级参数示例（局部重绘）

{
  "model": "gpt-image-2",
  "prompt": "把背景换成沙漠日落",
  "size": "1:1",
  "quality": "medium",
  "image_urls": ["https://your-cdn.com/photo.png"],
  "mask_url": "https://your-cdn.com/mask.png"
}

size 支持的比例

auto、1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、3:1、1:3、21:9、9:21。也可直接传像素，如 1881x836。

resolution 与像素（节选）

size	1k	2k	4k
1:1	1024×1024	2048×2048	2880×2880
16:9	1536×864	2048×1152	3840×2160
9:16	864×1536	1152×2048	2160×3840

4K 支持上表全部 15 种比例。

image_urls（图生图）

• 最多 16 张，超出会报错
• 支持公网 URL 与 base64 data URI（data:image/png;base64,...）混填
• 不传 size 时输出分辨率可跟随输入图；传 size 则按指定比例出图

请求示例

文生图（16:9 + 2K）

curl -s "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a corgi astronaut on the moon, cinematic, 8k",
    "size": "16:9",
    "resolution": "2k"
  }'

图生图（URL + base64 混填）

{
  "model": "gpt-image-2",
  "prompt": "把这两张照片融合成一张海报",
  "size": "4:3",
  "resolution": "2k",
  "image_urls": [
    "https://example.com/photo-a.jpg",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}

错误响应

HTTP	含义
400	参数错误，或误用 chat 端点
401	API Key 无效
402	余额不足
408	生成超时（可降低 resolution / quality 后重试）
429	限流
500 / 503	服务或上游异常

超时示例（OpenAI 风格）：

{
  "error": {
    "message": "Image generation timed out after 600 seconds. Retry with lower resolution or quality.",
    "type": "server_error",
    "code": "image_generation_timeout"
  }
}

异步模式：提交任务

使用 POST https://apimaster.ai/v1/images/generations/async，请求体与同步模式相同。响应立即返回 task_id，不会阻塞等待出图：

curl -s "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "size": "16:9",
    "resolution": "2k"
  }'

提交响应

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"
    }
  ]
}

异步模式：轮询任务结果

拿到 task_id 后，调用任务查询接口：

curl -s "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

• ?model=gpt-image-2 用于路由到正确渠道
• 完成时取图：data.result.images[0].url[0]
• 提交响应（/images/generations/async）里的 status 为 submitted；轮询响应（GET /tasks/...）里进行中常见 pending，也可能出现 processing / in_progress，终态为 completed 或 failed

阶段	典型 status	含义
提交成功	submitted	仅出现在 async 提交响应的 data[] 中
排队 / 生成中	pending、processing、in_progress	轮询时继续等待，不要因 pending 误判为失败
成功	completed	可取 data.result.images[0].url[0]
失败	failed、error、cancelled	查看响应中的错误信息

轮询建议

• 首次查询延迟 10–20 秒，之后每 3–5 秒 查一次
• 2k / 4k 任务可能超过 2 分钟，客户端 HTTP 读超时可设 ≥ 30 秒（单次查询），总等待时间由你的轮询逻辑控制
• 若同步模式返回 408 超时，可改用异步模式重试同一请求

Python 异步示例：

import time
import requests

API = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
body = {"model": "gpt-image-2", "prompt": "a corgi on the moon", "size": "16:9", "resolution": "2k"}

task_id = requests.post(f"{API}/images/generations/async", headers=headers, json=body, timeout=60).json()["data"][0]["task_id"]
time.sleep(15)
while True:
    r = requests.get(f"{API}/tasks/{task_id}", headers=headers, params={"model": "gpt-image-2"}, timeout=30).json()
    status = r.get("data", {}).get("status")
    if status == "completed":
        print(r["data"]["result"]["images"][0]["url"][0])
        break
    if status in ("failed", "error", "cancelled"):
        raise RuntimeError(r)
    # pending / processing / in_progress → 继续轮询
    time.sleep(4)

注意事项

1. 调用端点：文生图用 POST /images/generations（同步）或 POST /images/generations/async（异步）；勿用 Chat Completions。
2. 审核：prompt 违规会直接拒绝，通常不计费。
3. 比例：推荐只用 size 字段指定比例，避免在 prompt 里重复写比例造成冲突。
4. 计费：按分辨率档位（1K / 2K / 4K）；失败与审核未通过 generally 不扣费（以控制台为准）。
5. 链接时效：返回 URL 建议在有效期内下载或转存自有存储。
6. 智能路由：含 quality、mask_url、n>1 等高级参数时自动走官方能力渠道；纯文生图 / 标准图生图优先性价比更高的标准渠道。