# GPT Image 2

Generate and edit images with GPT Image 2, including asynchronous jobs and reference images.

## Prefer asynchronous jobs

Use `POST /v1/images/generations/jobs` for new integrations. It returns a task ID immediately and lets the client poll until the image is ready.

```http
POST /v1/images/generations/jobs
```

Use the synchronous endpoint for short requests or legacy clients:

```http
POST /v1/images/generations
```

The multipart edit endpoint is retained for compatibility, but is not recommended for new integrations:

```http
POST /v1/images/edits
```

## Text-to-image

```bash
curl https://kaienapi.com/v1/images/generations/jobs \\
  -H "Authorization: Bearer <YOUR_API_KEY>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "gpt-image-2",
    "prompt": "Create a clean product poster on a white background",
    "size": "1024x1024",
    "quality": "low",
    "format": "jpeg",
    "n": 1
  }'
```

`gpt-image-2`, `gpt-image-2-2K`, and `gpt-image-2-4K` support synchronous and asynchronous generation. The higher-resolution variants require dimensions that match the model limits and should normally use the asynchronous endpoint.

## Reference images

Use public image URLs or Base64 input in the asynchronous JSON request:

```json
{
  "model": "gpt-image-2",
  "prompt": "Keep the subject from image 1 and use the style from image 2.",
  "image": [
    "https://oss.example.com/subject.jpg",
    "https://oss.example.com/style.jpg"
  ],
  "size": "1024x1024",
  "quality": "standard",
  "format": "png",
  "n": 1
}
```

The `image` field accepts one URL or an array. `images` is also accepted for compatible clients. Do not send `image`, `image[]`, and `images` in the same request.

For Base64 input, use a complete data URL when possible:

```json
{
  "model": "gpt-image-2",
  "prompt": "Use the reference image to create a new product scene.",
  "images": ["data:image/png;base64,<IMAGE_BASE64>"],
  "size": "1024x1024",
  "quality": "low",
  "response_format": "url"
}
```

Reference URLs must remain publicly accessible while the task is running. Resize large images before submission. Base64 input is decoded and uploaded to temporary storage before the model request.

## Polling

1. Create the job and save its `id`.
2. Poll `GET /v1/images/generations/jobs/{job_id}` every two to three seconds for the first 30 seconds.
3. Slow polling to five to ten seconds for longer jobs.
4. Stop only at `succeeded` or `failed`.
5. Read `data` on success and `error.message` on failure.

Do not recreate a job after a temporary network failure. Keep the original task ID so the user can resume after a page refresh.

## Size and quality

Use `size` for the requested dimensions and `quality` for the model quality tier. The 2K and 4K variants validate width, height, aspect ratio, and pixel count more strictly than the base model. Follow the model limits shown in the API response and keep the original error body when diagnosing a rejected request.