# API

## Access

API access is included with the **Ultimate** plan. Create a key in [Settings → API Keys](https://probanana.net/settings/apikeys) and send it as a bearer token. Keys stop working if the plan no longer includes API access. Keep keys secret — anyone with a key spends your credits.

```
Authorization: Bearer sk-...
```

Jobs cost the same credits as in the studio, use the same resolution and Beast mode limits as your plan, and are refunded automatically if a model fails.

## Start a job

`POST /api/v1/images`

| Field               | Type                  | Notes                                                                                                |
| ------------------- | --------------------- | ---------------------------------------------------------------------------------------------------- |
| `model` or `models` | string / string[]     | e.g. `nano-banana-2-1`; several models = Beast mode (up to 8 on Ultimate); `auto` picks the best fit |
| `prompt`            | string                | required, up to 3,000 characters                                                                     |
| `references`        | string[]              | up to 8 public `https://` image URLs                                                                 |
| `resolution`        | `1K` \| `2K` \| `4K`  | snapped to what each model supports                                                                  |
| `aspectRatio`       | string                | e.g. `1:1`, `16:9`, `9:16`                                                                           |
| `relax`             | boolean               | Relax mode on Nano Banana / 2 / Pro — no credits, slower, hourly limit                               |
| `visibility`        | `public` \| `private` | Private Mode is on by default for your plan                                                          |

```bash
curl https://probanana.net/api/v1/images \
  -H "Authorization: Bearer $NBA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"models":["nano-banana-2-1","gpt-image-2-5-flare"],"prompt":"A ceramic mug on a sunlit desk","resolution":"2K"}'
```

The response (`201`) is `{ "data": [ { "id", "model", "status", "credits", ... } ] }` — one job per model.

## Poll a job

`GET /api/v1/images/{id}` returns `{ "data": { "status", "outputs": [url], "error" } }`. `status` is `pending`, `processing`, `success` or `failed`. Poll every few seconds; most images finish in 10–60 seconds.

## Models

`nano-banana`, `nano-banana-2`, `nano-banana-2-1`, `nano-banana-pro`, `gpt-image-2`, `gpt-image-2-5-flare`, `gpt-image-2-5-sunburst`, `seedream-4-5`, `seedream-5-lite`, `seedream-5-pro`, or `auto`.

## Errors

Errors return `{ "error": { "message" } }` with `401` (bad key), `403` (plan has no API access), `402` (not enough credits), `400` (invalid request or plan limit) or `429` (too many requests).

---

Source: https://probanana.net/api-docs · Site index for AI agents: https://probanana.net/llms.txt · Full content: https://probanana.net/llms-full.txt
