# GPT Image 2.5 Flare

GPT Image 2.5 tuned for fast, high quality everyday generation.

- Model ID: `openai/gpt-image-2.5-flare/text-to-image`
- Provider: OpenAI
- Modality: text → image
- Type: Text to Image
- Status: stable
- Delivery: async
- Max resolution: 4K
- Output format: png
- Aspect ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

## Authentication

Send your API key in the `X-API-Key` header.

The same key reads the org balance at `GET https://api.dev.pika.art/billing/balance`, which is free to call and confirms the request can be paid for before you submit it.

## Endpoint

```
POST https://api.dev.pika.art/v1/media/openai/gpt-image-2.5-flare/text-to-image
```

## Reference uploads

To use a local file (image, audio, or video) as a model input, first request a presigned upload URL: `POST /v1/media/uploads` with the `X-API-Key` header and a JSON body `{ "content_type": "image/png", "size_bytes": 12345 }`, where `size_bytes` is the file's exact byte length. The response returns `upload_url` (temporary, valid for 5 minutes), `headers`, and `url` (the permanent Pika URL). PUT the file bytes to `upload_url` sending the returned `headers` verbatim — both `Content-Type` and `Content-Length` are signed, and storage returns a bare 403 if either is missing or differs. Then pass `url` into fields such as `image`, `image_url`, `end_image_url`, `image_urls`, `first_frame_image`, or `mask_image_url`.

## Generate

`POST /v1/media/openai/gpt-image-2.5-flare/text-to-image`

```bash
curl -X POST https://api.dev.pika.art/v1/media/openai/gpt-image-2.5-flare/text-to-image \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "\nElevated fashion campaign advertisement photograph, 16:9. ONE SINGLE full-bleed photograph filling the\nentire frame — not a grid, not a collage, no panels.\nA classic red British telephone kiosk stands alone in the middle of a wide grass headland on a sea cliff,\nits door open. Several metres away, near the centre of the frame, one invented woman stands with her back\nto camera, facing out to sea, holding the handset to her ear; the coiled black cord runs taut all the way\nfrom inside the kiosk, across the grass, to her hand. She wears a long butter-yellow trench coat to the\nankle, simple and unbelted at the hem, her dark hair loosely pinned. Beyond her the sea fills the middle\nof the frame and a run of green-topped cliffs recedes into haze on the right, with a white line of surf\nat their base. Nothing else is on the headland.\nComposition: rule of thirds — the kiosk on the left third, the woman on the centre-right, the horizon\nhigh, a broad sweep of empty grass filling the foreground. Deep layering from foreground grass to distant\nheadland.\nColour: a large muted field of sea-green grass and pale grey-blue water and overcast sky, against the one\ndeep saturated pillar-box red of the kiosk. The butter-yellow coat is the single secondary note, warmer\nand softer than the red and smaller in area, so the pairing still reads first.\nLighting: soft, fully diffused overcast daylight as though through an enormous softbox — no visible sun,\nno hard shadows, no specular hotspots — but dimensional rather than flat, with a gentle key from the\nupper left, a soft luminous falloff across the grass and open shadows that keep their texture.\nGrade: natural and restrained. Low-to-moderate contrast, subtle fine grain, a slightly creamy finish,\ntexture held in the shadows, colour true. Soft but vibrant, never oversaturated, never dull or greyed.\nNo sharpening, no haloed edges.",
  "num_images": 1,
  "aspect_ratio": "16:9",
  "output_format": "png",
  "resolution": "1K",
  "quality": "medium"
}'
```

### Request body

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | yes | - | Text prompt describing the image to generate. |
| `num_images` | integer (1 – 10) | no | 1 | Number of images to generate. |
| `aspect_ratio` | enum | no | 1:1 | Output aspect ratio. Ignored when 'size' is set. |
| `output_format` | enum | no | png | Image file format of the output. |
| `resolution` | enum | no | 1K | Output resolution. |
| `background` | enum | no | - | Background of the output. 'transparent' needs a png or webp output_format. |
| `size` | string | no | - | Explicit output size as 'WxH' (e.g. '1024x1024'), or 'auto' to let the provider choose. Overrides aspect_ratio and resolution. |
| `quality` | enum | no | medium | Rendering quality of the output. |

