# GPT Image 2.5 API

> OpenAI's most capable image model — for work where editing precision matters most, up to 4K.

- **Provider**: OpenAI
- **Model id**: `gpt-image-2-5-sunburst-text-to-image`
- **Modality**: image
- **Price**: 2.9–7.2 credits

## Overview

GPT Image 2.5 is called in two steps: create a generation task, then poll the task until the result is ready.

## Authentication

All requests require a Bearer Token in the request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Create Task

`POST https://you.bot/api/v1/generate`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| modelId | string | Yes | Model id: `gpt-image-2-5-sunburst-text-to-image` |
| input | object | Yes | Input parameters object (see below) |
| callbackUrl | string | No | https URL we POST the finished task to. Signed with `X-Webhook-Signature` once you create a webhook signing key in Dashboard → Settings |

### input object parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string | Yes | Text value |
| aspect_ratio | string | Yes | Options: 1:1 \| 3:2 \| 2:3 \| 4:3 \| 3:4 \| 16:9 \| 9:16 \| 2:1 \| 1:2 \| 21:9 (default: 1:1) |
| resolution | string | No | Options: 1K \| 2K \| 4K (default: 1K) |

### Request example

```json
{
  "modelId": "gpt-image-2-5-sunburst-text-to-image",
  "input": {
    "prompt": "This contemporary art masterpiece depicts a mysterious woman standing in a field of glowing flowers at night. She wears a black, art-style outfit that contrasts sharply with the vibrant backdrop. Her face is serene, her eyes deep and piercing, surrounded by neon butterflies and flower petals floating in the air. The backdrop features a gigantic moon in shades of pinkish-orange against an electric blue, deep purple, and turquoise sky, creating a striking color contrast. The composition is balanced, reminiscent of modern poster art, with a clean, uncluttered space.\nDetails of only key specific points; lighting style cinematic glow, vibrant color harmony, bold contrast, surreal dreamscape, luxury art print, iconic composition, elegant negative space, ultra refined brushwork, artistic masterpiece, gallery quality, visually unforgettable, eye-catching from a distance, rich saturation, high-end contemporary art, unique visual identity, premium aesthetic, award-winning artwork, sharp focal point, depth and atmosphere, 8K\n\nNegative Prompt \n\ncluttered composition, excessive details, low contrast, dull colors, oversharpen, bad anatomy, extra fingers, text, watermark, logo, blurry, noisy, flat lighting, cheap CGI, amateur artwork, messy background, overdecorated scene",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }
}
```

### Response example

```json
{
  "taskId": "281e5b0…f39b9",
  "creditsCharged": 2.9
}
```

## Query Task

`GET https://you.bot/api/v1/task/{taskId}?model=gpt-image-2-5-sunburst-text-to-image`

When `state` is `success`, the output is in `resultUrls`: `{ "state": "success", "resultUrls": [ ... ] }`. (Text models return inline in the create response.)

## Error Codes

| Code | Description |
|------|-------------|
| 200 | Request successful |
| 400 | Invalid request parameters |
| 401 | Authentication failed — check API Key |
| 402 | Insufficient account balance |
| 403 | IP not allowed for this key, or the key is restricted to other models |
| 404 | Task not found, or it has expired |
| 409 | Duplicate request — an identical submit arrived moments ago. Nothing was charged; retry is safe |
| 413 | Payload too large — see the character and file-size limits for this model |
| 429 | Rate limit exceeded — retry after the Retry-After header |
| 500 | Internal server error |
| 504 | Upstream timed out — nothing was delivered; retry is safe |