GPT Image 2 API: Complete Guide (Python, Node.js, Curl)

If you want to integrate GPT Image 2 into your own product, automation pipeline, or batch generation workflow, the API is the only way. This guide covers everything you need — authentication, parameters, code samples for Python and Node.js, image editing, error handling, and cost optimization.

By the end, you will have a working GPT Image 2 integration that handles real production traffic.

Prerequisites

Before you start:

1. An OpenAI developer account (platform.openai.com)
2. A funded billing account (image generation is paid; new accounts may receive trial credits)
3. An API key — generate one at platform.openai.com/api-keys
4. Python 3.8+ or Node.js 18+ depending on which SDK you want to use

Stable API access for production teams

If your team is in a region where direct OpenAI access is unstable, or you need a single relay that handles failover, billing aggregation, and SLA guarantees, you can also obtain a managed GPT Image 2 API key by emailing support@gpt-image2.art. The relay supports the same gpt-image-2 model name, the same parameters described below, and the same response format — so your code does not need to change.

Step 1: Install the SDK

Python

pip install openai pillow

pillow is optional, only needed if you plan to do post-processing on the returned image.

Node.js

npm install openai
# or
pnpm add openai

Step 2: Configure your API key

Never hard-code your API key. Use an environment variable.

Create a .env file:

OPENAI_API_KEY=sk-proj-your-key-here

Then load it in your code (Python uses python-dotenv, Node.js loads .env natively or with dotenv).

Step 3: Generate your first image

Python — minimal working example

import os
from openai import OpenAI
import base64

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

result = client.images.generate(
    model="gpt-image-2",
    prompt="A white stainless steel water bottle on a beige linen tablecloth, premium product photography, 1:1 aspect ratio.",
    size="1024x1024",
    quality="medium",
    n=1,
)

# Image is returned as base64
image_b64 = result.data[0].b64_json
with open("output.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

print("Saved to output.png")

Node.js — minimal working example

import OpenAI from 'openai';
import fs from 'fs';

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

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
    'A white stainless steel water bottle on a beige linen tablecloth, premium product photography, 1:1 aspect ratio.',
  size: '1024x1024',
  quality: 'medium',
  n: 1,
});

const imageB64 = result.data[0].b64_json;
fs.writeFileSync('output.png', Buffer.from(imageB64, 'base64'));
console.log('Saved to output.png');

Curl — for shell scripts and quick tests

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A white stainless steel water bottle on a beige linen tablecloth.",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'

All parameters explained

Image editing — the killer feature

GPT Image 2's directed editing is its biggest API advantage over diffusion models. You upload an existing image and a prompt describing what to change.

Python

result = client.images.edit(
    model="gpt-image-2",
    image=open("original.png", "rb"),
    prompt="Change the bottle's color from white to navy blue. Keep everything else identical.",
    size="1024x1024",
    quality="medium",
)

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

Node.js

import { toFile } from 'openai';

const result = await client.images.edit({
  model: 'gpt-image-2',
  image: await toFile(fs.createReadStream('original.png'), 'original.png'),
  prompt:
    "Change the bottle's color from white to navy blue. Keep everything else identical.",
  size: '1024x1024',
  quality: 'medium',
});

The phrase "Keep everything else identical" in the prompt is critical — without it, the model may regenerate unrelated regions.

Batch generation with rate-limit-safe concurrency

Don't naively Promise.all() 100 requests — you'll hit rate limits. Use bounded concurrency.

Python — using asyncio with a semaphore

import asyncio
from openai import AsyncOpenAI

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

async def generate_one(prompt: str, semaphore: asyncio.Semaphore):
    async with semaphore:
        result = await client.images.generate(
            model="gpt-image-2",
            prompt=prompt,
            size="1024x1024",
            quality="medium",
        )
        return result.data[0].b64_json

async def batch_generate(prompts: list[str], concurrency: int = 5):
    semaphore = asyncio.Semaphore(concurrency)
    tasks = [generate_one(p, semaphore) for p in prompts]
    return await asyncio.gather(*tasks)

results = asyncio.run(batch_generate(["prompt 1", "prompt 2", ...]))

Node.js — using p-limit

import pLimit from 'p-limit';

const limit = pLimit(5); // 5 concurrent requests

const tasks = prompts.map((prompt) =>
  limit(async () => {
    const result = await client.images.generate({
      model: 'gpt-image-2',
      prompt,
      size: '1024x1024',
      quality: 'medium',
    });
    return result.data[0].b64_json;
  })
);

const results = await Promise.all(tasks);

Error handling for production

The API can fail in several distinct ways. Handle each:

from openai import OpenAI, APIError, RateLimitError, APIConnectionError, BadRequestError

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

def safe_generate(prompt: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            result = client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="medium",
            )
            return result.data[0].b64_json

        except RateLimitError:
            # 429 — wait and retry
            wait = (2 ** attempt) * 5
            print(f"Rate limited; waiting {wait}s")
            time.sleep(wait)

        except BadRequestError as e:
            # 400 — usually a content policy violation, don't retry
            print(f"Bad request: {e}")
            return None

        except APIConnectionError:
            # network blip — retry
            time.sleep(2 ** attempt)

        except APIError as e:
            # 500-level — retry with backoff
            time.sleep(2 ** attempt)

    return None

Cost optimization — concrete tactics

1. Pick the right quality tier

Most teams overpay by defaulting to high. Use medium for ~95% of work.

2. Iterate with images.edit, not images.generate

