GPT Image 2.5 API 接入教程：Flare 和 Sunburst 怎么选，附 image2 API 迁移代码

# macOS / Linux
export OPENAI_API_KEY="sk-proj-your-key-here"

# Windows PowerShell
setx OPENAI_API_KEY "sk-proj-your-key-here"

# Python 3.10 及以上
pip install --upgrade openai

# Node.js 22 及以上
npm install openai@latest

import base64
from openai import OpenAI

client = OpenAI()  # 自动读取 OPENAI_API_KEY

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt=(
        "一只白色不锈钢保温瓶立在米色亚麻桌布上，"
        "清晨柔和的窗光，高级产品摄影"
    ),
    size="1024x1024",
    quality="medium",
)

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

// generate.mjs
import fs from 'node:fs';
import OpenAI from 'openai';

const client = new OpenAI(); // 自动读取 OPENAI_API_KEY

const result = await client.images.generate({
  model: 'gpt-image-2.5-flare',
  prompt: '一只白色不锈钢保温瓶立在米色亚麻桌布上，清晨柔和的窗光，高级产品摄影',
  size: '1024x1024',
  quality: 'medium',
});

fs.writeFileSync('bottle.png', Buffer.from(result.data[0].b64_json, 'base64'));

curl -s https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "一只白色不锈钢保温瓶立在米色亚麻桌布上，清晨柔和的窗光",
    "size": "1024x1024",
    "quality": "medium"
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > bottle.png

def check_size(size: str) -> str:
    """发请求前预检尺寸，适用于 gpt-image-2 和 GPT Image 2.5 系列。"""
    if size == "auto":
        return size
    width, height = (int(v) for v in size.lower().split("x"))
    problems = []
    if width % 16 or height % 16:
        problems.append("宽和高必须是 16 的倍数")
    if max(width, height) > 3 * min(width, height):
        problems.append("宽高比必须在 1:3 到 3:1 之间")
    if max(width, height) > 3840:
        problems.append("任何一边都不能超过 3840 px")
    if not 655_360 <= width * height <= 8_294_400:
        problems.append("总像素必须在 655,360 到 8,294,400 之间")
    if problems:
        raise ValueError(f"{size}：" + "；".join(problems))
    return size

curl -s https://api.openai.com/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "image[]=@bottle.png" \
  -F "image[]=@label-artwork.png" \
  -F "image[]=@marble-counter.jpg" \
  -F "image[]=@lemons.webp;type=image/webp" \
  -F "prompt=把保温瓶放到大理石台面上，瓶身包上那张纸质标签图案，旁边摆两个柠檬。瓶子的形状和瓶盖保持不变。" \
  -F "size=1536x1024" \
  -F "quality=high" \
  | jq -r '.data[0].b64_json' | base64 --decode > bottle-counter.png

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

MIME = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
refs = ["bottle.png", "label-artwork.png", "marble-counter.jpg", "lemons.webp"]

def as_upload(path: str):
    p = Path(path)
    return (p.name, p.read_bytes(), MIME[p.suffix.lower()])

result = client.images.edit(
    model="gpt-image-2.5-flare",
    image=[as_upload(p) for p in refs],  # 最多 16 个文件
    prompt=(
        "把保温瓶放到大理石台面上，瓶身包上那张纸质标签图案，"
        "旁边摆两个柠檬。瓶子的形状和瓶盖保持不变。"
    ),
    size="1536x1024",
    quality="high",
)

Path("bottle-counter.png").write_bytes(base64.b64decode(result.data[0].b64_json))

// edit.mjs
import fs from 'node:fs';
import path from 'node:path';
import OpenAI, { toFile } from 'openai';

const client = new OpenAI();

const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' };
const refs = ['bottle.png', 'label-artwork.png', 'marble-counter.jpg', 'lemons.webp'];

const images = await Promise.all(
  refs.map((file) =>
    toFile(fs.createReadStream(file), path.basename(file), {
      type: MIME[path.extname(file).toLowerCase()],
    }),
  ),
);

const result = await client.images.edit({
  model: 'gpt-image-2.5-flare',
  image: images, // 最多 16 个文件
  prompt: '把保温瓶放到大理石台面上，瓶身包上那张纸质标签图案，旁边摆两个柠檬。瓶子的形状和瓶盖保持不变。',
  size: '1536x1024',
  quality: 'high',
});

