# Nano Banana Pro

> Google's advanced Gemini 3 Pro image model featuring 4K resolution, enhanced reasoning, real-time data integration, and multi-image composition capabilities.

## Overview

- Submit: `https://api.poyo.ai/api/generate/submit`
- Status: `https://api.poyo.ai/api/generate/status/{task_id}`
- Page: https://poyo.ai/models/nano-banana-2-api
- Model page ID: `nano-banana-2-api`
- API model IDs: `nano-banana-pro`, `nano-banana-pro-edit`, `nano-banana-2`, `nano-banana-2-edit`
- Category: Image
- Auth: `Authorization: Bearer $POYO_API_KEY`
- Create a key at https://poyo.ai/dashboard/api-key

This model uses PoYo's unified async API. POST the JSON body below, then poll status with the returned `task_id` or receive a webhook on `callback_url`. Failed tasks are not charged.

## Pricing

- nano-banana-pro@1K/2K: 8 credits ($0.040) per generation
- nano-banana-pro@4K: 14 credits ($0.070) per generation
- nano-banana-pro-official@1K/2K: 18 credits ($0.090) per generation
- nano-banana-pro-official@4K: 35 credits ($0.175) per generation

For more details, see https://poyo.ai/models/nano-banana-2-api.

## API Information

The request envelope is always `{ model, input, callback_url? }`. Input fields below are nested under `input`.

### Request envelope

- `model` (`ModelEnum`, required):
  Nano Banana model identifier
  - Options: `"nano-banana-2"`, `"nano-banana-2-edit"`, `"nano-banana-pro"`, `"nano-banana-pro-edit"`
- `callback_url` (`string`, optional):
  Webhook callback URL for result notifications
  - Examples: "https://your-domain.com/callback"

### Input Schema

Input parameters for generation

The API accepts the following `input` parameters:

- `prompt` (`string`, required):
  Generation prompt describing the desired output
  - Length: 0 to 10000 characters
  - Examples: "A beautiful sunset over the ocean"
- `image_urls` (`list`, optional):
  Reference image URLs (required for edit models, Nano Banana Pro edit supports up to 14 images)
  - Array of string
  - Examples: `[]`
- `size` (`SizeEnum`, optional):
  Image size ratio. Nano Banana Pro also supports `auto` and defaults to `auto`.
  - Options: `"auto"`, `"1:1"`, `"2:3"`, `"3:2"`, `"3:4"`, `"4:3"`, `"4:5"`, `"5:4"`, `"9:16"`, `"16:9"`, `"21:9"`
  - Examples: "auto"
- `resolution` (`ResolutionEnum`, optional):
  Output image resolution
  - Default: `"1K"`
  - Options: `"1K"`, `"2K"`, `"4K"`
  - Examples: "1K"
- `n` (`NEnum`, optional):
  Number of output images. Current supported value is `1`.
  - Default: `1`
  - Options: `1`
  - Examples: `1`
- `output_format` (`OutputFormatEnum`, optional):
  Nano Banana Pro only. Output image format.
  - Default: `"png"`
  - Options: `"png"`, `"jpg"`
  - Examples: "png"
- `enable_web_search` (`boolean`, optional):
  Nano Banana Pro only. Enable web search before generation.
  - Default: `false`
  - Examples: `false`

Required Parameters Example:

```json
{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A cyberpunk street scene with neon signs and rain",
    "size": "16:9",
    "resolution": "2K"
  }
}
```

Full Example:

```json
{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A cyberpunk street scene with neon signs and rain",
    "size": "16:9",
    "resolution": "2K",
    "image_urls": [],
    "n": 1,
    "output_format": "png",
    "enable_web_search": false
  }
}
```

Nano Banana 2 Image Edit:

```json
{
  "model": "nano-banana-2-edit",
  "input": {
    "prompt": "Add colorful flowers in the foreground",
    "image_urls": [
      "https://example.com/landscape.jpg"
    ],
    "size": "16:9",
    "resolution": "2K"
  }
}
```

Nano Banana Pro Image Generation:

