Nano Banana API Guide: Calling nano-banana, nano-banana-2, and nano-banana-pro on HiAPI

What the Nano Banana model family gives you

Image generation rarely stays at one setting. Early in a project you want fast drafts to explore ideas; later you want a polished render to ship. The Nano Banana family on HiAPI is built around that reality: one interface, three variants, each tuned to a different point on the quality-versus-speed curve.

The naming is intentional. nano-banana is the base option — reach for it when you need quick visual feedback while you are still shaping a prompt or a layout. nano-banana-2 is a step up in fidelity and prompt adherence, the usual pick when the output is close to final but you still want to iterate. nano-banana-pro is the highest-fidelity variant in the family, suited to final renders where detail and composition matter most.

What they share is just as important as what differs. All three are called the same way through the HiAPI endpoint. You authenticate once, shape the request once, and change only the model identifier to move between them. That means an app can start a request on the base model, and later rerun the same prompt on a stronger variant without touching its transport code.

A family like this also keeps your architecture simple. Instead of wiring a separate provider for every quality tier, you keep a single client, a single error-handling path, and a single place to observe usage. The model choice becomes a parameter, not an integration.

Why a family rather than one model

Different steps in a workflow have different needs. Prompt exploration, layout drafts, and client previews reward speed; hero images and marketing assets reward fidelity. Treating model choice as a runtime decision lets you match each step to the right variant without rebuilding your pipeline.

Choosing between nano-banana, nano-banana-2, and nano-banana-pro

Pick the variant by asking two questions: how close is this output to being final, and how many attempts will it take to get there? Everything else follows.

nano-banana: for volume and exploration

Use the base model when you are still deciding what the image should look like. Prompt rewrites, style tests, and layout thumbnails all benefit from fast turnaround, and a rough render often answers the question better than a paragraph of description. Keep this as your default during development.

nano-banana-2: for near-final iterations

Move to nano-banana-2 once the composition is stable and you are refining details — spacing, subject fidelity, how tightly the output follows the prompt. This is the pragmatic middle: noticeably stronger adherence without moving to your highest-fidelity path for every preview.

nano-banana-pro: for final renders

Reserve nano-banana-pro for outputs that ship. Hero images, product shots, and anything a client will look at closely justify the stronger variant. Do not make it the default — reserve it for the last step so your exploratory iterations stay cheap.

A practical routing rule

A simple escalation policy works for most teams:

• Default all new prompts to nano-banana.
• Promote a prompt to nano-banana-2 when the structure is right but quality is not.
• Run the final version on nano-banana-pro once, after the prompt is locked.

This keeps iteration fast and predictable, and it makes your usage patterns easy to reason about. Billing follows usage and differs by variant, so confirm the current rates and limits on the live model docs rather than baking any number into your code.

Prompt patterns that work across variants

The most expensive thing you can do is write prompts that only work on one model. Structure them so a swap is a one-line change.

The four-block prompt

Write every prompt as four labeled parts, in this order:

1. Subject — what is in the image, stated plainly.
2. Style — the visual treatment: photo, illustration, watercolor, 3D render.
3. Composition — framing, camera angle, placement, negative space.
4. Constraints — what to avoid and any hard requirements.

A filled-in example:

Subject: a ceramic coffee mug on a wooden desk, steam rising
Style: soft natural light, shallow depth of field, editorial photography
Composition: centered, 50mm equivalent, generous negative space at top
Constraints: no text, no logos, neutral background

Because the blocks are independent, you can strengthen the style or loosen the composition without rewriting the whole prompt — and the same structure reads well to every variant in the family.

Keep prompts model-agnostic

Avoid phrasing that assumes a particular model's quirks. Describe the result you want, not the steps a specific model should take. When you need to compare variants, change only the model ID and keep the prompt byte-for-byte identical so the comparison is meaningful.

Version your prompts like code

Store prompts as strings in a config file or a small prompt library, keyed by name and version. When a variant produces better output with a tweak, record the change. This is what makes it possible to move a prompt from nano-banana to nano-banana-pro at ship time without surprises.

