# GPT Image 2.5

> OpenAI image generation and editing with high-fidelity reference images, precise inpainting, multi-turn consistency, and transparent backgrounds. Explore Flare and Sunburst and compare GPT Image 2.5 with GPT Image 2 on PoYo.

## Overview

- Submit: `https://api.poyo.ai/api/generate/submit`
- Status: `https://api.poyo.ai/api/generate/status/{task_id}`
- Page: https://poyo.ai/models/gpt-image-2-5
- Model page ID: `gpt-image-2-5`
- API model IDs: `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-fixed`
- Category: Image
- Auth: `Authorization: Bearer $POYO_API_KEY`
- Create a key at https://poyo.ai/dashboard/api-key

This model uses PoYo's unified async API. POST the JSON body below, then poll status with the returned `task_id` or receive a webhook on `callback_url`. Failed tasks are not charged.

## Pricing

- Text input: 800 credits ($4.00) per 1M tokens
- Image input: 1280 credits ($6.40) per 1M tokens
- Image output: 4800 credits ($24.00) per 1M tokens
- Fixed - 1K: 1.7 credits ($0.0085) per image
- Fixed - 2K: 6 credits ($0.030) per image
- Fixed - 4K: 8 credits ($0.040) per image

For more details, see https://poyo.ai/models/gpt-image-2-5.

## API Information

The request envelope is always `{ model, input, callback_url? }`. Input fields below are nested under `input`.

### Request envelope

- `model` (`ModelEnum`, required):
  GPT Image 2.5 Flare model identifier.
  - Options: `"gpt-image-2.5-flare"`
- `callback_url` (`string`, optional):
  Optional webhook URL for task completion or failure.

### Input Schema

Generate one image, or edit reference images when image_urls is non-empty.

The API accepts the following `input` parameters:

- `prompt` (`string`, required):
  Prompt describing the image or the requested edit. Must contain non-whitespace text.
  - Length: 1 to 32000 characters
- `image_urls` (`list`, optional):
  Optional reference image URLs. A non-empty array selects editing; an omitted or empty array selects text-to-image generation. Must be a publicly accessible HTTP or HTTPS URL.
  - Array of string
  - Length: 0 to 16
- `size` (`string`, optional):
  Aspect ratio or custom WIDTHxHEIGHT. Supported values: auto, 1:1, 2:3, 3:2, 4:3, 3:4, 4:5, 5:4, 16:9, 9:16, 21:9, or WIDTHxHEIGHT. Defaults to 1:1. auto is available only at 1K. Custom sizes require resolution 2K or 4K, dimensions divisible by 16, max edge 3840, aspect ratio at most 3:1, and total pixels 655360–8294400. A custom 3840-pixel edge requires 4K.
  - Default: `"1:1"`
  - Examples: "1:1"
- `resolution` (`ResolutionEnum`, optional):
  Output resolution tier. For aspect ratios, actual pixel dimensions may vary by model and generation; inspect the returned image for exact dimensions. Custom WIDTHxHEIGHT specifies exact dimensions.
  - Default: `"1K"`
  - Options: `"1K"`, `"2K"`, `"4K"`
- `quality` (`QualityEnum`, optional):
  Output quality level.
  - Default: `"high"`
  - Options: `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`
- `background` (`BackgroundEnum`, optional):
  Background mode. transparent requires png or webp output.
  - Default: `"auto"`
  - Options: `"auto"`, `"transparent"`, `"opaque"`
- `output_format` (`OutputFormatEnum`, optional):
  Output image format.
  - Default: `"png"`
  - Options: `"png"`, `"jpeg"`, `"webp"`
- `mask_url` (`string`, optional):
  Optional mask image URL identifying the area to edit. Requires non-empty image_urls. Must be a publicly accessible HTTP or HTTPS URL.

Required Parameters Example:

```json
{
  "model": "gpt-image-2.5-flare",
  "input": {
    "prompt": "A premium product photo of a silver espresso machine in a bright studio",
    "size": "16:9",
    "resolution": "2K",
    "quality": "medium"
  }
}
```

Full Example:

```json
{
  "model": "gpt-image-2.5-flare",
  "input": {
    "prompt": "A premium product photo of a silver espresso machine in a bright studio",
    "size": "16:9",
    "resolution": "2K",
    "quality": "medium",
    "background": "auto",
    "output_format": "png"
  }
}
```

Image Edit:

