How to Use Nano-Banana-2-Lite via the HiAPI API: curl, Python, and a Working Request

What Nano-Banana-2-Lite Is and When to Use It

Nano-Banana-2-Lite is the ultra-low-cost tier in the Nano-Banana family available on HiAPI. It is designed for high-volume, cost-sensitive image generation where you want predictable spend and fast iteration rather than maximum fidelity. If you are prototyping a feature, generating thumbnails or variations at scale, or running background jobs that can tolerate a lighter model, this tier is the right starting point.

Use it when the output is one part of a larger pipeline: draft visuals, placeholder art, batch experiments, or A/B tests where you need many candidates cheaply. For final hero assets or cases that demand the highest detail, step up to a larger tier. The API surface stays the same, so you can switch models without rewriting your integration.

Prerequisites and Request Anatomy

Before you call Nano-Banana-2-Lite, make sure you have:

• A HiAPI account and an API key. Keep it in an environment variable such as HIAPI_API_KEY; never commit it to source control.
• A terminal with curl for the first test, and Python 3.8+ with the requests library for the scripted version.
• A prompt that describes the image you want. Start simple; you can add reference inputs later.

Every request to HiAPI follows the same shape: a POST to the model endpoint with a JSON body. The body carries the model name, the prompt, and any optional parameters. Because generation is asynchronous, the submit call returns a job identifier that you then poll. The response is JSON, and errors include a status code and a message you can log.

At a minimum, your payload needs model set to nano-banana-2-lite and a prompt. Optional fields such as reference_images and output settings are covered in later sections.

A Working curl Request

Here is a complete, copy-ready call that submits a basic job. Replace the placeholder prompt with your own.

curl -X POST https://api.hiapi.ai/v1/images/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1"
  }'

The response contains a job id and a status field. A fresh submission typically returns queued or processing. Save that id; you will use it in the polling step. If you get a 401, check that HIAPI_API_KEY is exported in your shell. If you get a 422, inspect the error message for the offending field.

The Same Request in Python

Port the curl call to Python so you can drop it into a script or service. This example uses requests and reads the key from the environment.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

Keep the request body in a dictionary so you can extend it with optional fields without rewriting the call. A timeout of 30 seconds is reasonable for the submit step because the heavy work happens asynchronously.

Adding Optional Reference Inputs

Reference inputs let you steer the generation with visual context. On HiAPI you attach them as a reference_images array in the same JSON body. Each entry is a publicly accessible URL or a base64 data URI. Use references when you want to preserve a composition, match a style, or keep a product shot consistent across variants.

{
  "model": "nano-banana-2-lite",
  "prompt": "Same layout, but in a warm sunset palette",
  "reference_images": [
    "https://example.com/reference/layout.png"
  ]
}

Include references only when they add signal. Each reference is extra data to transfer and can dilute a simple prompt. For straightforward text-to-image jobs, omit the field entirely. When you do use references, keep them relevant and few; one or two well-chosen images usually beat a large set.

Polling for the Async Result

Image generation is asynchronous: you submit, then poll a job endpoint until the status is terminal. The pattern is the same in curl and Python.

With curl, check the job by its id:

curl https://api.hiapi.ai/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

In Python, wrap the poll in a loop with a delay so you do not hammer the API:

import time

def wait_for_job(job_id, interval=2, max_attempts=30):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    for _ in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError("Job did not finish in time")

Start with a short interval and back off if you are polling many jobs. Always set a maximum number of attempts so a stuck job does not block your worker forever. Treat failed as terminal and log the error message.

Downloading and Verifying the Output

When the job succeeds, the response includes one or more output URLs. Fetch the file and save it locally, then verify what you got.

result = wait_for_job(job["id"])
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
    img = requests.get(image_url, timeout=60)
    img.raise_for_status()
    with open("output.png", "wb") as f:
        f.write(img.content)

Sanity-check the download: confirm the content type is an image, check the file size is non-zero and plausible, and open it once to confirm it matches your prompt. Log the job id alongside the local filename so you can trace any asset back to its request.

Cost and Failure Checklist Before Going to Production

Nano-Banana-2-Lite is priced as the ultra-low-cost tier; billing follows the platform's standard image-generation meter. Check the current price panel on the site for exact rates rather than hard-coding assumptions.

Before you ship, put these habits in place:

• Retry with backoff. Retry transient errors (timeouts, 5xx) a small number of times with increasing delay; do not retry 4xx validation errors.
• Cap polling. Use a fixed interval and a maximum attempt count. Log the final status and elapsed time.
• Log job ids and prompts. Store the job id, prompt, model, and any reference inputs with each output so you can reproduce or audit a run.
• Validate inputs early. Check prompt length and reference URLs before submitting to avoid wasted jobs.

With those checks in place, Nano-Banana-2-Lite is a predictable, low-cost workhorse for batch and background generation. Explore the model page on HiAPI for the latest parameters and rate details.