Nano Banana 2.1 API

POST Base URL: https://api.hiapi.ai /v1/tasks

Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model	gemini-nano-banana-2.1
Use	Image generation and reference editing
Endpoint	POST /v1/tasks
Pricing	HiAPI

Create fashion portraits and interiors with Nano Banana 2.1. Try online, view real examples and edit reference photos through the HiAPI API.

Production guidance

For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

Photographic scenes and campaign layouts

Describe the subject, materials, camera, light and lettering to create a visual concept for the placement.

promptaspect_ratio

Reference-based garment editing

Supply an original image and specify changes and details to preserve.

promptimage_input

Request parameters

POST https://api.hiapi.ai/v1/tasks

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gemini-nano-banana-2.1",
  "input": {
    "prompt": "A fashion editorial photograph on a sunlit white-stucco terrace above the Mediterranean, shot at eye level with a 50mm lens. One adult woman in her late twenties is walking naturally toward the camera at the right-center of the composition, her head turned slightly toward the sea with a relaxed confident expression. She wears an oversized ivory linen blazer over a deep burgundy silk camisole, high-waisted navy tailored trousers, and simple leather sandals. Wind lifts a few strands of her dark shoulder-length hair and gently moves the blazer hem. A cobalt-blue glazed ceramic bench occupies the left foreground; beyond it, crisp ivory architecture frames a bright turquoise sea and a small distant headland. Directional late-afternoon sunlight reveals real skin texture, linen weave and silk highlights, with clean architectural shadows and controlled reflections. Rich but restrained cobalt, burgundy, ivory and warm skin tones, sophisticated magazine photography, believable proportions and hands, beautifully resolved clothing, candid physical movement, subtle film grain. The woman is the clear visual focus, with the surrounding terrace providing depth. No lettering, no logos, no watermark, no illustration, no CGI appearance, no airbrushed plastic skin.",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "gemini-nano-banana-2.1",
  "input": {
    "prompt": "A fashion editorial photograph on a sunlit white-stucco terrace above the Mediterranean, shot at eye level with a 50mm lens. One adult woman in her late twenties is walking naturally toward the camera at the right-center of the composition, her head turned slightly toward the sea with a relaxed confident expression. She wears an oversized ivory linen blazer over a deep burgundy silk camisole, high-waisted navy tailored trousers, and simple leather sandals. Wind lifts a few strands of her dark shoulder-length hair and gently moves the blazer hem. A cobalt-blue glazed ceramic bench occupies the left foreground; beyond it, crisp ivory architecture frames a bright turquoise sea and a small distant headland. Directional late-afternoon sunlight reveals real skin texture, linen weave and silk highlights, with clean architectural shadows and controlled reflections. Rich but restrained cobalt, burgundy, ivory and warm skin tones, sophisticated magazine photography, believable proportions and hands, beautifully resolved clothing, candid physical movement, subtle film grain. The woman is the clear visual focus, with the surrounding terrace providing depth. No lettering, no logos, no watermark, no illustration, no CGI appearance, no airbrushed plastic skin.",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gemini-nano-banana-2.1",
  "input": {
    "prompt": "A fashion editorial photograph on a sunlit white-stucco terrace above the Mediterranean, shot at eye level with a 50mm lens. One adult woman in her late twenties is walking naturally toward the camera at the right-center of the composition, her head turned slightly toward the sea with a relaxed confident expression. She wears an oversized ivory linen blazer over a deep burgundy silk camisole, high-waisted navy tailored trousers, and simple leather sandals. Wind lifts a few strands of her dark shoulder-length hair and gently moves the blazer hem. A cobalt-blue glazed ceramic bench occupies the left foreground; beyond it, crisp ivory architecture frames a bright turquoise sea and a small distant headland. Directional late-afternoon sunlight reveals real skin texture, linen weave and silk highlights, with clean architectural shadows and controlled reflections. Rich but restrained cobalt, burgundy, ivory and warm skin tones, sophisticated magazine photography, believable proportions and hands, beautifully resolved clothing, candid physical movement, subtle film grain. The woman is the clear visual focus, with the surrounding terrace providing depth. No lettering, no logos, no watermark, no illustration, no CGI appearance, no airbrushed plastic skin.",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Model ID to call.

example gemini-nano-banana-2.1

input object required

Image generation and editing parameters.

prompt string required

Describe the image or changes to reference images. Length: 1–20000 characters.

image_input string[] optional

Publicly accessible reference URLs for editing or blending. Up to 10 JPEG, PNG or WebP images, no larger than 30 MB each.

aspect_ratio enum optional

Controls the layout. auto chooses a ratio from the prompt and references.

default auto enum: 1:12:33:21:44:13:44:34:55:41:88:19:1616:921:9auto

resolution enum optional

Output resolution tier. Pixel dimensions depend on the aspect ratio.

default 1K enum: 1K2K4K

output_format enum optional

Image file format. PNG does not guarantee transparency.

default jpg enum: jpgpng

callback object optional

Terminal task notification configuration.

url string required

HTTPS URL that receives task notifications.

when enum optional

Notification trigger.

default final enum: final

Example requests

Coastal fashion editorial

Create a landscape fashion concept with a walking subject, tactile clothing and coastal daylight.

Request body

{
  "model": "gemini-nano-banana-2.1",
  "input": {
    "prompt": "A fashion editorial photograph on a sunlit white-stucco terrace above the Mediterranean, shot at eye level with a 50mm lens. One adult woman in her late twenties is walking naturally toward the camera at the right-center of the composition, her head turned slightly toward the sea with a relaxed confident expression. She wears an oversized ivory linen blazer over a deep burgundy silk camisole, high-waisted navy tailored trousers, and simple leather sandals. Wind lifts a few strands of her dark shoulder-length hair and gently moves the blazer hem. A cobalt-blue glazed ceramic bench occupies the left foreground; beyond it, crisp ivory architecture frames a bright turquoise sea and a small distant headland. Directional late-afternoon sunlight reveals real skin texture, linen weave and silk highlights, with clean architectural shadows and controlled reflections. Rich but restrained cobalt, burgundy, ivory and warm skin tones, sophisticated magazine photography, believable proportions and hands, beautifully resolved clothing, candid physical movement, subtle film grain. The woman is the clear visual focus, with the surrounding terrace providing depth. No lettering, no logos, no watermark, no illustration, no CGI appearance, no airbrushed plastic skin.",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }
}

Getting the result

The response returns a taskId immediately without waiting for generation to finish.
In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
When status=success, download the generated image from output[].url.
When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

How do I switch between generation and editing?

Use a prompt alone to generate an image. Add references and describe the requested changes and details to preserve for editing. Both use the same model ID. Tasks are independent; supply the previous result again to continue editing.

How should I use reference images?

Add up to 10 JPEG, PNG or WebP images. Assign each a subject, setting or style role and list details to preserve. URLs must be publicly accessible; API images must be no larger than 30 MB each.

How does auto choose the aspect ratio?

auto lets the model choose a layout from the prompt and references. Select an explicit ratio for a poster or advertising placement. Resolution tiers do not specify a fixed pixel width and height. Ratios guide composition; actual pixel ratios can vary, especially at 1:8 and 8:1. Check output dimensions before cropping for a fixed placement.

How can I make poster lettering easier to read?

Write each exact phrase, specify the position of the headline, label and subtitle, and exclude extra text. Check the completed image character by character, especially small type and long passages.

Can I request transparency or multiple images?

Each task generates one JPG or PNG image. A transparent-background switch and image-count parameter are not exposed. Choosing PNG does not guarantee transparency.

How do I retrieve and save results?

Save taskId, retrieve GET /v1/tasks/:id until completion, then read output[].url. You can also set callback.url for terminal notifications. Save results promptly if you need to retain them.