GPT Image 2.5 API

Images API: Image Models

GPT Image 2.5 offers two documented models: gpt-image-2.5-sunburst is positioned for higher editing precision, while gpt-image-2.5-flare is positioned for everyday fast generation. The current documentation lists low, medium, high, xhigh, max, and auto quality levels, flexible custom sizes, and transparent PNG/WebP output. Verify each option against the live model schema.

Model selection and quality settings affect token usage. Before launch, check the actual usage field in each response instead of estimating per-image cost from the model name or unit price alone.

Images API: Generate Images

Generation requests use /v1/images/generations. The following Tokenra example uses gpt-image-2.5-flare to create a 1536×1024 PNG. The response returns the image as data[0].b64_json and includes output metadata plus token usage.

POST https://tokenra.io/v1/images/generations

{
  "model": "gpt-image-2.5-flare",
  "prompt": "Create a premium product poster for a transparent perfume bottle on wet black stone, with crisp studio lighting and elegant typography.",
  "n": 1,
  "size": "1536x1024",
  "quality": "auto",
  "output_format": "png",
  "moderation": "auto"
}

Send the request with your Tokenra API key in the Authorization header. Keep the key on the server or in an environment variable; never expose it in browser-side JavaScript.

curl -sS "https://tokenra.io/v1/images/generations" \\
  -H "Authorization: Bearer $Tokenra_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Create a premium product poster for a transparent perfume bottle on wet black stone, with crisp studio lighting and elegant typography.",
    "n": 1,
    "size": "1536x1024",
    "quality": "auto",
    "output_format": "png",
    "moderation": "auto"
  }'

Response shape

A successful response contains the base64 image in data[0].b64_json. The response also reports the selected background, output_format, quality, size, model, and a usage object.

{
  "created": 1788931908,
  "data": [{ "b64_json": "<base64 PNG data>" }],
  "background": "opaque",
  "output_format": "png",
  "quality": "low",
  "size": "1024x1536",
  "model": "gpt-image-2.5-flare",
  "usage": {
    "input_tokens": 29,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 29
    },
    "output_tokens": 343,
    "output_tokens_details": {
      "image_tokens": 343,
      "text_tokens": 0
    },
    "total_tokens": 372
  }
}

Use the returned usage values for cost accounting. The displayed response is an example shape; fields such as generated timestamp, size, quality, and token counts depend on the actual request and response.

Pricing and Usage

As of September 9, 2026, the two models have the same documented unit prices:

The same unit price does not mean the same cost per image. Models and quality levels can consume different numbers of tokens. For billing, prioritize the usage value in the response and measure your own prompt, size, and quality combinations.

Images API: 4K Images

gpt-image-2.5-sunburst supports flexible sizes, but 4K output should be interpreted within these constraints:

• 4K landscape: 3840x2160
• 4K portrait: 2160x3840
• The maximum edge must not exceed 3840.
• Both dimensions must be multiples of 16 pixels.
• The long-to-short edge ratio must not exceed 3:1.
• Total pixels must be between 655,360 and 8,294,400.

Outputs larger than 2560x1440 in total pixel dimensions fall into a high-resolution or experimental range. Start with low or medium quality to confirm composition, then switch to 4K and higher quality. In testing, both 3840x2160 and 2160x3840 generated successfully.

Images API: Edit Images

The editing endpoint is /v1/images/edits. Tokenra's compatible image-editing service uses multipart/form-data to pass the input image to gpt-image-2.5-sunburst for editing or reference-image generation.

Request requirements

• Send one image or repeated image[] fields, an optional mask, and a required prompt.
• PNG, JPEG, and WebP are supported.
• Up to 16 input images and one mask are supported.
• Each file can be up to 50 MiB, and the complete multipart request can be up to 128 MiB.

Do not mix in legacy parameters

Do not send the legacy response_format parameter. Also do not send stream, partial_images, or input_fidelity in direct Images editing requests. This avoids carrying parameters from older interfaces into the current multipart editing workflow.

Pre-Integration Checklist

1. Use low or medium quality first to validate the prompt, composition, and editing workflow.
2. Record actual token usage from the response before estimating costs.
3. For 4K output, check dimension multiples, pixel limits, and aspect-ratio constraints.
4. Use multipart/form-data for editing requests and enforce file-size and input-count limits.
5. Never hard-code an API key in production; use environment variables or server-side secret management.