# Nano Banana 2 Lite — /images/generations

Image generation (async, job-based) backed by Google Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image), the fastest and lowest-cost model in the Nano Banana family. Text-to-image needs only a prompt; for an edit put the references in image or images (a URL, a data: URI or base64), or call /v1/images/edits. Submitting returns a job id at once (HTTP 202); poll GET /v1/images/jobs/{id} for the image. 1K only, in 14 aspect ratios: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9, 4:1, 1:4, 8:1 and 1:8. A 2K or 4K request is refused at submit and not charged. Billed per image; failed requests are not charged.

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

## Quick start

Three steps: submit a job, poll it, take the image link. Replace YOUR_API_KEY with your key and the commands below run as they are.

Step 1 · Submit (returns a job id at once, HTTP 202)

```bash
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "16:9", "resolution": "1K"}'
```

Response (HTTP 202)

```json
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281500,
  "model": "nano-banana-2-lite"
}
```

Step 2 · Poll every 2-3 seconds until status is succeeded or failed

```bash
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response when it succeeds

```json
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281500,
  "model": "nano-banana-2-lite",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.jpg"}
  ],
  "usage": {"images": 1, "resolution": "1K", "model": "nano-banana-2-lite"}
}
```

Step 3 · data[0].url is the image (the original image from upstream, in JPEG). It is kept for 7 days; download it to your own storage to keep it longer.

### Complete example (Python: submit, wait, save to disk)

```python
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. submit
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "nano-banana-2-lite",
    "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field",
    "size": "16:9",
    "resolution": "1K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. poll every 3 seconds until it finishes
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. download the image
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("nano-banana-2-lite.jpg", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["message"])
```

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

## Request body
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Model ID, here nano-banana-2-lite. |
| `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). |
| `resolution` | string | No | Resolution: 1K only (the default; you can omit it). resolution 2K / 4K returns 400 unsupported_resolution at submit and is not charged. When size is a pixel size, the 14 native 1K sizes of Lite (e.g. 2928x352 or 1584x672) all count as 1K. |
| `thinking_level` | string | No | Thinking level, nano-banana-2-lite only: minimal (the default; may be omitted) or high. high thinks before it draws: 3–6 seconds slower, same price. Worth trying for complex layouts, exact counts and text placement; in our tests the pictures did not look clearly different. On other models high is refused at submit with a 400, no charge. |
| `n` | integer | No | Always 1: each job returns one image. A larger value still returns one image and charges for one; for several images submit several jobs at once. |
| `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 | Several reference images, up to 8 (only the first 8 are used if you send more): an array of strings or of {"image_url": "..."} objects; each a public image URL, a data: URI or base64, up to 16MB. Sending them runs image-to-image, the same as /v1/images/edits. For one reference the image field above also works. |

## Request example
```bash
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2-lite", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "1K"}'
# 2) poll until status=succeeded
curl https://kovapi.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-2-lite"
}
```

## Price

Billed per image by resolution tier only: aspect ratio, text-to-image or image-to-image make no difference. The tier price is held when you submit and refunded in full if the job fails. 1 credit = $0.005.

| Tier | Credits per image | USD per image |
| --- | --- | --- |
| 1K | 2 | $0.01 |

Each job returns exactly one image: whatever n you send, you get one image and pay for one. For several images, submit several jobs at once (an account renders up to 50 at the same time).

## Aspect ratio, resolution and output size

Put the ratio in size; resolution can be omitted (1K is the only tier). The model renders at the chosen ratio directly, and you get the original image from upstream, neither cropped nor resized; each ratio has one fixed size, listed below:

| Aspect ratio | 1K |
| --- | --- |
| 1:1 | 1024x1024 |
| 16:9 | 1376x768 |
| 9:16 | 768x1376 |
| 4:3 | 1200x896 |
| 3:4 | 896x1200 |
| 3:2 | 1264x848 |
| 2:3 | 848x1264 |
| 4:5 | 928x1152 |
| 5:4 | 1152x928 |
| 21:9 | 1584x672 |
| 1:4 | 512x2064 |
| 4:1 | 2064x512 |
| 1:8 | 352x2928 |
| 8:1 | 2928x352 |

Only the ratios in the table are supported (a pixel size in size counts as the closest of them, within 1.5%). Any other ratio fails straight away and is not charged; nothing is drawn and then cropped.

size can also be a pixel size: the sizes in the table (e.g. 2928x352 or 1584x672) render at 1K, and any other pixel size renders at the native 1K size of the closest ratio (within 1.5%); a longest side over 1536 counts as 2K / 4K and is refused at submit. resolution can only be 1K: 2K / 4K returns 400 unsupported_resolution at submit, with no job and no charge. Without size you get a 1:1 square.

## Image-to-image and reference images

- Send image (one picture) or images (several, up to 8; only the first 8 are used if you send more) and the job runs image-to-image; say in the prompt what to change. POST /v1/images/edits takes the same parameters.
- Each reference can be a public image URL (http or https), a data: URI or plain base64, up to 16MB each, in a common format such as JPEG, PNG or WebP.
- A URL has to download the image itself: not a web page, and not behind a login or hotlink protection. A reference we cannot read is refused at submit with 400 and the reason; no job is created and nothing is charged.
- The output ratio comes from size, not from the reference. To keep the original ratio, set size to it.
- We host the references for you and keep them for 7 days.

**Image-to-image with two references**

```bash
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "1K"}'
```

## Job status and fields

GET /v1/images/jobs/{id} always returns id, object (image.generation.job), status, created (Unix seconds) and model; the other fields depend on the status:

| status | Meaning | Extra fields |
| --- | --- | --- |
| `queued` | Waiting in the queue | queue_position (jobs ahead of yours), eta_seconds (estimated wait in seconds, a guide only) |
| `processing` | Rendering | — |
| `succeeded` | Done | data[].url (the image link; our image host keeps it for 7 days); usage.images (images delivered), usage.resolution (billed tier) |
| `failed` | Failed; the amount held at submit has been refunded in full | error.message, error.type, error.code |

Poll every 2-3 seconds. One account renders up to 50 images at a time; further jobs wait in submission order, and a job that has not started after 15 minutes fails and is refunded in full. Job records are kept for 3 days, after which the job id returns 404, but the image link stays valid for its 7 days. Only the account that submitted a job can read it.

## How long it takes

Typical time from submit to result, as a guide. Image-to-image takes a few to a dozen seconds longer; a job the gateway retries automatically can take 1-2 minutes.

| Tier | Typical time |
| --- | --- |
| 1K | 5–15 s |

## Errors and refunds

Every error has the same shape, {"error": {"message", "type", "code", "param"}}; branch on code.

### Errors returned at submit (no job is created and nothing is charged)

| HTTP | code | Cause | What to do |
| --- | --- | --- | --- |
| 400 | `missing_prompt` | prompt is empty | Add a prompt |
| 400 | `model_not_found` | The model id is wrong or not available right now | Check the id; /v1/models lists the available ones |
| 400 | `invalid_request` | A reference image cannot be read (dead link, not an image, over 16MB...); message says which one and why | Use a direct image link or send it as base64 |
| 401 | `invalid_api_key` | The key is wrong, deleted or disabled | Check the key in the console |
| 402 | `insufficient_quota` | Not enough balance to hold this job | Top up and retry |
| 429 | `rate_limit_exceeded` | Over the per-minute limit set on this key | Slow down, or raise the key limit in the console |
| 503 | `model_maintenance` | The model is under maintenance | Retry later; see the status page |
| 503 | `service_unavailable` | A temporary error on our side (e.g. storing your reference failed) | Retry shortly |

### Failed jobs (the job was accepted and later ended with status failed; the hold is refunded in full)

| Situation | What you see | What to do |
| --- | --- | --- |
| The prompt or a reference did not pass the Google safety review | error.message such as Content blocked | Rewrite the prompt or change the reference; resubmitting it unchanged is usually refused again |
| A temporary upstream fault or timeout (we retry automatically first and only return a failure when the retries also fail) | error.code such as upstream_error or upstream_timeout, with the reason in message | Submit again |
| The job waited 15 minutes without starting | error.message says so | Submit again later |

## Use a webhook instead of polling

For production, add callback_url when you submit. When the job ends, successfully or not, we POST the same JSON as the job endpoint to that URL as image.completed or image.failed, with signature headers you can verify. You can also set one URL for the whole account under Settings > Webhook. [Webhook docs](https://docs.kovapi.com/en/webhooks)

```bash
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```