Nano Banana 2 Lite Standard

Generate or edit a 1K image from text and up to 14 reference images. Billed by the tokens each render uses.

• Billed by tokens: input, text and thinking output, and image output tokens at per-1M-token rates. The per-image prices below are estimates at the image tokens listed for each resolution.
• Asynchronous only: create a task with POST /v1/images/tasks, then poll GET /v1/tasks/{task_id}. The render runs on BeatAPI’s side, so a long render never holds your connection open. The synchronous POST /v1/images/generations is not available for this model.
• One image per task. To get several images, create several tasks.
• Text to image, or edit and combine up to 14 reference images given as public HTTPS links.
• A failed task costs nothing: the reservation is returned in full.

Opens this model in the API Explorer. Enter your BeatAPI API key to create a task: the call is real and is billed to your own balance.

Model IDs

The fixed-price model and this one take the same request; only the way the price is counted differs. The values below come straight from the gateway contract.

Endpoint and authentication

POST https://api.beatapi.io/v1/images/tasks

Send the body as JSON with Content-Type: application/json. Idempotency-Key is optional: send a unique value (at most 255 characters) per logical request and reuse it only to retry that exact body. Within 24 hours a retry with the same key and body returns the first response again with Idempotent-Replayed: true; the same key with a different body returns 409 idempotency_conflict. Responses other than 2xx are not stored, so a retry after a 400 or 402 runs again.

How a request works

Input modes

Request parameters

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png",
  "https://cdn.beatapi.io/samples/neon-singer.png"
]

The gateway also checks these combinations before creating the task:

• billed per token at the listed rates for the tokens each render uses (input, text and thinking output, image output); the listed per-image prices are estimates at each resolution’s listed image tokens
• this is the official version, billed per token; nano-banana-2-lite is the same model at a fixed price per image

Input media limits

The gateway reads every input before the task is created and refuses one outside these limits with a 400 bad_request that names the input. Nothing is charged.

• Reference images: PNG, JPEG or WebP, recognised from the file content rather than the file name or Content-Type; at most 50 MB each (decimal megabytes; checked when the host states the size); 1 to 14 links. GIF, HEIC and SVG are refused.
• No pixel or aspect-ratio limit is checked for this model.
• If a host does not answer in time, the link is not refused at create; a link that still cannot be fetched later fails the task with bad_request, and the task is refunded.
• Have a local file? Upload it with POST /v1/files and pass the returned data.url.

Submit, then poll

This model runs only as a task. POST /v1/images/tasks answers at once with the task ID in data.id; then call GET /v1/tasks/{task_id} every data.poll_after_seconds until data.status is succeeded or failed. The render runs on BeatAPI’s side, so a long render never holds your connection open or runs into your client’s timeout. The synchronous POST /v1/images/generations is not available for this model.

# 1. Create the task. The call returns at once; the task ID is in data.id.
TASK_ID=$(curl -sS -X POST https://api.beatapi.io/v1/images/tasks \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-2-lite-std","prompt":"A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field","resolution":"1K"}' | jq -r '.data.id')
# 2. Poll until the task is final. The render runs on BeatAPI, not on this connection.
while true; do
  TASK=$(curl -sS "https://api.beatapi.io/v1/tasks/$TASK_ID" -H "Authorization: Bearer $BEATAPI_API_KEY")
  STATUS=$(echo "$TASK" | jq -r '.data.status')
  if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]; then break; fi
  sleep 5
done
echo "$TASK" | jq '.data.output.media[].url, .data.usage'

Through the Capabilities API it is the same task: start it with POST /v1/capabilities/run, then send the status call with the returned task ID until it is succeeded or failed.

{"reference":"model:nano-banana-2-lite-std","input":{"model":"nano-banana-2-lite-std","prompt":"A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field","resolution":"1K"}}

{"reference":"model:nano-banana-2-lite-std","operation":"status","task_id":"<task_id>"}