#### Example body

```json
{
  "prompt": "\nElevated fashion campaign advertisement photograph, 16:9. ONE SINGLE full-bleed photograph filling the\nentire frame — not a grid, not a collage, no panels.\nA classic red British telephone kiosk stands alone in the middle of a wide grass headland on a sea cliff,\nits door open. Several metres away, near the centre of the frame, one invented woman stands with her back\nto camera, facing out to sea, holding the handset to her ear; the coiled black cord runs taut all the way\nfrom inside the kiosk, across the grass, to her hand. She wears a long butter-yellow trench coat to the\nankle, simple and unbelted at the hem, her dark hair loosely pinned. Beyond her the sea fills the middle\nof the frame and a run of green-topped cliffs recedes into haze on the right, with a white line of surf\nat their base. Nothing else is on the headland.\nComposition: rule of thirds — the kiosk on the left third, the woman on the centre-right, the horizon\nhigh, a broad sweep of empty grass filling the foreground. Deep layering from foreground grass to distant\nheadland.\nColour: a large muted field of sea-green grass and pale grey-blue water and overcast sky, against the one\ndeep saturated pillar-box red of the kiosk. The butter-yellow coat is the single secondary note, warmer\nand softer than the red and smaller in area, so the pairing still reads first.\nLighting: soft, fully diffused overcast daylight as though through an enormous softbox — no visible sun,\nno hard shadows, no specular hotspots — but dimensional rather than flat, with a gentle key from the\nupper left, a soft luminous falloff across the grass and open shadows that keep their texture.\nGrade: natural and restrained. Low-to-moderate contrast, subtle fine grain, a slightly creamy finish,\ntexture held in the shadows, colour true. Soft but vibrant, never oversaturated, never dull or greyed.\nNo sharpening, no haloed edges.",
  "num_images": 1,
  "aspect_ratio": "16:9",
  "output_format": "png",
  "resolution": "1K",
  "quality": "medium"
}
```

### Accepted values

| Param | Values | Default |
| --- | --- | --- |
| `aspect_ratio` | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | `1:1` |
| `output_format` | `png`, `jpeg`, `webp` | `png` |
| `resolution` | `1K`, `2K`, `4K` | `1K` |
| `background` | `auto`, `opaque`, `transparent` | — |
| `quality` | `low`, `medium`, `high`, `xhigh`, `max` | `medium` |

Returns a job object, not the final output — normally with status `queued`. Store the `id` and poll until a terminal state. A rejected submit (insufficient balance, rate limit, unpriceable input) still returns the job object, with status `failed` and `error` set. An `Idempotency-Key` replay returns the existing job in its current state — including `failed`, so retry a failure with a fresh key, never the same one.

### Response

**200 OK · queued**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "queued"
}
```

## Poll status

`GET /v1/media/jobs/{request_id}`

```bash
curl https://api.dev.pika.art/v1/media/jobs/{request_id} \
  -H "X-API-Key: YOUR_API_KEY"
```

Poll the job by id until it reaches a terminal state: `completed` or `failed`.

### The job object

- `id` (string): Unique identifier for the job.
- `status` (enum): One of `queued`, `running`, `completed`, `failed`.
- `output` (object): Present once the job completes.
  - `media_type` (enum): `image`.
  - `output.images[].url` (string): URLs of the generated images.
- `error` (object): Present if the job failed. `error.code` is the stable machine-readable value to branch on — one of `invalid_input`, `content_moderation`, `provider_error`, `provider_timeout`, `provider_unavailable`, `rate_limited`, `insufficient_balance`, `membership_required`, `cycle_limit_exceeded`, `admission_suspended`, `timed_out`, `internal`. Unrecognized values normalize to `provider_error`. `error.message` is diagnostic text and varies.
- `usage` (object): Units the provider reported for the job, such as `video_output_tokens`, `image_output_tokens`, `input_tokens`, or `output_seconds`. Present once the job is terminal, carries only the units the job reports, and is `null` when nothing was reported. It may not reproduce the charge, because some pricing components are fixed by the request; the charge is authoritative.
- `billing` (object): What the job charged. Present once the job is terminal, `null` on the submit response and on webhooks. `billing.state` is one of `settled`, `pending`, `unavailable`. `settled` carries `charge_micro_usd`, the amount collected in micro-USD (the balance's unit), `0` included. `pending` means the charge is still settling: retry at 1s, 2s, then 5s. `unavailable` means the billing read failed on Pika's side: retry no sooner than 30s. Record spend only when `state` is `settled`, keyed by job id; a `billing` of `null` is not a charge.

### Response

**200 OK · running**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "running"
}
```

