# GPT Image 2.5 API

> OpenAI's fast everyday image model — generation and editing from text, with selectable aspect ratio and resolution up to 4K.

- **Provider**: OpenAI
- **Model id**: `gpt-image-2-5-flare-text-to-image`
- **Modality**: image
- **Price**: 2.7–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-flare-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-flare-text-to-image",
  "input": {
    "prompt": "Create a realistic photo in the style of Asian cinema, featuring a raw, desaturated tone with shades of grey, green, and muted hues.\n\nA middle-aged Asian man with a lean build; his face shows slight wrinkles, and he has messy, unkempt long hair and light stubble. His expression is calm and stoic, yet hints at a dangerous nature.\n\nHe wears a kimono in a muted white with a cherry blossom pattern; the garment underneath features a traditional print and looks worn, showing signs of actual use.\n\nHe holds a katana casually—not in a formal stance—yet his demeanor naturally exudes danger.\n\nA cigarette hangs from his lips, with smoke swirling around him; the smoke is realistic—varying in density—and drifts through the light, adding depth to the image.\n\nThe background is a courtyard with blurred figures that do not distract from the subject; natural light streams in from the side or back.\n\nCamera angle is chest-to-waist level, focusing on the main character with a shallow depth of field, causing the background to blur slightly.\n\nCinematic lighting—natural and ambient rather than staged or flash-based. Soft shadows and muted colors create a movie-scene look rather than a studio photograph.\n\nThe overall mood is cool, composed, tense, and realistic—capturing a fleeting moment of a dangerous individual in the real world. No fantasy elements or special effects.\n\n⸻\n\nNEGATIVE PROMPT (Crucial—use as is)\n\nCGI, 3D render, digital art, illustration, fantasy, anime, cartoon, unreal engine, concept art, studio lighting, beauty lighting, smooth skin, plastic skin, over sharp, over contrast, dramatic fantasy light, glow, magical effect",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }
}
```

### Response example

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

## Query Task

`GET https://you.bot/api/v1/task/{taskId}?model=gpt-image-2-5-flare-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 |