How to Use the Nano Banana 2 API: A Complete Tutorial

Nano-Banana-2 is the mid-tier model in hiapi's Nano Banana image family: text-to-image from a prompt alone, image-to-image editing from up to 14 reference URLs, and resolution control up to 4K. This tutorial covers authentication, the exact request schema for both modes, working curl/Python/Node examples, and the errors you'll actually hit in production.

What you'll build, and what you need

Goal: send a request to nano-banana-2, wait for the image, and download it — first from a text prompt, then from a reference image.

You need one thing: a hiapi API key (sk-...). Grab it from your hiapi dashboard. Per-image pricing (it varies by resolution) is on the pricing page and the Nano Banana 2 model page.

Like every image model on hiapi, Nano-Banana-2 runs through the unified async task API: POST /v1/tasks creates a job, then you either poll GET /v1/tasks/{id} or receive a webhook when it's done.

Minimal working example: text-to-image

Create the task:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "output_format": "png"
    }
  }'

The response carries the task id at data.taskId. Poll it:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Once data.status is "success", the image is at data.output[0].url. Download it immediately — output URLs are signed and carry an expireAt, so persist the bytes, not the link.

prompt is the only required field (model aside). Everything else defaults: aspect_ratio defaults to "auto", resolution defaults to "1K", output_format defaults to "png". The full set of accepted aspect_ratio values is 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9, auto — send anything else and you get a 400 naming the valid set. The schema is strict (additionalProperties: false), so a typo'd field name 400s immediately rather than silently defaulting.

Image-to-image: editing with reference images

Pass reference image URLs in image_input (not image_urls — that field name belongs to the smaller Nano-Banana-2-Lite tier, and mixing them up is the single most common integration bug people hit switching between the two):

import requests, time

payload = {
    "model": "nano-banana-2",
    "input": {
        "prompt": "Restyle this product photo with a warm studio lighting setup and a soft gradient background",
        "image_input": [
            "https://example.com/your-product-photo.jpg"
        ],
        "resolution": "2K",
    },
}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": "Bearer sk-YOUR_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers={"Authorization": "Bearer sk-YOUR_KEY"},
    ).json()["data"]
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]
    print(image_url)
else:
    print("generation failed:", task.get("error"))

image_input accepts up to 14 reference URLs (they must be publicly fetchable — hiapi's servers download them). You can combine references with any of aspect_ratio, resolution, and output_format in the same request; Nano-Banana-2 doesn't require an explicit "mode" flag — supplying image_input is what switches it into editing behavior.

Same request in Node

const payload = {
  model: "nano-banana-2",
  input: {
    prompt: "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights, dreamy bokeh",
    aspect_ratio: "16:9",
    resolution: "1K",
  },
};

const response = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const { data } = await response.json();
console.log(data.taskId);

Poll GET /v1/tasks/{taskId} the same way as the curl example above.

Production hardening

Use webhooks instead of polling when you can. Add a callback block and hiapi POSTs the terminal result to your endpoint instead of you polling for it:

{
  "model": "nano-banana-2",
  "input": { "prompt": "...", "resolution": "1K" },
  "callback": { "url": "https://your-app.com/webhooks/hiapi", "when": "final" }
}

when only accepts "final" — exactly one callback, whether the task succeeds or fails. If your callback endpoint is flaky or you're just scripting locally, polling every 2–5 seconds with a hard timeout is fine; see this checklist if a callback you set up stops arriving.

Make task creation idempotent on your side. POST /v1/tasks is not idempotent — retrying a timed-out create can spin up two billed tasks. Persist the taskId the moment you receive it, and on restart, resume polling the saved id instead of re-creating.

Handle both error layers. Request-level failures come back as HTTP errors before any task is created: an invalid key returns 401 with {"error": {"code": "permission_denied", "type": "hiapi_error", ...}} (see the API key troubleshooting guide if this happens with a key you believe is valid), and a bad field or value returns 400 INVALID_REQUEST with the specific violation. Task-level failures arrive later, once a task has actually been dispatched — those show up as status: "fail" with an error object on the task, and there's no cancel endpoint once a task is running.

Store bytes, not URLs. Output URLs are signed and expire. Download the image into your own storage before doing anything else with it.

Related reading

• Nano Banana 2 model page — live parameters, pricing, and playground
• Nano Banana 2 Lite API tutorial — the budget tier, different reference-image field name
• hiapi task callback troubleshooting
• Invalid API key errors: causes and fixes
• hiapi docs and pricing

FAQ

What's the difference between Nano-Banana-2 and Nano-Banana-2-Lite? Both run the same task API, but the reference-image field is different — Nano-Banana-2 uses image_input (up to 14 URLs) and supports explicit resolution control (1K/2K/4K); Lite uses image_urls (up to 10 URLs) and has no resolution parameter. Sending the wrong field name for the tier you're calling returns a 400 additional properties not allowed.

Does Nano-Banana-2 do text-to-image, or does it need a reference image? Both. prompt alone is enough for text-to-image; adding image_input switches the same call into image-to-image editing. There's no separate endpoint or mode flag.

How many reference images can I send? Up to 14 URLs in image_input. They must be public, fetchable URLs — hiapi's backend downloads them before generation starts.

What resolutions are available, and how do I pick an aspect ratio? resolution accepts 1K, 2K, or 4K (default 1K). aspect_ratio is independent of resolution and accepts 15 values from square (1:1) through wide (21:9) and tall (9:16) ratios, plus auto to let the model choose based on the prompt or references.

Why do I get a 400 "additional properties not allowed"? The input schema is strict — every field name is checked, and unknown or misspelled fields (like image_urls instead of image_input, or size instead of resolution) are rejected immediately rather than ignored.

What does a 401 permission_denied mean? Your API key is invalid, revoked, or malformed. Confirm it in your dashboard and make sure you're sending Authorization: Bearer sk-... exactly.

How long are output image URLs valid? They're signed URLs with an expireAt timestamp in the output object. Download and store the bytes yourself immediately — don't hot-link the task output in production.