**200 OK · completed**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "completed",
  "output": {
    "media_type": "image",
    "images": [
      {
        "url": "https://api.dev.pika.art/v1/files/img_8f3a2c91.png",
        "content_type": "image/png"
      }
    ]
  },
  "usage": {
    "image_output_tokens": 1568
  },
  "billing": {
    "state": "settled",
    "charge_micro_usd": 52000
  }
}
```

**200 OK · failed**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "failed",
  "error": {
    "code": "provider_error",
    "message": "upstream generation failed"
  },
  "billing": {
    "state": "settled",
    "charge_micro_usd": 0
  }
}
```

A completed job carries its download URL in `output`. `GET /v1/media/jobs/{request_id}/content` returns that same URL as `{ "url": "..." }` for clients that only kept the id; it answers `409` until the job completes.

## Errors

Errors use conventional HTTP status codes and always return JSON, in one of two shapes. Request-level errors (auth, unknown path, schema validation, idempotency conflict) are `{"message": "..."}`. Submit rejections that occur after the job row is created (insufficient balance, rate limit, unpriceable input, dispatch unavailable) return the full failed job envelope — branch on `error.code`, and retry with a fresh `Idempotency-Key`, since a failed job replays on its key.

- 401 Unauthorized — The API key is missing or invalid. Body: `{"message":"Invalid API key"}`
- 403 Forbidden — An inactive key is rejected with a `{"message"}` body. A submit that the org balance or postpaid cycle limit cannot cover is rejected after the job row exists and returns the failed job envelope. `GET /billing/balance` separates the two: a `200` means the key is active, so the rejection was the balance or the cycle limit. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"insufficient_balance","message":"Insufficient org balance"}}`
- 404 Not Found — No job with that id exists in your org, or the media path names an unknown vendor/model/function. Body: `{"message":"media job not found"}`
- 409 Conflict — The result was requested before the job completed, or an Idempotency-Key header was reused with a different body. Body: `{"message":"media job is not ready"}`
- 422 Unprocessable Entity — The request body failed validation: an invalid enum value, a missing required field, a wrong type, or malformed JSON. The JSON message names the offending field. A schema-valid parameter combination that cannot be priced instead fails after job creation and returns the failed job envelope with error code `invalid_input`. Body: `{"message":"duration: Input should be less than or equal to 15"}`
- 429 Too Many Requests — Org limit reached: requests per minute or day, or concurrent jobs. Returned as the failed job envelope; check the Retry-After header and retry with a fresh Idempotency-Key. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"rate_limited","message":"rate limit exceeded: rpm"}}`
- 503 Service Unavailable — The model rail or a backend dependency is temporarily unavailable. Returned as the failed job envelope; retry with backoff and a fresh Idempotency-Key. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"provider_unavailable","message":"media dispatch unavailable"}}`

## Pricing

- Image output: $30 per 1M tokens
- Input: $5 per 1M tokens

Only successful generations are charged.

Check the balance against this price before submitting: `GET https://api.dev.pika.art/billing/balance` returns `balance_micro_usd`, which is US dollars multiplied by 1,000,000, and `postpaid` when the org bills by invoice instead. For an active postpaid org, compare the price against `postpaid.cycle.remaining_micro_usd` rather than the prepaid balance. Report a shortfall to the user rather than submitting a request the balance cannot cover.

---

Model page: https://dev.pika.art/models/openai/gpt-image-2.5-flare/text-to-image
API index: https://dev.pika.art/llms.txt