Billed by tokens, compared with the fixed price

Fields this model does not accept

The image endpoint knows a few fields that other image models use. Sending one of them here is refused instead of being ignored, so you never pay for a setting that had no effect:

• quality, seed, background, size, enhance_prompt → field "quality" is not supported by model nano-banana-2-lite-std (with the field you sent).
• Any other unknown field, such as n → unknown field: n. There is no n: one task makes one image.

Request examples

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "nano-banana-2-lite-std",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "16:9",
  "resolution": "1K"
}'

Text to image

A 1K landscape image from a prompt.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "nano-banana-2-lite-std",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "16:9",
  "resolution": "1K"
}'

Edit one image

Change the background and keep the product. auto usually keeps the shape of the reference.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "nano-banana-2-lite-std",
  "prompt": "Keep the bottle exactly as it is. Replace the background with a sunlit kitchen counter and add a soft reflection under the bottle.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "auto"
}'

Combine several images

Name each reference in the prompt by its position.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "nano-banana-2-lite-std",
  "prompt": "Place the bottle from the first image on a neon-lit stage like the one in the second image. Keep the bottle label readable.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "aspect_ratio": "1:1",
  "resolution": "1K"
}'

1K JPEG poster

A tall poster delivered as JPEG.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "nano-banana-2-lite-std",
  "prompt": "A retro travel poster of a coastal city at sunset, bold flat colours, large title text \"SEASIDE\" at the top",
  "aspect_ratio": "9:16",
  "resolution": "1K",
  "output_format": "jpeg"
}'

Responses

Create a task (201)

The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "nano-banana-2-lite-std",
    "capability_version": 1,
    "media_type": "image",
    "model": "nano-banana-2-lite-std",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.01848,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.01848
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Finished task

GET /v1/tasks/{task_id} returns HTTP 200 with status: "succeeded" and the result in data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "nano-banana-2-lite-std",
    "capability_version": 1,
    "media_type": "image",
    "model": "nano-banana-2-lite-std",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "image",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png",
          "mime_type": "image/png"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png"
    },
    "usage": {
      "credits_reserved": 0.01848,
      "credits_settled": 0.01848,
      "credits_refunded": 0,
      "credits_charged": 0.01848
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Output fields

Failed task

A failed task is still HTTP 200 on GET /v1/tasks/{task_id}: the failure is in the body. The reservation is returned in full, so nothing is charged.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "nano-banana-2-lite-std",
    "capability_version": 1,
    "media_type": "image",
    "model": "nano-banana-2-lite-std",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.01848,
      "credits_settled": 0,
      "credits_refunded": 0.01848,
      "credits_charged": 0
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Complete example

Create a task, wait for it with the server’s polling hint, and print the result URLs. Set BEATAPI_API_KEY in your environment and install requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/images/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "nano-banana-2-lite-std",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "16:9",
  "resolution": "1K"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Billing

• Billed by tokens at the per-1M-token rates in the table below: input (the prompt and the reference images in images), text and thinking output, and image output. The model counts the tokens; the resolution and the reference images change the count.
• The per-image prices are estimates at the image-output tokens listed for one render of each resolution, without reference images; reference images and thinking add to them.
• When the task is created, the estimate for its tier is reserved from your balance, and from the key’s quota if it has one. When it succeeds, the charge is settled to the tokens the render actually used, so the final data.usage can differ from the reservation. A request refused before a task exists costs nothing.
• A failed task is refunded in full.
• The fixed-price nano-banana-2-lite is the same model at one flat price per image, whatever the render used.

Current list prices, the same as on Pricing. An account with a negotiated discount pays less; data.usage on the task always shows the amount actually charged.

Common errors

HTTP errors at a glance

Errors before a task exists arrive as a non-2xx response, and nothing is charged. Branch on error.code or error.retryable; message names the problem. The full list and retry policy are on Errors.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}