GPT-Image-2 API 快速入门：10 分钟从 cURL 到生产环境

为什么值得接入 GPT-Image-2 API

在 2026 年 4 月的 LM Arena 泄露测试中，GPT-Image-2 以两项能力彻底改变了图像生成 API 的格局：

• 文字渲染准确率 99%+。GPT-Image-2 是第一个能在图像中可靠渲染长字符串的商业 API，覆盖拉丁文、中日韩、西里尔文、阿拉伯文。此前最强的 Nano Banana 2（Gemini 2.5 Flash Image）在中日韩文字上的通过率只有约 55%。
• 真正的 4K 输出。GPT-Image-2 标准版支持 2048×2048，专业版路径可达 4096×4096，是印刷与大幅广告的第一个可用商业 API 方案。

对于任何涉及海报设计、包装生成、UI 原型截图、信息图自动化的产品，GPT-Image-2 的接入都是从"可以用"到"可以上线"的质变。本文将带你从零完成 GPT-Image-2 API 的完整接入流程。

前置准备：获取 API Key

接入 GPT-Image-2 API 有两条路径：

本文示例均使用 APIMart 端点，代码与 OpenAI 官方端点完全兼容，切换只需改变 base_url 一个参数。

获取 API Key 步骤：

1. 访问 apimart.ai 注册账号。
2. 在控制台创建新的 API Key，记录保存（仅显示一次）。
3. 充值余额或激活免费额度（新用户通常有 $5 免费测试额度）。

鉴权设置

GPT-Image-2 API 使用标准的 Bearer Token 鉴权机制，与 OpenAI API 完全一致。所有请求必须在 HTTP Header 中携带：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

推荐通过操作系统环境变量管理密钥：

# macOS / Linux（加入 ~/.bashrc 或 ~/.zshrc 使其永久生效）
export APIMART_API_KEY="sk-your-api-key-here"

# Windows PowerShell
$env:APIMART_API_KEY = "sk-your-api-key-here"

# .env 文件（配合 python-dotenv 或 dotenv npm 包）
APIMART_API_KEY=sk-your-api-key-here

第一个 cURL 请求

下面是调用 GPT-Image-2 API 生成图像的完整 cURL 命令，可直接在终端执行：

curl https://apimart.ai/v1/images/generations \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张简洁的 SaaS 产品宣传海报，白色背景，顶部蓝色 Banner 显示文字\"季度增长 +37%\"，下方三个功能图标及说明文字，现代无衬线字体，商业摄影风格",
    "size": "1792x1024",
    "quality": "high",
    "n": 1,
    "response_format": "url"
  }'

成功响应格式（response_format: url）：

{
  "created": 1745280000,
  "data": [
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/...",
      "revised_prompt": "一张简洁的 SaaS 产品宣传海报..."
    }
  ]
}

成功响应格式（response_format: b64_json）：

{
  "created": 1745280000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAB...",
      "revised_prompt": "..."
    }
  ]
}

Python SDK 代码示例

以下是完整可运行的 Python 示例，使用 OpenAI 官方 Python SDK 连接 GPT-Image-2 API：

# 安装依赖：pip install openai python-dotenv requests
import os
import base64
import requests
from pathlib import Path
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

# 初始化客户端，指向 APIMart 端点（兼容 OpenAI SDK）
client = OpenAI(
    api_key=os.environ["APIMART_API_KEY"],
    base_url="https://apimart.ai/v1",  # 切换至 OpenAI 直接接入时改为 https://api.openai.com/v1
)