Negative constraints matter

If a prompt keeps producing text, logos, or unwanted objects, add them to the constraints block explicitly. Across variants, clear negative constraints tend to be more reliable than clever wording.

Building a working request on HiAPI

Every variant is called through the same HiAPI endpoint. The request has four moving parts: the base URL, your auth header, the model field, and the payload.

The shape of a request

A minimal image-generation call looks like this:

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",
    "prompt": "Subject: a ceramic coffee mug on a wooden desk, steam rising\nStyle: soft natural light, editorial photography\nComposition: centered, negative space at top\nConstraints: no text, no logos",
    "n": 1
  }'

Keep the API key in an environment variable or a secrets manager — never in source. The model field is the only thing you change to switch variants, and the prompt field carries the four-block structure from the previous section.

In Python the same call is a handful of lines:

import os, requests

def generate(prompt, model="nano-banana-2"):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": model, "prompt": prompt, "n": 1},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()

What the response contains

The response carries the image result — typically a URL or encoded payload — plus metadata identifying the model that served the request. Read the model field back and log it: it is the cheapest way to tell which variant produced a given asset after the fact.

Confirm parameters before shipping

The exact set of optional parameters differs between variants and evolves over time. Before you hardcode anything beyond model and prompt, check the live model documentation for the current field names and accepted values. Treat anything not documented as unsupported rather than guessing.

Handling responses, failures, and retries

Image generation is a network call with a model behind it, so plan for the parts that fail.

Validate before you trust

After every response, check three things: the HTTP status, the presence of an image payload, and whether the returned model matches what you asked for. Fail loudly on any mismatch rather than passing a bad asset downstream.

Retry the failures that are worth retrying

Not every error deserves a retry. A malformed prompt or an invalid model name will fail the same way every time — fix the request. Transient failures like timeouts, connection resets, and rate-limit responses are worth retrying.

Use bounded exponential backoff with jitter:

import time, random

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except (TimeoutError, ConnectionError):
            if attempt == retries - 1:
                raise
            time.sleep((2 ** attempt) + random.random())

Cap the total attempts so a broken request cannot loop forever, and log each attempt with the model and prompt hash so you can see whether a specific variant is flaky.

Fall back deliberately

If a variant is consistently failing, falling back to another member of the family keeps the pipeline alive. Because all three share a request shape, a fallback is just a different model value on the retry. Decide the order in advance — for example, move from nano-banana-pro to nano-banana-2 when the high-fidelity call fails repeatedly — and record when a fallback fired so you notice patterns.

Make failures visible

Validate the returned payload before storing it, and emit a metric on retries and fallbacks. When error rates climb, you want to know it before a batch job silently produces blanks.

Hardening before you ship

Before you put image generation in front of users, run through this checklist.

Confirm IDs and parameters

Model identifiers change. Re-check the current model names for the Nano Banana family, and confirm every optional parameter against the live docs. Do not ship values that only exist in an old example.

Centralize configuration

Keep model IDs, prompt templates, and retry limits in one config module. When you promote a prompt from nano-banana to nano-banana-pro, that should be a config change, not a code change scattered across files.

Log what matters

For every call, log the model, prompt version, response status, latency, and whether a retry or fallback occurred. Hash long prompts so logs stay readable. This is what makes it possible to answer "why did this image look different yesterday?"

Monitor usage as you scale

Because billing follows usage, watch the number of calls and the variant mix. A single quiet escalation to nano-banana-pro on every request can turn an exploratory tool into a cost problem. Route deliberately: cheap variants for iteration, stronger ones for final output.

Test the endpoints

Write a small smoke test that calls each variant once with a fixed prompt and asserts a valid response. Run it against current docs before each release so a model change never surprises you in production.

Ship with a single client, a shared prompt library, and an intentional routing policy, and the Nano Banana family on HiAPI becomes one dependency you can scale from drafts to final renders without rewriting your integration.