Skip to main content
POST
Generate image with Nano Banana 2.1

Authorizations

Authorization
string
header
required

API key as a bearer token: Authorization: Bearer bpx_live_xxx

Body

application/json
prompt
string
required

Text description of the image to generate, or of the edit to apply to the reference images.

aspect_ratio
enum<string>
default:auto

Output aspect ratio. "auto" (default) follows the first reference image when editing and gives a square image for text-to-image.

Available options:
auto,
1:1,
16:9,
9:16,
4:3,
3:4,
3:2,
2:3,
5:4,
4:5,
21:9,
1:4,
4:1,
1:8,
8:1

Ground the image in live Google Search results (weather, scores, recent events, current facts). Off by default. Adds 10 credits per image.

Let the model look up web images as visual context before rendering. Off by default. Runs a web search too, so it adds 20 credits per image in total, with or without google_search.

num_images
integer
default:1

Number of images to generate. Each image is billed at its size's price, plus search grounding if enabled.

Required range: 1 <= x <= 4
output_format
enum<string>
default:png

Output image format (default png, at full resolution). jpeg gives a much smaller file, but its long edge is limited to 4096 px, so a wide 4K image comes back smaller than its PNG (16:9 at 4K: 5504x3072 as PNG, about 25 MB; 4096x2286 as JPEG). Results generated with image_search are returned as JPEG regardless.

Available options:
png,
jpeg
reference_images
string[]

Optional reference images (up to 9) for image editing and multi-reference composition. Each item is a public image URL, a data URI, raw base64, or an uploaded-file URL from POST /v1/uploads. Omit for text-to-image. Reference images cost nothing extra.

Maximum array length: 9
size
enum<string>
default:1K

Output resolution tier. Sets the price: 1K = 45, 2K = 70, 4K = 150 credits per image.

Available options:
1K,
2K,
4K

Response

Job accepted.

id
string

Opaque job id — use it to poll status.

Example:

"img_a1b2c3d4e5f6"

message
string
model
string
status
enum<string>

Lifecycle state. succeeded/failed/timeout are terminal.

Available options:
pending,
starting,
processing,
completing,
succeeded,
failed,
timeout