# Nano Banana Pro — /images/generations

Image generation (async, job-based) backed by the flagship Nano Banana Pro (Gemini 3 Pro Image). Text-to-image needs only a prompt; image-to-image takes the reference in `image` (a URL, a data: URI, or base64) and repaints it while preserving the subject. Stronger detail, composition and in-image text layout — ideal for commercial covers and high-quality illustration. Returns a job id immediately (HTTP 202); poll GET /v1/images/jobs/{id}. Supports 7 aspect ratios and 1K / 2K / 4K, and failed requests are not charged.

**Endpoint:** `POST https://nezhagate.com/v1/images/generations`

## Authentication
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Request body
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Model ID, here nano-banana-pro. |
| `prompt` | string | Yes | Text prompt describing the image. |
| `size` | string | No | Output aspect ratio. Recommended: pass a ratio — 1:1, 3:4, 2:3, 9:16, 4:3, 3:2, 16:9 — and the model renders natively at that ratio with no subject cropping. Pixel sizes (e.g. 1024x1024, 1024x1536, 1536x1024) are also accepted. Default 1:1 (square). |
| `n` | integer | No | Number of images, default 1. |
| `image` | string | No | Image-to-image: a reference image as a public URL, a data: URI, or raw base64. When present the request runs true identity-preserving image-to-image at the chosen size/ratio — equivalent to calling /v1/images/edits. |
| `images` | array | No | Multi-image reference (up to 8; ≤4 recommended for subject consistency): pass an array of strings, or an array of [{"image_url": "..."}] objects; each item a public URL, a data: URI, or base64. Runs multi-reference image-to-image (fusing the subjects and style of several references) - equivalent to multi-image input of /v1/images/edits. For a single reference the image field above also works. |

## Request example
```bash
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-pro", "prompt": "a serene ink-wash poster, lots of negative space", "size": "1024x1536"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

## Response
```json
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "nano-banana-pro"
}
```

## Image-to-Image
Image-to-image: put the reference in `image` (a public URL, a data: URI, or raw base64) to run true identity-preserving i2i — the model regenerates from it at the chosen size/ratio. Equivalent to calling /v1/images/edits.

```bash
curl __BASE__/v1/images/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "nano-banana-pro", "prompt": "change the background to a starry sky", "image": "https://example.com/ref.png", "size": "3:4"}'
```

## Image jobs (submit → poll for the result)
Image rendering usually takes 1–3 minutes, so the image endpoints are job-only: submitting a request returns a job id immediately (HTTP 202); poll for the result with that id — the server keeps rendering across restarts, so the image is never lost. Same for text-to-image and image-to-image. (The old "async": true field is no longer needed; it is accepted but ignored.)

```bash
# Step 1 · Submit the job (returns a job id right away, HTTP 202)
curl __BASE__/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-pro", "prompt": "an ink-wash poster", "size": "3:4"}'
# Step 2 · Poll for the result (every 2–3s until status is succeeded)
curl __BASE__/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

status is one of queued / processing / succeeded / failed. On success the response carries data[].url. A job can only be polled by the account that created it. Image endpoints are always async — submit returns a job id; "async": true is accepted only for backward compatibility and ignored.