```json
{
  "model": "gpt-image-2.5-flare",
  "input": {
    "prompt": "Keep the product and replace the background with a warm modern studio",
    "image_urls": [
      "https://example.com/product.png"
    ],
    "size": "1:1",
    "quality": "high"
  }
}
```

Mask Edit:

```json
{
  "model": "gpt-image-2.5-flare",
  "input": {
    "prompt": "Replace only the masked area with a small vase of flowers",
    "image_urls": [
      "https://example.com/room.png"
    ],
    "mask_url": "https://example.com/mask.png",
    "size": "auto"
  }
}
```

### Output Schema

Submit returns a `task_id`. Poll `GET /api/generate/status/{task_id}` until `status` is `finished` or `failed`. Completed media is in `data.files`.

Response fields:

- `code` (`CodeEnum`, required):
  Business status code. `200` means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with `code: 400` in the body.
  
  - `200`: Success
  - `400`: Invalid request parameters
  - `401`: Missing or invalid API key
  - `402`: Insufficient credits
  - `403`: Permission denied
  - `404`: Resource not found
  - `408`: Request timeout
  - `429`: Rate limit exceeded
  - `500`: Internal server error
  - `502`: Upstream service error
  - `503`: Service unavailable
  
  See [Error Codes](/api-manual/error-codes) for details.
  - Options: `200`, `400`, `401`, `402`, `403`, `404`, `408`, `429`, `500`, `502`, `503`
  - Examples: `200`
- `data` (`object`, required):

Example Response:

```json
{
  "code": 200,
  "data": {
    "task_id": "task_example",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.poyo.ai/models/gpt-image-2-5/examples/polar-rescue-output-95ce526b796b.png",
        "file_type": "image"
      }
    ]
  }
}
```

## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"gpt-image-2.5-flare","input":{"prompt":"A premium product photo of a silver espresso machine in a bright studio","size":"16:9","resolution":"2K","quality":"medium"}}'
```

### Python

```python
import json
import os
import time
import requests

API = "https://api.poyo.ai"
headers = {
    "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
    "Content-Type": "application/json",
}
payload = json.loads("{\n  \"model\": \"gpt-image-2.5-flare\",\n  \"input\": {\n    \"prompt\": \"A premium product photo of a silver espresso machine in a bright studio\",\n    \"size\": \"16:9\",\n    \"resolution\": \"2K\",\n    \"quality\": \"medium\"\n  }\n}")

submit = requests.post(f"{API}/api/generate/submit", headers=headers, json=payload)
submit.raise_for_status()
task_id = submit.json()["data"]["task_id"]

while True:
    status = requests.get(f"{API}/api/generate/status/{task_id}", headers=headers)
    status.raise_for_status()
    data = status.json()["data"]
    if data["status"] in ("finished", "failed"):
        print(data)
        break
    time.sleep(2)
```

### JavaScript

```javascript
const headers = {
  Authorization: `Bearer ${process.env.POYO_API_KEY}`,
  "Content-Type": "application/json",
};

const submit = await fetch("https://api.poyo.ai/api/generate/submit", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "gpt-image-2.5-flare",
  "input": {
    "prompt": "A premium product photo of a silver espresso machine in a bright studio",
    "size": "16:9",
    "resolution": "2K",
    "quality": "medium"
  }
}),
});

const submitted = await submit.json();
const taskId = submitted.data.task_id;

while (true) {
  const statusResponse = await fetch(`https://api.poyo.ai/api/generate/status/${taskId}`, { headers });
  const status = await statusResponse.json();
  if (["finished", "failed"].includes(status.data.status)) {
    console.log(status.data);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 2000));
}
```

## Additional Resources

### Documentation

- [Model Playground](https://poyo.ai/models/gpt-image-2-5)
- [API Documentation](https://docs.poyo.ai/api-manual/image-series/gpt-image-2-5-flare)
- [API Documentation (Markdown)](https://docs.poyo.ai/api-manual/image-series/gpt-image-2-5-flare.md)
- [Task status](https://docs.poyo.ai/api-manual/task-management/query-task-status)
- [Webhooks](https://docs.poyo.ai/api-manual/task-management/webhooks)

### Other agent-readable surfaces

- [Platform overview](https://poyo.ai/llms.txt)
- [Documentation index](https://docs.poyo.ai/llms.txt)
- [Full documentation text](https://docs.poyo.ai/llms-full.txt)
- Any other model: `https://poyo.ai/models/<model-id>/llms.txt`