# GPT Image 2 API Reference

Use the imya API to create high quality GPT Image 2 generations from your own app, backend, or automation workflow.

> Developer preview: this document defines the public imya API contract. Enable production traffic only after your API endpoint is connected and verified.

## Base URL

```text
https://imya.ai
```

## Authentication

Create an API key in your imya account, then pass it as a Bearer token.

```http
Authorization: Bearer imya_xxxxxxxxx
Content-Type: application/json
```

## Create an image generation task

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| model | string | Yes | Use `gpt-image-2`. |
| prompt | string | Yes | The text prompt for the image. |
| size | string | No | `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, or `9:16`. |
| quality | string | No | `medium` or `high`. |
| n | number | No | Number of images to generate. Default is `1`. |
| image_urls | string[] | No | Reference images for image-to-image workflows. |
| callback_url | string | No | Optional webhook URL for completion events. |

### Example request

```bash
curl https://imya.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_IMYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A luxury perfume product photo on warm marble, soft studio light",
    "size": "1:1",
    "quality": "medium",
    "n": 1
  }'
```

### Example response

```json
{
  "id": "task_01jz_example",
  "status": "pending",
  "model": "gpt-image-2",
  "credits_reserved": 13
}
```

## Retrieve a task

```http
GET /v1/tasks/{task_id}
```

### Example request

```bash
curl https://imya.ai/v1/tasks/task_01jz_example \
  -H "Authorization: Bearer YOUR_IMYA_API_KEY"
```

### Completed response

```json
{
  "id": "task_01jz_example",
  "status": "succeeded",
  "model": "gpt-image-2",
  "credits_used": 13,
  "data": [
    {
      "url": "https://cdn.imya.ai/generated/example.png",
      "width": 1024,
      "height": 1024
    }
  ]
}
```

## Status values

| Status | Meaning |
| --- | --- |
| pending | The task has been accepted. |
| processing | The model is generating. |
| succeeded | The result is ready. |
| failed | The task failed. Check `error`. |

## Credit billing

Credits are charged to the imya user that owns the API key. The final credit cost depends on the model, output count, and the user's plan discount.

If a task fails before generation starts, reserved credits should be released.

## Errors

| Code | Meaning |
| --- | --- |
| 401 | Missing or invalid API key. |
| 402 | Not enough credits. |
| 422 | Invalid model, prompt, size, or quality. |
| 429 | Rate limit reached. |
| 500 | Provider or server error. |