> ## 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
> OpenAI image generation API for text-to-image and image-to-image workflows
## Overview
GPT Image 2 is an OpenAI image model for text-to-image generation and reference-guided image editing. Use this page when you are ready to call the API after trying the model in the APIXO playground.
| Capability | Value |
| ---------------- | --------------------------------------------------------------------------------------------- |
| Model ID | `gpt-image-2` |
| Modes | `text-to-image`, `image-to-image` |
| Prompt length | 1-20000 characters |
| Reference images | 1-16 URLs 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` |
| Size formats | Supported ratio values or custom `WIDTHxHEIGHT` |
| Resolution tiers | `1k`, `2k`, `4k` |
| Quality levels | `low`, `medium`, `high` |
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | ----------------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/gpt-image-2` | Submit a generation task |
| `GET` | `/statusTask/gpt-image-2?taskId={taskId}` | Poll task status and retrieve results |
All requests require your APIXO API key:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
Submit requests also require:
```http theme={null}
Content-Type: application/json
```
## Copy-paste async quickstart
This minimal request submits a text-to-image task and returns a `taskId`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/gpt-image-2" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "text-to-image",
"prompt": "a futuristic city skyline at dusk",
"size": "21:9",
"resolution": "2k",
"quality": "high"
}
}'
```
Successful response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678"
}
}
```
Save the `taskId`; you need it to poll for the final result.
## Poll for result
```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/gpt-image-2?taskId=task_12345678" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Processing response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "processing",
"createTime": 1767965610929
}
}
```
Success response:
```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
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "CONTENT_VIOLATION",
"failMsg": "Content does not meet safety guidelines",
"createTime": 1767965610929,
"completeTime": 1767965620132
}
}
```
Parse `resultJson` after `state` becomes `success`:
```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;
```
## Request body
### Text-to-image
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "text-to-image",
"prompt": "a fox in watercolor style",
"aspect_ratio": "16:9",
"size": "16:9",
"resolution": "2k",
"quality": "high"
}
}
```
### Image-to-image
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "image-to-image",
"prompt": "turn this photo into an oil painting",
"image_urls": [
"https://example.com/source.png"
],
"size": "3840x2160",
"resolution": "4k"
}
}
```
## Parameters
Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks).
GPT Image 2 input parameters.
Generation mode. Supported values: `text-to-image`, `image-to-image`.
Text prompt describing the desired image or edit. Supports 1-20000 characters.
Reference image URLs. Required for `image-to-image`. Supports 1-16 URLs.
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`.
Optional output size. Supports the same ratio values as `aspect_ratio`, or custom `WIDTHxHEIGHT` such as `2304x1536`.
Output resolution tier. Supported values: `1k`, `2k`, `4k`. When `4k` is requested, only `16:9`, `9:16`, `21:9`, `1:2`, `2:1`, or custom `WIDTHxHEIGHT` with one edge equal to `3840` will keep `4k`; other supported ratios or custom sizes will be processed as `2k`.
Optional quality level. Supported values: `low`, `medium`, `high`.
## Response format
### Submit task response
`POST /generateTask/gpt-image-2` returns a task ID when the task is accepted:
API status code. `200` means the task was accepted.
Human-readable status message.
Unique task identifier used with the status endpoint.
### Status response fields
Unique task identifier.
Current task state: `pending`, `processing`, `success`, or `failed`.
JSON string containing the generated image URLs. Present when `state` is `success`.
Machine-readable failure code. Present when `state` is `failed`.
Human-readable failure message. Present when `state` is `failed`.
Task creation timestamp in Unix milliseconds.
Task completion timestamp in Unix milliseconds. Present after completion.
Processing duration in milliseconds. Present after successful completion.
## Webhook callback mode
Use callback mode when your backend should receive the final result automatically instead of polling.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/gpt-image-2" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "callback",
"callback_url": "https://your-server.com/webhooks/apixo",
"input": {
"mode": "text-to-image",
"prompt": "a clean product photo of wireless earbuds on soft stone",
"aspect_ratio": "1:1",
"resolution": "2k",
"quality": "medium"
}
}'
```
See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
GPT Image 2 is billed per generated image. The selected `quality` and billed `resolution` determine the unit price.
| Params | APIXO price |
| ------------------------------- | ----------- |
| `quality=low, resolution=1k` | `0.0300` |
| `quality=low, resolution=2k` | `0.0400` |
| `quality=low, resolution=4k` | `0.0550` |
| `quality=medium, resolution=1k` | `0.0424` |
| `quality=medium, resolution=2k` | `0.0448` |
| `quality=medium, resolution=4k` | `0.0808` |
| `quality=high, resolution=1k` | `0.1688` |
| `quality=high, resolution=2k` | `0.1776` |
| `quality=high, resolution=4k` | `0.3208` |
For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Actual latency may vary by prompt complexity, provider route, and current queue load.
| Resolution | Typical generation time | Recommended first poll | Poll interval |
| ---------- | ----------------------- | ------------------------ | ------------- |
| `1k` | 30s-120s | 30s after task creation | 10s |
| `2k` | 60s-180s | 60s after task creation | 10s |
| `4k` | 120s-240s | 120s after task creation | 10s |
For high-concurrency production workloads, use callback mode to avoid frequent polling.
## Size rules
* `size` can be either a supported ratio value or a custom `WIDTHxHEIGHT`.
* Supported ratio values are the same as `aspect_ratio`: `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`.
* When both `size` and `aspect_ratio` are provided, `size` takes precedence.
* `1:2` and `2:1` are supported.
* When `resolution=4k`, only `16:9`, `9:16`, `21:9`, `1:2`, `2:1`, or custom `WIDTHxHEIGHT` with one edge equal to `3840` will keep `4k`.
* When `resolution=4k` is used with other supported ratios, or with custom `WIDTHxHEIGHT` whose two edges are both not `3840`, the task will be processed as `2k`.
* Custom `WIDTHxHEIGHT` requires both dimensions to be divisible by `16`.
* Custom `WIDTHxHEIGHT` cannot exceed `3840` pixels on either edge.
* Custom `WIDTHxHEIGHT` total pixels must stay between `655360` and `8294400`.
* Custom `WIDTHxHEIGHT` aspect ratio cannot exceed `3:1`.
* Custom `WIDTHxHEIGHT` requires `resolution` to be `2k` or `4k`.
Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/docs/api-reference/system).
## Errors and troubleshooting
### HTTP errors
| Code | Meaning | What to do |
| ----- | --------------------------------------------------------- | ------------------------------------------------ |
| `400` | Invalid request body, mode, parameter, or image URL shape | Fix the request before retrying |
| `401` | Missing or invalid API key | Check the `Authorization` header |
| `402` | Insufficient balance or quota | Add balance or switch account/key |
| `403` | Key or route cannot access the model | Check permissions and route strategy |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error | Retry with backoff |
| `502` | Upstream provider error | Retry with backoff |
| `504` | Upstream timeout | Retry or use callback mode for long-running jobs |
### Task failure codes
| Fail code | Meaning | What to do |
| ---------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
| `CONTENT_VIOLATION` | Prompt or reference image failed safety checks | Change the prompt or input image |
| `INVALID_IMAGE_URL` | A reference image URL could not be fetched or decoded | Use a public, direct image URL |
| `INVALID_PARAMETER` | A model parameter is unsupported or malformed | Check `mode`, `aspect_ratio`, `resolution`, and `image_urls` |
| `INSUFFICIENT_BALANCE` | The account does not have enough balance for the task | Add balance before retrying |
| `UPSTREAM_ERROR` | Provider-side failure | Retry with backoff or try another route |
| `TIMEOUT` | Generation did not finish in time | Retry, reduce input complexity, or use callback mode |
See [Error Codes](/docs/api-reference/errors) for the full error reference.
## Related links
* [Generation API Overview](/docs/models)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Error Codes](/docs/api-reference/errors)
* [Parameter Specification](/docs/api-reference/parameters)
* [Routing Strategies](/docs/concepts/routing-strategies)
* [Pricing](https://apixo.ai/pricing)