API

GPT Image 2.5 API

Image

GPT Image 2.5 API brings OpenAI’s most advanced image generation and editing models to your application. Create images from text or refine reference images, with flexible aspect ratios and 1K, 2K, or 4K output. Choose flare for fast, high-quality everyday generation, or sunburst for demanding creative work and precise image editing.

Authorizations

Bearerstringheaderrequired

API key to authorize requests

Body

application/json

modelstringrequired

gpt-image-2-5

input.promptstringrequired

Describe the image you want to create, including the subject, composition, style, and lighting. For image editing, describe what to change and what to preserve in the reference images. Leading and trailing whitespace is trimmed.

input.modestringoptional

Select the GPT Image 2.5 variant. flare is the default and prioritizes speed for high-quality everyday generation and rapid iteration. sunburst prioritizes demanding quality requirements and editing precision, making it a good choice when accurate changes to reference images matter most.

Both modes support text-to-image and image editing. Omit input.images to generate from text, or provide reference images to edit. Keep the prompt, references, aspect ratio, and resolution the same when comparing modes.

Default: flare

flaresunburst

input.imagesstring[]optional

Optional reference image URLs. Use publicly accessible HTTPS URLs only. Omit for text-to-image.

input.aspect_ratiostringoptional

Output width-to-height ratio. auto lets the model choose a suitable composition. Choose a listed ratio to control the format, such as 1:1 for square images, 9:16 for portrait images, or 16:9 for landscape images.

Default: auto

auto1:12:33:23:44:39:1616:921:9

input.resolutionstringoptional

Output resolution tier. Use the lowercase values 1k, 2k, or 4k to select the corresponding tier. Set this field explicitly when you need a specific output resolution.

Default: 2k

1k2k4k

Request examples

POST /api/v1/create

curl -X POST https://nanobanana.io/api/v1/create \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2-5",
  "input": {
    "prompt": "A cinematic product photo of a futuristic banana-shaped camera"
  }
}'

POST /api/v1/create · HTTP 201

{
  "data": {
    "task_id": "task_example",
    "model": "gpt-image-2-5",
    "status": "processing",
    "credits": 5
  }
}

Poll this endpoint using the returned task ID until the task is completed or failed. We recommend polling every 5 seconds to check the latest task status.

POST /api/v1/check

{
  "task_id": "task_example"
}

Response

Task status returned by POST /api/v1/check. The IDs, URLs, and timestamps below are illustrative.

idstringrequired

Task identifier in data.id, matching the task_id used in the check request.

statusstringrequired

completed means generation succeeded and data.data contains the results. For other statuses, data.data is null.

failed_reasonstringoptional

Only returned when status is failed, to explain the failure. This field is omitted for completed and processing.

Completed · completed

The download URLs are in data.data.results.

POST /api/v1/check · HTTP 200

{
  "data": {
    "id": "task_example",
    "created_at": 1791244800,
    "model": "gpt-image-2-5",
    "status": "completed",
    "data": {
      "results": [
        "https://example.com/generated.png"
      ],
      "processing_time": 18
    }
  }
}

Other statuses

For processing or failed, data.data is null. This example shows failed: only failed includes failed_reason. Continue polling for processing; stop polling for failed.

POST /api/v1/check · HTTP 200

{
  "data": {
    "id": "task_example",
    "created_at": 1791244800,
    "model": "gpt-image-2-5",
    "status": "failed",
    "data": null,
    "failed_reason": "Generation failed."
  }
}

Credit usage

Credits consumed for a request generating one image.

Credits consumed for a request generating one image.
Resolution	1K	2K	4K
Single image	12	36	50

Optional parameters omitted: 5 credits

Set the listed input parameters explicitly to use the corresponding rate. Requests generating multiple images may consume more credits.

The credits field returned by POST /api/v1/create shows the amount charged for the task.