KovAPIKovAPI
nano-banana-2-lite

Nano Banana 2 Lite · API

POST https://kovapi.com/v1/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.

Try in Playground →

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)
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)
{
  "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
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
Response when it succeeds
{
  "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)
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

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create an API Key in the console to start.

Request body

ParameterTypeRequiredDescription
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

cURL
# 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

200 · 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.

TierCredits per imageUSD per image
1K2$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 ratio1K
1:11024x1024
16:91376x768
9:16768x1376
4:31200x896
3:4896x1200
3:21264x848
2:3848x1264
4:5928x1152
5:41152x928
21:91584x672
1:4512x2064
4:12064x512
1:8352x2928
8:12928x352

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.
curl · Image-to-image with two references
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:

statusMeaningExtra fields
queuedWaiting in the queuequeue_position (jobs ahead of yours), eta_seconds (estimated wait in seconds, a guide only)
processingRendering—
succeededDonedata[].url (the image link; our image host keeps it for 7 days); usage.images (images delivered), usage.resolution (billed tier)
failedFailed; the amount held at submit has been refunded in fullerror.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.

TierTypical time
1K5–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)

HTTPcodeCauseWhat to do
400missing_promptprompt is emptyAdd a prompt
400model_not_foundThe model id is wrong or not available right nowCheck the id; /v1/models lists the available ones
400invalid_requestA reference image cannot be read (dead link, not an image, over 16MB...); message says which one and whyUse a direct image link or send it as base64
401invalid_api_keyThe key is wrong, deleted or disabledCheck the key in the console
402insufficient_quotaNot enough balance to hold this jobTop up and retry
429rate_limit_exceededOver the per-minute limit set on this keySlow down, or raise the key limit in the console
503model_maintenanceThe model is under maintenanceRetry later; see the status page
503service_unavailableA 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)

SituationWhat you seeWhat to do
The prompt or a reference did not pass the Google safety reviewerror.message such as Content blockedRewrite 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 messageSubmit again
The job waited 15 minutes without startingerror.message says soSubmit 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

curl · callback_url
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"}'