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

# GPT Image 2

> Generate one image from a prompt or uploaded reference images.

Use the public model ID `gpt-image-2` with `POST /images/generation`. Each new request creates a job for one image. You can generate from a prompt alone or provide up to 16 uploaded reference images.

## Create a job

Send an organization API key and a unique `Idempotency-Key`. Reuse the same key and request body when retrying the same job.

```bash theme={null}
export CREATOK_IDEMPOTENCY_KEY="$(uuidgen)"
curl https://api.creatok.ai/v1/images/generation \
  -H "Authorization: Bearer $CREATOK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CREATOK_IDEMPOTENCY_KEY" \
  -d '{
    "model": "gpt-image-2",
    "input": {
      "prompt": "A product photograph of a ceramic mug on a clean desk",
      "resolution": "2K",
      "quality": "low",
      "aspectRatio": "1:1"
    }
  }'
```

The API responds with HTTP `202` and a job. Read its `id` and `status`, then [poll the job](https://docs.creatok.ai/guides/jobs.md) until it reaches a final status. On success, download the image from `output.files`. Fetch the job again when you need a fresh signed URL.

## Input fields

| Field | Values | Default |
| - | - | - |
| `input.prompt` | 1–5,000 characters after trimming | Required |
| `input.resolution` | `1K`, `2K`, `4K` | `2K` |
| `input.quality` | `low`, `medium`, `high` | `low` |
| `input.aspectRatio` | `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `5:4`, `4:5`, `2:1`, `1:2`, `21:9`, `9:21` | `1:1` |
| `input.referenceImageKeys` | Up to 16 uploaded images | Empty array |

Unknown fields at the request root or inside `input` return `400 invalid_parameter`. The request supports optional `metadata` and `max_cost_usd` fields.

## Generate with reference images

[Upload each image](https://docs.creatok.ai/guides/files.md) before submitting the job. Pass its `file_id` or `upload_fields.key` in `referenceImageKeys`. Each reference must belong to your workspace, have an `image/*` content type, and be nonempty and no larger than 10 MiB. Do not send a public URL or base64 data.

```json theme={null}
{
  "model": "gpt-image-2",
  "input": {
    "prompt": "Place the mug in a bright kitchen",
    "referenceImageKeys": [
      "file_11111111-1111-4111-8111-111111111111"
    ]
  }
}
```

## Cost and retries

Check the current image rates on the [pricing page](https://www.creatok.ai/app/api-platform/pricing). The charge depends on `resolution`, `quality`, and the number of reference images. `cost.amount_usd` on the returned job shows the charge.

Set `max_cost_usd` to a decimal USD string with up to six decimal places to cap the charge. A quote above your cap returns `400 max_cost_exceeded` before charging. A failed or canceled job receives a refund, reported in `cost.refunded_usd`.

See [Idempotency](https://docs.creatok.ai/guides/idempotency.md) for safe retries and [Jobs and polling](https://docs.creatok.ai/guides/jobs.md) for output retention.


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