```json
{
  "model": "nano-banana-pro",
  "input": {
    "prompt": "An action shot of a black lab swimming in an inground suburban swimming pool. The camera is placed meticulously on the water line, dividing the image in half, revealing both the dogs head above water holding a tennis ball in it's mouth, and it's paws paddling underwater.",
    "resolution": "1K",
    "size": "auto",
    "n": 1,
    "output_format": "png",
    "enable_web_search": false
  }
}
```

### Output Schema

Submit returns a `task_id`. Poll `GET /api/generate/status/{task_id}` until `status` is `finished` or `failed`. Completed media is in `data.files`.

Response fields:

- `code` (`CodeEnum`, required):
  Business status code. `200` means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with `code: 400` in the body.
  
  - `200`: Success
  - `400`: Invalid request parameters
  - `401`: Missing or invalid API key
  - `402`: Insufficient credits
  - `403`: Permission denied
  - `404`: Resource not found
  - `408`: Request timeout
  - `429`: Rate limit exceeded
  - `500`: Internal server error
  - `502`: Upstream service error
  - `503`: Service unavailable
  
  See [Error Codes](/api-manual/error-codes) for details.
  - Options: `200`, `400`, `401`, `402`, `403`, `404`, `408`, `429`, `500`, `502`, `503`
  - Examples: `200`
- `data` (`object`, required):

Example Response:

```json
{
  "code": 200,
  "data": {
    "task_id": "task_example",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.poyo.ai/nano-banana-2-api/examples/nano-banana-2-product-mug.png",
        "file_type": "image"
      }
    ]
  }
}
```

## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"nano-banana-2","input":{"prompt":"A cyberpunk street scene with neon signs and rain","size":"16:9","resolution":"2K"}}'
```

### Python

```python
import json
import os
import time
import requests

API = "https://api.poyo.ai"
headers = {
    "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
    "Content-Type": "application/json",
}
payload = json.loads("{\n  \"model\": \"nano-banana-2\",\n  \"input\": {\n    \"prompt\": \"A cyberpunk street scene with neon signs and rain\",\n    \"size\": \"16:9\",\n    \"resolution\": \"2K\"\n  }\n}")

submit = requests.post(f"{API}/api/generate/submit", headers=headers, json=payload)
submit.raise_for_status()
task_id = submit.json()["data"]["task_id"]

while True:
    status = requests.get(f"{API}/api/generate/status/{task_id}", headers=headers)
    status.raise_for_status()
    data = status.json()["data"]
    if data["status"] in ("finished", "failed"):
        print(data)
        break
    time.sleep(2)
```

### JavaScript

```javascript
const headers = {
  Authorization: `Bearer ${process.env.POYO_API_KEY}`,
  "Content-Type": "application/json",
};

const submit = await fetch("https://api.poyo.ai/api/generate/submit", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "nano-banana-2",
  "input": {
    "prompt": "A cyberpunk street scene with neon signs and rain",
    "size": "16:9",
    "resolution": "2K"
  }
}),
});

const submitted = await submit.json();
const taskId = submitted.data.task_id;

while (true) {
  const statusResponse = await fetch(`https://api.poyo.ai/api/generate/status/${taskId}`, { headers });
  const status = await statusResponse.json();
  if (["finished", "failed"].includes(status.data.status)) {
    console.log(status.data);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 2000));
}
```

## Additional Resources

### Documentation

- [Model Playground](https://poyo.ai/models/nano-banana-2-api)
- [API Documentation](https://docs.poyo.ai/api-manual/image-series/nano-banana-2)
- [API Documentation (Markdown)](https://docs.poyo.ai/api-manual/image-series/nano-banana-2.md)
- [Task status](https://docs.poyo.ai/api-manual/task-management/query-task-status)
- [Webhooks](https://docs.poyo.ai/api-manual/task-management/webhooks)

### Other agent-readable surfaces

- [Platform overview](https://poyo.ai/llms.txt)
- [Documentation index](https://docs.poyo.ai/llms.txt)
- [Full documentation text](https://docs.poyo.ai/llms-full.txt)
- Any other model: `https://poyo.ai/models/<model-id>/llms.txt`