gpt-image-2 API

Generate high-quality images from text prompts or edit existing images with references. The same generation engine that powers the in-app Studio, exposed for programmatic access.

What you can build

• Text-to-image — generate an image from a natural-language prompt
• Image-to-image — supply up to 4 reference images and let the prompt guide the edit or restyle

A typical generation takes 45–60 seconds end-to-end. Tasks are asynchronous: submit once, then poll until done.

Base URL

All requests go to:

https://gptimg.co

Endpoints are versioned under /api/v1/images.

Authentication

Every request must carry a Bearer token in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

Getting an API key

1. Sign in to your account
2. Open Settings → API Keys — go there now →
3. Click Create API Key, give it a name, and copy the generated key

Keys are shown only once at creation. Store them in a secret manager; they cannot be retrieved later. You can revoke a key at any time from the same page.

Security notes

• Always use HTTPS. Requests over HTTP are rejected in production.
• Never put the key in a query string. The server rejects any request that exposes ?api_key=..., ?apikey=..., ?key=..., ?token=..., or ?access_token=..., because CDN / proxy logs may already have captured the value. Rotate such a key immediately.
• Never commit keys to git. Use environment variables.
• Keys are user-scoped. An API key inherits the credit balance and data isolation of the owning user. One user's keys cannot access another user's tasks. API keys also cannot read tasks that the same user created through the web Studio — the two surfaces are kept separate.

Credit pricing

Total charge = 2 × n, where n is the number of images you request (1–4).

Credits are deducted atomically at submission time. If the task later fails, the full charge is refunded automatically — credits_refunded in the transaction log will equal the original charge.

If your balance is below the required amount, the request returns 402 INSUFFICIENT_CREDITS. Top up from the Credits page in the dashboard.

Quickstart

A complete end-to-end example. Replace <YOUR_API_KEY> with your real key.

1. Submit a task

curl -X POST https://gptimg.co/api/v1/images/generate \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A small red apple on a white marble table, studio photograph, soft daylight",
    "aspect_ratio": "1:1",
    "n": 1
  }'

Response (HTTP 200):

{
  "success": true,
  "data": {
    "id": "kUtpnus8fXpDKkuEjayG3",
    "task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
    "status": "processing",
    "provider": "gpt-image-2",
    "model": "gpt-image-2",
    "type": "text-to-image",
    "media_url": null,
    "images": [],
    "created_at": "2026-04-22T00:12:03.456Z"
  }
}

Take note of data.task_id — that's what you'll poll with.

2. Poll for completion

Poll every 5–10 seconds until status transitions to completed or failed.

curl https://gptimg.co/api/v1/images/task/gpt-image-2-kUtpnus8fXpDKkuEjayG3 \
  -H "Authorization: Bearer <YOUR_API_KEY>"

3. Receive the result

When status is completed, the response contains the hosted image URL(s):

{
  "success": true,
  "data": {
    "id": "kUtpnus8fXpDKkuEjayG3",
    "task_id": "gpt-image-2-kUtpnus8fXpDKkuEjayG3",
    "status": "completed",
    "provider": "gpt-image-2",
    "model": "gpt-image-2",
    "type": "text-to-image",
    "media_url": "https://file.gptimg.co/gpt-image-2-outputs/f063a662-1860-4a51-bd9b-ffe75a5336a5.png",
    "images": [
      {
        "url": "https://file.gptimg.co/gpt-image-2-outputs/f063a662-1860-4a51-bd9b-ffe75a5336a5.png",
        "content_type": "image/png"
      }
    ],
    "error": null,
    "created_at": "2026-04-22T00:12:03.456Z",
    "updated_at": "2026-04-22T00:13:02.789Z"
  }
}

Image URLs are hosted on our R2 CDN and are stable — feel free to hot-link, but for production you should mirror them to your own storage so you control uptime.

Next steps

• POST /api/v1/images/generate — full request reference
• GET /api/v1/images/task/{id} — check status and retrieve results
• Errors — error code reference