A directed edit costs the same as a generation, but lands the right result in 1 try instead of 5. For multi-round refinement, this is 5× cost savings.

3. Cache deterministically when prompts repeat

If you generate the same prompt repeatedly (e.g., user-facing product previews), cache by hash(prompt + size + quality) and serve from your CDN.

4. Use low for prompt exploration, then upgrade

A common workflow:

# Step 1: try 5 prompt variants at low quality ($0.05 total)
candidates = [generate(p, quality="low") for p in variants]

# Step 2: pick the best, regenerate at high quality
best_prompt = pick_winner(candidates)
final = generate(best_prompt, quality="high")  # $0.167

Total cost: ~$0.22 instead of ~$0.84 if you'd run all 5 variants at high.

5. Set hard spending limits in the OpenAI dashboard

Don't trust your code to never bug — set a usage cap at platform.openai.com/account/billing/limits.

Streaming generation status (optional)

For long-running batches, you may want to surface progress. The image generation endpoint isn't streamed, but you can wrap your batch in async progress reporting:

let completed = 0;
const tasks = prompts.map((prompt) =>
  limit(async () => {
    const result = await client.images.generate({ /* ... */ });
    completed++;
    onProgress({ completed, total: prompts.length });
    return result.data[0].b64_json;
  })
);

Common integration mistakes

Production-ready checklist

Before shipping a GPT Image 2 integration:

• API key in environment variable, never in code or logs
• Quality tier appropriate for use case (default to medium)
• Bounded concurrency (p-limit / Semaphore) for batch jobs
• Error handling distinguishes 4xx vs 5xx
• Hard spending cap set in OpenAI dashboard
• User input sanitized for content policy violations
• Output stored on your own storage (not relying on OpenAI URLs)
• Cache layer for repeated prompts
• Monitoring on cost-per-image and error rate

Async generation with task polling (for high-concurrency setups)

For high-volume production workloads, some GPT Image 2 relays offer an async task model: you submit the request, get a task ID back immediately, and either poll for completion or receive a callback. This avoids HTTP timeouts on large batches.

Typical async flow:

# 1. Submit request → get task_id
response = client.images.generate(
    model="gpt-image-2",
    prompt="...",
    size="1024x1024",
    quality="high",
    callback_url="https://your-app.com/api/image-callback",  # optional
)
task_id = response.id

# 2. Poll task status every few seconds
while True:
    status = client.images.retrieve(task_id)
    if status.status == "completed":
        image_url = status.data[0].url
        break
    elif status.status == "failed":
        raise Exception(status.error)
    time.sleep(3)

Async mode is ideal for:

• E-commerce stores generating 100s of product variants overnight
• Marketing teams running A/B prompt tests
• Apps where users request images and check back later (notifications)

GPT Image 2 API FAQ

Q: What's the GPT Image 2 API model name? gpt-image-2. Use exactly this string for all requests.

Q: Does GPT Image 2 API support image-to-image / image editing? Yes. Use images.edit with the image parameter, or pass image_urls (array of 1-16 reference images) to relays that support it. Reference images are essential for character consistency, IP design, and product photography.

Q: Is GPT Image 2 API free? No, it is paid per token. New OpenAI accounts may receive trial credits. Some third-party relays offer free trial credits.

Q: How much does the GPT Image 2 API cost per image? Approximately $0.011 / $0.042 / $0.167 per 1024×1024 image at low / medium / high quality respectively. Larger sizes and reference images cost more.

Q: What's the maximum prompt length? Up to 32,000 characters. In practice, prompts above ~1,500 characters show diminishing returns.

Q: How do I generate transparent-background PNGs with the API? Set background: "transparent" and output_format: "png".

Q: What resolutions does GPT Image 2 support? Common presets: 1024x1024, 1536x1024, 1024x1536. Some relays expose 1K / 2K / 4K resolution levels for explicit control.

Q: What's the rate limit? Depends on your OpenAI tier. Free tier has the strictest limits; usage tier scales up over time. Use bounded concurrency (p-limit / Semaphore) to stay under the limit.

Q: How do I handle GPT Image 2 API errors? Distinguish 4xx (don't retry — usually content policy violations) from 5xx (retry with exponential backoff). See the error handling section above.

Q: Can I cancel an in-flight GPT Image 2 API request? For sync requests, only by closing the connection. Async-capable relays expose a cancel endpoint that works while the task is still queued.

Q: Does the API support streaming? Image generation itself is not streamed (you get the complete image at the end). For progress UI, wrap your batch in a custom progress reporter (see "Streaming generation status" above).

Want a working example app?

For a full reference implementation — Next.js + GPT Image 2 + Stripe + image storage — explore gpt-image2.art and the explore page showing real outputs.

Need a managed API key with SLA?

If you'd rather skip account setup, billing, region issues, and rate-limit tuning, you can purchase a managed GPT Image 2 API key by emailing support@gpt-image2.art. We provide:

• One stable API endpoint with built-in failover
• Aggregated billing in your local currency (no USD wire transfer required)
• Async task mode + callback support out of the box
• Volume pricing for teams generating > 10K images/month
• Same gpt-image-2 model name and parameter spec as the official API — drop-in compatible

Further reading

• GPT Image 2 Prompt Writing Guide — 7 Rules That Take Hit Rate From 30% to 90%
• GPT Image 2 Style Library — 12 Production-Ready Art Style Prompts
• What is GPT Image 2? A Complete Introduction