fs.writeFileSync('bottle-counter.png', Buffer.from(result.data[0].b64_json, 'base64'));

 result = client.images.generate(
-    model="gpt-image-2",
+    model="gpt-image-2.5-flare-2026-09-08",
     prompt=prompt,
     size="1536x1024",
     quality="high",
 )

import asyncio
import base64
from openai import AsyncOpenAI

client = AsyncOpenAI(max_retries=4)

async def generate_one(i: int, prompt: str, sem: asyncio.Semaphore) -> None:
    async with sem:
        result = await client.images.generate(
            model="gpt-image-2.5-flare",
            prompt=prompt,
            size="1024x1024",
            quality="low",
        )
    with open(f"draft-{i:03}.png", "wb") as f:
        f.write(base64.b64decode(result.data[0].b64_json))

async def main(prompts: list[str], concurrency: int = 4) -> None:
    sem = asyncio.Semaphore(concurrency)
    results = await asyncio.gather(
        *(generate_one(i, p, sem) for i, p in enumerate(prompts)),
        return_exceptions=True,
    )
    for i, r in enumerate(results):
        if isinstance(r, Exception):
            print(f"第 {i} 条失败：{r!r}")

asyncio.run(main(["提示词一", "提示词二", "提示词三"]))

// batch.mjs
import fs from 'node:fs';
import OpenAI from 'openai';
import pLimit from 'p-limit';

const client = new OpenAI({ maxRetries: 4 });
const limit = pLimit(4);
const prompts = ['提示词一', '提示词二', '提示词三'];

const results = await Promise.allSettled(
  prompts.map((prompt, i) =>
    limit(async () => {
      const result = await client.images.generate({
        model: 'gpt-image-2.5-flare',
        prompt,
        size: '1024x1024',
        quality: 'low',
      });
      fs.writeFileSync(`draft-${i}.png`, Buffer.from(result.data[0].b64_json, 'base64'));
    }),
  ),
);

results.forEach((r, i) => {
  if (r.status === 'rejected') console.error(`第 ${i} 条失败：`, r.reason?.message);
});

import base64
from openai import OpenAI

client = OpenAI()

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="一只白色不锈钢保温瓶立在米色亚麻桌布上",
    size="1024x1024",
    stream=True,
    partial_images=2,
)

for event in stream:
    if event.type == "image_generation.partial_image":
        name = f"preview-{event.partial_image_index}.png"
    elif event.type == "image_generation.completed":
        name = "final.png"
    else:
        continue
    with open(name, "wb") as f:
        f.write(base64.b64decode(event.b64_json))

// stream.mjs
import fs from 'node:fs';
import OpenAI from 'openai';

const client = new OpenAI();

const stream = await client.images.generate({
  model: 'gpt-image-2.5-flare',
  prompt: '一只白色不锈钢保温瓶立在米色亚麻桌布上',
  size: '1024x1024',
  stream: true,
  partial_images: 2,
});

for await (const event of stream) {
  if (event.type === 'image_generation.partial_image') {
    fs.writeFileSync(`preview-${event.partial_image_index}.png`, Buffer.from(event.b64_json, 'base64'));
  } else if (event.type === 'image_generation.completed') {
    fs.writeFileSync('final.png', Buffer.from(event.b64_json, 'base64'));
  }
}

import base64
import openai
from openai import OpenAI

client = OpenAI(max_retries=0)  # 重试交给任务队列决定

BILLING_CODES = {
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
}

def generate(prompt: str) -> tuple[str, bytes | None]:
    try:
        result = client.images.generate(
            model="gpt-image-2.5-flare",
            prompt=prompt,
            size="1024x1024",
            quality="medium",
        )
        return "ok", base64.b64decode(result.data[0].b64_json)

    except openai.BadRequestError as e:
        if e.code == "moderation_blocked":
            body = e.body if isinstance(e.body, dict) else {}
            print("被拦截：", body.get("moderation_details"), e.request_id)
            return "blocked", None  # 给用户一条笼统的提示
        print("请求有误：", e.message, e.request_id)
        return "fix_request", None  # 原样重发还会失败

    except openai.RateLimitError as e:
        if e.code in BILLING_CODES or e.type == "insufficient_quota":
            return "billing", None  # 充值或调高上限
        return "retry_later", None  # 延迟后重新入队

    except (openai.AuthenticationError, openai.PermissionDeniedError) as e:
        print("账号问题：", e.status_code, e.request_id)
        return "check_account", None  # 检查 key、项目或地区

    except (openai.APIConnectionError, openai.InternalServerError):
        return "retry_later", None