GPT-Image-2 API Quickstart: From cURL to Production in 10 Minutes

Why GPT-Image-2 is Worth Integrating

GPT-Image-2 is the first commercially-available image generation API to genuinely solve the three problems that have plagued AI image pipelines since 2022: garbled text, slow latency, and washed-out 1K-capped resolution. When GPT-Image-2 appeared on LM Arena in April 2026, testers immediately noted 99%+ glyph accuracy on long strings — including dense CJK, Cyrillic, and Arabic — where every predecessor, including DALL·E 3 and Nano Banana, still fails at non-trivial copy density.

Beyond text rendering, GPT-Image-2 raises the bar on two other fronts that matter for production use:

• Resolution: GPT-Image-2 outputs natively at 2048×2048 on the standard tier and 4096×4096 on pro — true 4K without post-processing upscales that introduce interpolation artifacts.
• Speed: GPT-Image-2 generates a standard-resolution image in 2–3 seconds, down from 8–12 seconds in v1.5, putting it on par with Google's Nano Banana for most workloads.

If your product generates ads, packaging mockups, infographics, UI screenshots, or any asset where the words inside the image have to be correct, GPT-Image-2 is the upgrade you've been waiting for. The GPT-Image-2 API uses the same OpenAI-compatible schema you already know, so migration cost is minimal.

Prerequisites

Before you write a single line of GPT-Image-2 integration code, confirm you have the following:

• API key: Either an OpenAI API key with GPT-Image-2 access (check your tier eligibility), or an APIMart API key — which is available now and provides drop-in GPT-Image-2 compatibility with unified billing and higher rate limits.
• Python 3.9+ if using the Python path (3.11 recommended). Install the OpenAI SDK: pip install openai
• Node.js 18+ if using the Node.js path. Install the OpenAI SDK: npm install openai
• curl 7.68+ for the command-line examples (ships with macOS 12+ and most Linux distros).

Authentication

GPT-Image-2 uses standard Bearer token authentication. Set your API key as an environment variable — never hardcode it in source files.

# For OpenAI direct access
export OPENAI_API_KEY="sk-proj-..."

# For APIMart (drop-in compatible — same schema, same SDKs)
export OPENAI_API_KEY="am-..."
export OPENAI_BASE_URL="https://api.apimart.ai/v1"

The GPT-Image-2 API is fully compatible with the OpenAI Python and Node.js SDKs. When using APIMart, the only change is the base_url — every other SDK call, parameter, and response shape is identical. This means your GPT-Image-2 integration works against both endpoints with zero code changes; you route by environment variable alone.

First Call with cURL

The fastest way to validate your GPT-Image-2 API key is a raw cURL call. This sends a single GPT-Image-2 generation request and returns a base64-encoded PNG.

curl https://api.openai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a matte black coffee thermos on a slate surface, steam rising, moody studio lighting, photorealistic",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "b64_json"
  }'

A successful GPT-Image-2 response looks like this:

{
  "created": 1745200000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "A cinematic product photo of a matte black coffee thermos..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1024,
    "total_tokens": 1066
  }
}

To save the GPT-Image-2 output directly to a file, pipe the response through jq:

curl https://api.openai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Editorial poster: the word LAUNCH in bold white sans-serif on a deep space background, with Earth visible below",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "b64_json"
  }' | jq -r '.data[0].b64_json' | base64 --decode > gpt-image-2-output.png

Python SDK Example

The following GPT-Image-2 Python integration uses the official OpenAI SDK and includes proper error handling, base64 decoding, and file saving.

import os
import base64
from pathlib import Path
from openai import OpenAI

# Initialize the client — swap base_url for APIMart if needed
client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    # base_url="https://api.apimart.ai/v1",  # Uncomment for APIMart
)

def generate_image(prompt: str, output_path: str = "output.png") -> str:
    """Generate an image with GPT-Image-2 and save it to disk."""
    response = client.images.generate(
        model="gpt-image-2",
        prompt=prompt,
        size="1024x1024",       # Options: 1024x1024, 1536x1024, 1024x1536, 2048x2048
        quality="high",          # Options: "standard" | "high"
        n=1,                     # Number of images (1–4)
        response_format="b64_json",
    )

    image_data = response.data[0].b64_json
    image_bytes = base64.b64decode(image_data)
    Path(output_path).write_bytes(image_bytes)
    print(f"GPT-Image-2 image saved to {output_path}")
    return output_path

if __name__ == "__main__":
    generate_image(
        prompt="A high-contrast infographic poster: '2026 AI Report' headline in bold Helvetica, "
               "three icon columns below labelled Speed, Accuracy, Scale, dark navy background, "
               "white and indigo color scheme",
        output_path="gpt-image-2-infographic.png",
    )

For async workloads — common in FastAPI or Django Channels apps integrating GPT-Image-2 — use the async client:

import asyncio
import base64
from pathlib import Path
from openai import AsyncOpenAI

async_client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def generate_batch(prompts: list[str]) -> list[str]:
    """Generate multiple GPT-Image-2 images concurrently."""
    tasks = [
        async_client.images.generate(
            model="gpt-image-2",
            prompt=p,
            size="1024x1024",
            quality="high",
            n=1,
            response_format="b64_json",
        )
        for p in prompts
    ]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    paths = []
    for i, res in enumerate(results):
        if isinstance(res, Exception):
            print(f"GPT-Image-2 request {i} failed: {res}")
        else:
            path = f"output_{i}.png"
            Path(path).write_bytes(base64.b64decode(res.data[0].b64_json))
            paths.append(path)
    return paths

Node.js Example

The GPT-Image-2 Node.js integration follows the same pattern. This example uses ES modules and the official OpenAI SDK.