def generate_image(
    prompt: str,
    size: str = "1024x1024",
    quality: str = "high",
    n: int = 1,
    output_path: str = "output.png",
) -> str:
    """
    调用 GPT-Image-2 生成图像并保存到本地。

    Args:
        prompt: 图像描述提示词
        size: 图像尺寸，支持 "1024x1024" / "1792x1024" / "1024x1792" / "2048x2048"
        quality: "standard" 或 "high"（高质量模式）
        n: 生成数量（1–4）
        output_path: 本地保存路径

    Returns:
        保存的本地文件路径
    """
    response = client.images.generate(
        model="gpt-image-2",
        prompt=prompt,
        size=size,
        quality=quality,
        n=n,
        response_format="b64_json",  # 使用 b64_json 避免 URL 过期问题
    )

    image_data = base64.b64decode(response.data[0].b64_json)
    Path(output_path).write_bytes(image_data)
    print(f"图像已保存至：{output_path}")
    return output_path


def generate_batch(prompts: list[str], output_dir: str = "outputs/") -> list[str]:
    """批量生成图像，逐个请求避免触发限速。"""
    import time
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    results = []
    for i, prompt in enumerate(prompts):
        try:
            path = generate_image(
                prompt=prompt,
                output_path=f"{output_dir}/image_{i+1:03d}.png",
            )
            results.append(path)
            if i < len(prompts) - 1:
                time.sleep(0.5)  # 简单限速缓冲
        except Exception as e:
            print(f"第 {i+1} 张生成失败：{e}")
            results.append(None)
    return results


if __name__ == "__main__":
    generate_image(
        prompt=(
            "高端咖啡品牌海报，品牌名 'Aurora Roast' 使用优雅衬线字体显示在顶部，"
            "下方是一杯冒着热气的手冲咖啡特写，深棕色调，影棚布光，"
            "底部文字 '每一杯，都是清晨的仪式感'"
        ),
        size="1792x1024",
        quality="high",
        output_path="coffee_poster.png",
    )

Node.js 代码示例

以下是使用 OpenAI Node.js SDK 接入 GPT-Image-2 的完整示例：

// 安装依赖：npm install openai dotenv
import OpenAI from "openai";
import fs from "fs";
import path from "path";
import dotenv from "dotenv";

dotenv.config();

// 初始化客户端（兼容 OpenAI SDK，仅需修改 baseURL）
const client = new OpenAI({
  apiKey: process.env.APIMART_API_KEY,
  baseURL: "https://apimart.ai/v1",
});

/**
 * 调用 GPT-Image-2 生成图像
 * @param {string} prompt - 图像描述
 * @param {Object} options - 可选参数
 * @returns {Promise<Buffer>} - 图像二进制数据
 */
async function generateImage(prompt, options = {}) {
  const {
    size = "1024x1024",
    quality = "high",
    n = 1,
    outputPath = "output.png",
  } = options;

  const response = await client.images.generate({
    model: "gpt-image-2",
    prompt,
    size,
    quality,
    n,
    response_format: "b64_json",
  });

  const imageBuffer = Buffer.from(response.data[0].b64_json, "base64");
  fs.writeFileSync(outputPath, imageBuffer);
  console.log(`图像已保存至：${outputPath}`);
  return imageBuffer;
}

/**
 * 带指数退避的重试包装器
 * @param {Function} fn - 待重试的异步函数
 * @param {number} maxRetries - 最大重试次数
 */
async function withRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      const isRetryable = [429, 500, 502, 503].includes(error?.status);
      if (!isRetryable) throw error;
      const delay = Math.min(1000 * Math.pow(2, attempt), 16000);
      console.log(`第 ${attempt + 1} 次重试，等待 ${delay}ms...`);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

// 使用示例
async function main() {
  await withRetry(() =>
    generateImage(
      "极简主义产品展示图：一双白色运动鞋放置在纯白大理石台面上，" +
      "自然侧光，右下角清晰显示品牌名 'STRYDE' 和 tagline 'Move Forward'，" +
      "高端商业摄影风格，4K 质感",
      {
        size: "1792x1024",
        quality: "high",
        outputPath: "sneaker_ad.png",
      }
    )
  );
}

main().catch(console.error);

请求参数详解

GPT-Image-2 API 请求体支持以下参数，理解每个参数的边界有助于在成本与质量之间取得最佳平衡：

