> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/image-api/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# BeatAPI Image API

> Compare BeatAPI image generation models, reference-image limits, resolutions, aspect ratios, and model-specific request contracts.

# Image API

Create one asynchronous image generation task with a stable BeatAPI model ID.

| Model                                                         | Input modes            | Required fields   | Main controls                                                                       |
| ------------------------------------------------------------- | ---------------------- | ----------------- | ----------------------------------------------------------------------------------- |
| [`nano-banana`](/image-api/nano-banana)                       | Text, reference images | `model`, `prompt` | Up to 10 references, aspect ratio, PNG/JPEG output                                  |
| [`nano-banana-2`](/image-api/nano-banana-2)                   | Text, reference images | `model`, `prompt` | Up to 10 references, 1K/2K/4K, PNG/JPEG output                                      |
| [`nano-banana-2.1`](/image-api/nano-banana-2-1)               | Text, reference images | `model`, `prompt` | The successor to Nano Banana 2. Up to 14 references, 1K/2K/4K, PNG/JPEG output      |
| [`nano-banana-2-lite`](/image-api/nano-banana-2-lite)         | Text, reference images | `model`, `prompt` | Up to 10 references, fixed 1K, PNG/JPEG output                                      |
| [`nano-banana-pro`](/image-api/nano-banana-pro)               | Text, reference images | `model`, `prompt` | Up to 8 references, up to 4K                                                        |
| [`gpt-image-2`](/image-api/gpt-image-2)                       | Text, reference images | `model`, `prompt` | Up to 16 references, broad aspect ratios, up to 4K                                  |
| [`gpt-image-2.5-flare`](/image-api/gpt-image-2-5-flare)       | Text, reference images | `model`, `prompt` | The fast default of the 2.5 pair. Up to 16 references, 16 aspect ratios, up to 4K   |
| [`gpt-image-2.5-sunburst`](/image-api/gpt-image-2-5-sunburst) | Text, reference images | `model`, `prompt` | The precision half of the 2.5 pair. Up to 16 references, 16 aspect ratios, up to 4K |
| [`seedream-5-pro`](/image-api/seedream-5-pro)                 | Text, reference images | `model`, `prompt` | Up to 10 references, 1K/2K/4K                                                       |
| [`grok-imagine-image-2.0`](/image-api/grok-imagine-image-2-0) | Text, reference images | `model`, `prompt` | Up to 5 references, automatic edit-mode selection                                   |

Open the matching model page for every field, default, enum, combination rule, request example, response, and error behavior.

## List available models

`GET /v1/media/models`

| Parameter    | Location | Type   | Required | Allowed values   |
| ------------ | -------- | ------ | -------- | ---------------- |
| `media_type` | Query    | string | No       | `image`, `video` |

This public endpoint does not require authentication.

```bash
curl "https://api.beatapi.io/v1/media/models?media_type=image"
```

```json
{
  "data": {
    "object": "list",
    "data": [
      {
        "id": "gpt-image-2",
        "object": "generation_model",
        "name": "GPT Image 2",
        "media_type": "image",
        "input_modes": ["text", "image"]
      },
      {
        "id": "gpt-image-2.5-flare",
        "object": "generation_model",
        "name": "GPT Image 2.5 Flare",
        "media_type": "image",
        "input_modes": ["text", "image"]
      },
      {
        "id": "gpt-image-2.5-sunburst",
        "object": "generation_model",
        "name": "GPT Image 2.5 Sunburst",
        "media_type": "image",
        "input_modes": ["text", "image"]
      }
    ]
  }
}
```

| Field         | Type      | Meaning                                       |
| ------------- | --------- | --------------------------------------------- |
| `id`          | string    | Stable public model alias                     |
| `object`      | string    | `generation_model`                            |
| `name`        | string    | Display name                                  |
| `media_type`  | string    | `image` or `video`                            |
| `input_modes` | string\[] | Any of `text`, `image`, `frames`, `reference` |

Internal provider routing is not part of the public contract.

## Shared create contract

`POST /v1/images/tasks`

| Header            | Type   | Required        | Rules                                            |
| ----------------- | ------ | --------------- | ------------------------------------------------ |
| `Authorization`   | string | Yes             | `Bearer <BEATAPI_API_KEY>`                       |
| `Content-Type`    | string | Yes             | `application/json`                               |
| `Idempotency-Key` | string | No, recommended | Up to 255 characters; one key per logical create |