import OpenAI from "openai";
import { writeFileSync } from "fs";

// Initialize — point base_url at APIMart for unified access
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  // baseURL: "https://api.apimart.ai/v1", // Uncomment for APIMart
});

async function generateImage(prompt, outputPath = "output.png") {
  const response = await client.images.generate({
    model: "gpt-image-2",
    prompt,
    size: "1024x1024",      // "1024x1024" | "1536x1024" | "1024x1536" | "2048x2048"
    quality: "high",         // "standard" | "high"
    n: 1,
    response_format: "b64_json",
  });

  const imageData = response.data[0].b64_json;
  const imageBuffer = Buffer.from(imageData, "base64");
  writeFileSync(outputPath, imageBuffer);
  console.log(`GPT-Image-2 image saved to ${outputPath}`);
  return outputPath;
}

// Example: generate a product label with GPT-Image-2
await generateImage(
  'Product label for "Solstice Gin" — botanical illustration of juniper and elderflower, ' +
  'script font for the brand name, gold on deep green background, premium spirits aesthetic',
  "gpt-image-2-label.png"
);

For Express.js or Next.js API routes, wrap the GPT-Image-2 call in a try/catch and stream the response to the client:

// Next.js App Router: app/api/generate/route.js
import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export async function POST(request) {
  const { prompt, size = "1024x1024" } = await request.json();

  try {
    const response = await client.images.generate({
      model: "gpt-image-2",
      prompt,
      size,
      quality: "high",
      n: 1,
      response_format: "b64_json",
    });
    return Response.json({ image: response.data[0].b64_json });
  } catch (err) {
    const status = err.status ?? 500;
    return Response.json({ error: err.message }, { status });
  }
}

Request Schema Reference

The GPT-Image-2 API accepts the following parameters on the POST /v1/images/generations endpoint. Understanding each field helps you squeeze maximum quality out of each GPT-Image-2 generation.

Error Handling

GPT-Image-2 returns standard HTTP status codes. Implement handling for the four codes you'll hit regularly in any GPT-Image-2 integration:

Here is a production-ready retry wrapper for Python GPT-Image-2 calls:

import time
import random
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

def generate_with_retry(prompt: str, max_retries: int = 3) -> dict:
    """Call GPT-Image-2 with exponential backoff on retryable errors."""
    for attempt in range(max_retries):
        try:
            response = client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high",
                n=1,
                response_format="b64_json",
            )
            return response
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"GPT-Image-2 rate limit hit. Retrying in {wait:.1f}s...")
            time.sleep(wait)
        except APIStatusError as e:
            if e.status_code in (500, 503) and attempt < max_retries - 1:
                wait = (2 ** attempt) + random.uniform(0, 1)
                print(f"GPT-Image-2 server error {e.status_code}. Retrying in {wait:.1f}s...")
                time.sleep(wait)
            else:
                raise

Rate Limits & Cost Optimization

GPT-Image-2 is billed per image generated (not per token in the traditional sense). Getting your cost model right from day one avoids surprises at invoice time.

Rate limit basics

The GPT-Image-2 API enforces rate limits at two levels: requests per minute (RPM) and images per minute (IPM). Your tier determines these ceilings. Direct OpenAI access starts at conservative limits during the GPT-Image-2 rollout; APIMart aggregates across multiple provider accounts to offer higher sustained throughput.

Cost optimization strategies

• Batch with n>1: Sending n=4 in a single GPT-Image-2 call is more efficient than 4 separate calls — you pay one API overhead and get 4 images. Use this for variation generation in creative tools.
• Use "standard" quality for drafts: GPT-Image-2 "standard" quality is substantially faster and slightly cheaper. Run draft-mode generation in standard, then upgrade to "high" for the selected hero image only.
• Cache aggressively: GPT-Image-2 output for an identical prompt and parameters is deterministic enough to cache. Store the b64_json in S3 or R2 keyed on a hash of (model, prompt, size, quality) — repeat requests for the same asset cost nothing.
• Use b64_json, not URLs: GPT-Image-2 temporary URLs expire in 60 minutes and aren't cacheable downstream. Always decode and store the binary yourself.
• Route by asset importance: Run bulk drafts through a cheaper model (e.g., Nano Banana at ~$0.039/image) and escalate to GPT-Image-2 only for the final customer-facing render. Teams using this pattern report 60–70% lower image costs.

Production Checklist

Before you ship your GPT-Image-2 integration to users, run through this checklist:

• Env vars, not hardcoded keys: OPENAI_API_KEY should come from a secrets manager (AWS Secrets Manager, Vercel env, Doppler) — never committed to git. Scan your repo for the string sk- before every deploy.
• Server-side only: Never call the GPT-Image-2 API from client-side JavaScript. Your API key would be exposed in browser devtools. Route all GPT-Image-2 requests through your backend or an edge function.
• Set request timeouts: GPT-Image-2 at 4K quality can take 6–8 seconds. Set your HTTP client timeout to at least 30 seconds and surface a user-facing "generating…" state.
• Log structured metadata: Log model, size, quality, prompt_hash, latency_ms, and status for every GPT-Image-2 call. This is essential for cost attribution and debugging prompt failures.
• Content policy compliance: GPT-Image-2 enforces OpenAI's usage policy. Build a content moderation layer (e.g., the OpenAI Moderation API) before the prompt reaches GPT-Image-2 to avoid unexpected 400 errors in production.
• Graceful degradation: When GPT-Image-2 returns a 500 or is unavailable, fall back to a cached placeholder or a lower-tier model rather than breaking the user flow.
• Monitor spend in real time: Set usage alerts in your OpenAI dashboard (or APIMart dashboard) so you catch runaway usage before your monthly invoice.

Frequently Asked Questions