错误处理：400 / 401 / 429 / 500 重试逻辑

GPT-Image-2 API 遵循标准 HTTP 状态码规范。以下是各类错误的含义与处理建议：

以下是 Python 版完整的带指数退避重试逻辑：

import time
import openai

def generate_with_retry(client, prompt: str, max_retries: int = 3, **kwargs):
    """带指数退避的 GPT-Image-2 图像生成函数。"""
    RETRYABLE_CODES = {429, 500, 502, 503}

    for attempt in range(max_retries + 1):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                **kwargs,
            )
        except openai.APIStatusError as e:
            if e.status_code not in RETRYABLE_CODES or attempt == max_retries:
                raise  # 不可重试或已超最大次数，直接抛出

            # 429 时优先读取 Retry-After 头
            retry_after = None
            if e.status_code == 429 and hasattr(e, "response"):
                retry_after = e.response.headers.get("Retry-After")

            wait = float(retry_after) if retry_after else min(2 ** attempt, 16)
            print(f"[{e.status_code}] 第 {attempt + 1} 次重试，等待 {wait:.1f}s...")
            time.sleep(wait)

        except openai.APIConnectionError:
            if attempt == max_retries:
                raise
            time.sleep(2 ** attempt)

    raise RuntimeError("超过最大重试次数")

限速与成本优化

合理控制 GPT-Image-2 API 的调用频率，不仅能避免触发限速，更能有效降低整体成本。

了解限速指标

GPT-Image-2 API 通常有两类限速维度：

• RPM（每分钟请求数）：生产环境常见阈值为 60–120 RPM，具体取决于账号等级。
• 并发连接数：同一时间最多允许的并发 HTTP 请求数，通常为 5–10。

成本优化策略

• 按需选择 quality 参数。草稿预览用 quality: "standard"，节省约 30% 成本；只有需要印刷或上线的终稿才用 "high"。
• 批量生成优于多次单张。单次请求 n=4 比 4 次 n=1 的网络开销更低，但注意 n 值不影响限速计算（每张均计入 RPM）。
• 尺寸优先用 1024x1024。非必要不请求 2048x2048 或 4K，分辨率越高单价越高。
• 缓存相同 prompt 的结果。对于固定模板（如品牌占位图），用 Redis 或文件系统缓存结果，避免重复计费。
• 用 APIMart 路由混合模型。草稿批次路由至 Nano Banana，终稿路由至 GPT-Image-2，综合成本可降低 60–70%。

生产环境检查清单

在将 GPT-Image-2 API 集成推送至生产环境前，请逐项确认以下清单：

• API Key 安全：通过环境变量或密钥管理服务（如 AWS Secrets Manager、Vault）注入，严禁硬编码或提交至 Git 仓库。
• 重试逻辑：所有请求包裹在带指数退避的重试函数中，覆盖 429 / 5xx 场景。
• 超时设置：HTTP 客户端设置合理的 connect_timeout（5s）和 read_timeout（60s），防止长时间挂起。
• 图像存储：不依赖 URL 格式的临时链接，始终将 b64_json 结果持久化到对象存储。
• 内容安全过滤：在 prompt 进入 GPT-Image-2 前，做一轮业务层的敏感词过滤，降低 400 违规错误率。
• 用量监控：接入 APIMart 控制台或 OpenAI 用量 API，配置超出预算的告警阈值。
• 日志记录：记录每次请求的 prompt（脱敏后）、参数、响应时间、状态码，用于成本分析与故障排查。
• 降级策略：GPT-Image-2 不可用时（计划维护或突发故障），自动降级至 Nano Banana，保证服务连续性。
• CORS 配置：如果前端直接调用图像 API，确保后端代理层正确设置 CORS 头，避免暴露 API Key。
• 速率限流（应用层）：在应用层为终端用户设置个人调用频率上限，防止单用户耗尽配额。

常见问题