The body must match exactly one model schema. `model` is the discriminator; unknown fields are rejected.

```bash
curl https://api.beatapi.io/v1/images/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Idempotency-Key: image-gpt-image-2-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Editorial product photograph on a warm stone pedestal.",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'
```

A valid request returns `201 Created` with `data.id`, `task_kind="image"`, the selected `model`, `status="queued"`, usage metrics, and `request_id`. Poll `GET /v1/tasks/{task_id}` every 5–10 seconds until `succeeded` or `failed`; successful image is in `data.output.media[]` and `data.output.r2_url`.

An exact idempotent replay returns the accepted task. Reusing a key with a different body returns `409 idempotency_conflict`.

## Shared errors

| HTTP  | Common code                                                                                      | Client action                                                                          |
| ----- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `400` | `bad_request`                                                                                    | Fix fields, values, combinations, counts, or media URLs                                |
| `400` | `content_policy_violation`                                                                       | Change the prompt or input; do not resend unchanged                                    |
| `401` | `missing_api_key` / `invalid_api_key`                                                            | Send the Bearer key, or replace a wrong, expired, disabled, or exhausted one           |
| `402` | `insufficient_credits`                                                                           | Top up before creating a new task                                                      |
| `403` | `forbidden`                                                                                      | Not allowed for this key or account — for example a model not available on free credit |
| `409` | `idempotency_conflict`                                                                           | Reuse the key only with the exact same body                                            |
| `429` | `rate_limit_exceeded` / `user_concurrency_exceeded`                                              | Honor `Retry-After` or wait for active work to finish                                  |
| `500` | `internal_error`                                                                                 | Retry once with backoff                                                                |
| `503` | `processing_unavailable` / `processing_timeout` / `processing_failed` / `result_transfer_failed` | Retry with backoff; nothing was charged                                                |

Error responses include `error.code`, an English `error.message`, `error.retryable`, `error.request_id`, and `error.retry_after_seconds` on a `429`. A task that fails after it was accepted is still read with `200`: see `data.error_code` and [Errors](/errors) for every code and retry rule. The per-model pages below are the production request contracts.

> Compare BeatAPI image generation models, reference-image limits, resolutions, aspect ratios, and model-specific request contracts.

## Docs

- [Nano Banana](https://docs.beatapi.io/image-api/nano-banana.md): Generate or edit one image from text and up to three public HTTPS reference images, with configurable aspect ratio and output format.
- [Nano Banana 2](https://docs.beatapi.io/image-api/nano-banana-2.md): Generate or edit images from text and up to 14 public HTTPS reference images, with 1K, 2K, or 4K output.
- [Nano Banana 2.1](https://docs.beatapi.io/image-api/nano-banana-2-1.md): Generate or edit images with the successor to Nano Banana 2, from text and up to 14 public HTTPS reference images, with 1K, 2K, or 4K output.
- [Nano Banana 2 Lite](https://docs.beatapi.io/image-api/nano-banana-2-lite.md): Generate or edit 1K images from text and up to 14 public HTTPS reference images at the lowest-priced Nano Banana 2 tier.
- [Nano Banana Pro](https://docs.beatapi.io/image-api/nano-banana-pro.md): Generate or edit images from text and up to 14 public HTTPS reference images, with output up to 4K.
- [GPT Image 2](https://docs.beatapi.io/image-api/gpt-image-2.md): Generate or edit images from text and up to sixteen public HTTPS reference images, with output up to 4K.
- [GPT Image 2.5 Flare](https://docs.beatapi.io/image-api/gpt-image-2-5-flare.md): The fast default of the GPT Image 2.5 pair — natural lighting and rich textures, from text or up to sixteen public HTTPS reference images, across sixteen aspect ratios and output up to 4K.
- [GPT Image 2.5 Sunburst](https://docs.beatapi.io/image-api/gpt-image-2-5-sunburst.md): The precision half of the GPT Image 2.5 pair — extra fidelity on intricate detail, from text or up to sixteen public HTTPS reference images, across sixteen aspect ratios and output up to 4K.
- [Seedream 5 Pro](https://docs.beatapi.io/image-api/seedream-5-pro.md): Generate or edit images from text and up to ten public HTTPS reference images, with 1K, 2K, or 4K output.
- [Grok Imagine Image 2.0](https://docs.beatapi.io/image-api/grok-imagine-image-2-0.md): Generate or edit one image from text and up to five public HTTPS reference images, with automatic edit-mode selection.