> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GPT Image 2.5 Sunburst API: Image Generation & Editing

> Generate and edit images with the GPT Image 2.5 Sunburst API through APIXO, featuring high-fidelity styling, five quality tiers, and async task delivery.

## Overview

GPT Image 2.5 Sunburst is an asynchronous image generation API for text-to-image and reference-guided image editing.

| Capability | Value |
| - | - |
| Model ID | `gpt-image-2.5-sunburst` |
| Modes | `text-to-image`, `image-to-image` |
| Prompt length | 1-32,000 characters |
| Reference images | 1-16 URLs for `image-to-image` |
| Mask editing | Optional `mask_url` for `image-to-image` |
| Aspect ratios | `auto`, `1:1`, `1:2`, `2:1`, `2:3`, `3:2`, `4:3`, `3:4`, `4:5`, `5:4`, `16:9`, `9:16`, `21:9` |
| Output control | `aspect_ratio` or `size` (supported ratio or custom `WIDTHxHEIGHT`) |
| Background | `auto`, `transparent`, `opaque` |
| Output format | `png`, `jpeg`, `webp` |
| Resolution tiers | `1k`, `2k`, `4k` |
| Quality tiers | `low`, `medium`, `high`, `xhigh`, `max` |

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint | Purpose |
| - | - | - |
| `POST` | `/generateTask/gpt-image-2.5-sunburst` | Submit a generation task |
| `GET` | `/statusTask/gpt-image-2.5-sunburst?taskId={taskId}` | Poll task status and retrieve results |

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Quickstart

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/gpt-image-2.5-sunburst" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-image",
      "prompt": "A cinematic aerial view of a futuristic coastal city at sunrise, warm golden light, detailed architecture, realistic clouds and ocean, no text or watermark",
      "aspect_ratio": "16:9",
      "resolution": "4k",
      "quality": "max"
    }
  }'
```

The accepted response includes `data.taskId`. Save it and poll until `state` becomes `success` or `failed`.

## Request body

### Text-to-image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "A cinematic travel poster of mountains, a lake, and a cabin at sunrise, rich natural colors, no text",
    "aspect_ratio": "3:2",
    "resolution": "2k",
    "quality": "high"
  }
}
```

### Image-to-image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "image-to-image",
    "prompt": "Turn the supplied portrait into a refined editorial fashion photograph. Preserve the person's identity and pose, natural skin texture, beige studio backdrop, soft directional light.",
    "image_urls": [
      "https://your-domain.com/images/portrait-source.jpg"
    ],
    "mask_url": "https://your-domain.com/images/portrait-mask.png",
    "aspect_ratio": "4:5",
    "background": "opaque",
    "output_format": "png",
    "resolution": "2k",
    "quality": "max"
  }
}
```

## Parameters

**request\_type** `string` *required* (default: async)

Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.

**callback\_url** `string`

Required when `request_type` is `callback`. It must be a public HTTPS URL that can receive the final task payload. See [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md).

**input** `object` *required*

GPT Image 2.5 Sunburst input parameters.

**properties**

**mode** `string` *required*

Generation mode. Supported values: `text-to-image`, `image-to-image`.

**prompt** `string` *required*

Text prompt describing the requested image or edit. Supports 1-32,000 characters.

**image\_urls** `string[]`

Publicly accessible reference image URLs. Required for `image-to-image`; supports 1-16 URLs.

**aspect\_ratio** `string` (default: auto)

Output aspect ratio. Supported values: `auto`, `1:1`, `1:2`, `2:1`, `2:3`, `3:2`, `4:3`, `3:4`, `4:5`, `5:4`, `16:9`, `9:16`, `21:9`. `1:2` and `2:1` require `resolution` to be `2k` or `4k`. Ignored when `size` is supplied.

**size** `string`

Optional output size. Use a supported aspect ratio or custom `WIDTHxHEIGHT`, such as `1536x1024`. It takes priority over `aspect_ratio`. Custom `WIDTHxHEIGHT`, `1:2`, and `2:1` require `resolution` to be `2k` or `4k`.

**resolution** `string` (default: 1k)

Output resolution tier. Supported values: `1k`, `2k`, `4k`.

**quality** `string` (default: medium)

Quality and billing tier. Supported values: `low`, `medium`, `high`, `xhigh`, `max`. Each tier has its own listed price.

**background** `string` (default: auto)

Output background. Supported values: `auto`, `transparent`, `opaque`. When using `transparent`, set `output_format` to `png` or `webp`.

**output\_format** `string` (default: png)

Output image format. Supported values: `png`, `jpeg`, `webp`. `jpeg` cannot be used with `background=transparent`.

**mask\_url** `string`

Optional public HTTP(S) mask image URL. Available only for `image-to-image` and requires `image_urls`.

## Poll for results

```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/gpt-image-2.5-sunburst?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

When successful, `data.resultJson` is a JSON string containing `resultUrls`:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/xxx.png\"]}",
    "createTime": 1767965610929,
    "completeTime": 1767965652317,
    "costTime": 41388
  }
}
```

For failed tasks, `state` is `failed` and the response includes `failCode` and `failMsg`.

## Billing

New non-LLM requests use **1 credit = `$0.001`**. Calculate the full amount, including billable quantity and add-ons, apply the applicable account discount, then round the request total upward to the next whole credit. Agreed fixed unit prices retain their precision and replace the standard price and discount; final rounding still applies. See [credit conversion and rounding](https://apixo.ai/docs/pricing.md#credit-conversion-and-rounding).

Billing is per successfully generated image. Standard unit prices below are in USD with up to three decimal places. Text-to-image and image-to-image use the same output-tier price; reference images do not add an extra charge.

| Quality | `1k` | `2k` | `4k` |
| - | -: | -: | -: |
| `low` | `$0.010` | `$0.020` | `$0.030` |
| `medium` | `$0.024` | `$0.040` | `$0.070` |
| `high` | `$0.090` | `$0.150` | `$0.270` |
| `xhigh` | `$0.160` | `$0.270` | `$0.480` |
| `max` | `$0.360` | `$0.600` | `$1.000` |

For the live price catalog, see [API pricing](https://apixo.ai/pricing/api).

## Latency and polling

Generation time depends on prompt complexity, reference images, selected resolution, and current queue load. Start polling after 30-60 seconds, then poll every 10 seconds. For production workloads, prefer callback mode.

## MCP integration

The [complete model schema](https://apixo.ai/docs/models/schemas/image/gpt-image-2-5-sunburst.json) declares result decoding in `mcp.result` and supported file bindings in `mcp.attachments`. These are client integration metadata, not generation input parameters. Attachment paths: `image_urls`, `mask_url`. Preserve the user's file order. Model parameter validation remains on the API.

## Related links

* [Image Models](https://apixo.ai/docs/models/image)
* [Generation API Overview](https://apixo.ai/docs/models.md)
* [Generate Task](https://apixo.ai/docs/api-reference/generate-task.md)
* [Status Task](https://apixo.ai/docs/api-reference/status-task.md)
* [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md)
* [API pricing](https://apixo.ai/pricing/api)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.