Nano Banana Pro

Generate or edit an image from text and up to 14 reference images, at 1K, 2K or 4K, delivered as PNG or JPEG.

• Asynchronous: the create call returns a task ID in a moment; the image arrives when the task succeeds.
• 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.
• Priced per image by resolution: aspect ratio, number of references and prompt length do not change the price.
• 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

All five models use this endpoint and the same fields; they differ in the values they accept. 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://media.beatapi.io/samples/smart-bottle.png",
  "https://media.beatapi.io/samples/neon-singer.png"
]

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.

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-pro (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-pro",
  "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": "2K"
}'

Text to image

A 2K 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-pro",
  "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": "2K"
}'

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-pro",
  "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://media.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-pro",
  "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://media.beatapi.io/samples/smart-bottle.png",
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "aspect_ratio": "1:1",
  "resolution": "1K"
}'

4K JPEG poster

A tall poster delivered as JPEG. This model takes jpg for 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-pro",
  "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": "4K",
  "output_format": "jpg"
}'

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-pro",
    "capability_version": 1,
    "media_type": "image",
    "model": "nano-banana-pro",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.05,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.05
    },
    "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-pro",
    "capability_version": 1,
    "media_type": "image",
    "model": "nano-banana-pro",
    "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.05,
      "credits_settled": 0.05,
      "credits_refunded": 0,
      "credits_charged": 0.05
    },
    "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-pro",
    "capability_version": 1,
    "media_type": "image",
    "model": "nano-banana-pro",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.05,
      "credits_settled": 0,
      "credits_refunded": 0.05,
      "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-pro",
  "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": "2K"
})
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

• One image per task, priced by resolution only (table below). Aspect ratio, number of references and prompt length do not change the price.
• The 1K and 2K tiers have the same price; 4K costs twice as much.
• The price is reserved when the task is created, from your balance and from the key’s quota if it has one. A request refused before a task exists costs nothing.
• A succeeded task keeps the reserved amount. A failed task returns it in full: credits_refunded then equals credits_reserved.

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"
  }
}