# Nano Banana API

> Provider: **Google**
> Source: https://www.pixazo.ai/models/nano-banana

Advanced image generation and editing by Google.

## Nano Banana 2

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/nano-banana-2/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Image Request - Nano Banana 2

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/nano-banana-2/v1/nano-banana-2/generate
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "Photorealistic DSLR portrait of a man wearing a black cap, standing in a lush green park with trees and soft sunlight, natural lighting, realistic skin texture, shallow depth of field, ultra-detailed, no stylization.",
  "aspect_ratio": "1:1"
}
```

```
import requests

url = "https://gateway.pixazo.ai/nano-banana-2/v1/nano-banana-2/generate"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Photorealistic DSLR portrait of a man wearing a black cap, standing in a lush green park with trees and soft sunlight, natural lighting, realistic skin texture, shallow depth of field, ultra-detailed, no stylization.",
    "aspect_ratio": "1:1"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/nano-banana-2/v1/nano-banana-2/generate';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY'
};
const data = {
  prompt: 'APhotorealistic DSLR portrait of a man wearing a black cap, standing in a lush green park with trees and soft sunlight, natural lighting, realistic skin texture, shallow depth of field, ultra-detailed, no stylization.',
  aspect_ratio: '1:1'
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/nano-banana-2/v1/nano-banana-2/generate" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "Photorealistic DSLR portrait of a man wearing a black cap, standing in a lush green park with trees and soft sunlight, natural lighting, realistic skin texture, shallow depth of field, ultra-detailed, no stylization.",
    "aspect_ratio": "1:1"
  }'
```

## Output

```
{
  "request_id": "nano-banana-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=nano-banana-2&operation=image-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Image Request

Parameter

Required

Type

Description

prompt

Yes

string

Text description of the image to generate

image\_input

No

array of URIs

Input images to transform or use as reference (up to 14 images)

aspect\_ratio

No

string

Aspect ratio: "match\_input\_image", "1:1", "1:4", "1:8", "2:3", "3:2", "3:4", "4:1", "4:3", "4:5", "5:4", "8:1", "9:16", "16:9", "21:9"

resolution

No

string

Resolution: "1K", "2K", "4K". Higher resolutions take longer

google\_search

No

boolean

Use Google Web Search grounding for real-time information

image\_search

No

boolean

Use Google Image Search grounding for visual context

output\_format

No

string

Output format: "jpg", "png"

webhook

No

string

Webhook URL for async notifications when generation completes

webhook\_events\_filter

No

array

Event types to receive (e.g. \["completed"\])

## Example Request

```
{
  "prompt": "APhotorealistic DSLR portrait of a man wearing a black cap, standing in a lush green park with trees and soft sunlight, natural lighting, realistic skin texture, shallow depth of field, ultra-detailed, no stylization.",
  "image_input": ["https://example.com/reference-image.jpg"],
  "aspect_ratio": "1:1",
  "resolution": "4K",
  "google_search": false,
  "image_search": false,
  "output_format": "png",
  "webhook": "https://your-webhook.com/callback",
  "webhook_events_filter": ["completed"]
}
```

## Response

```
{
  "request_id": "nano-banana-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'nano-banana-2' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "nano-banana-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "nano-banana-2",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/nano-banana-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "nano-banana-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "nano-banana-2",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/nano-banana-2_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

## Nano Banana Standard

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/nano-banana/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Edit Image Request - Nano Banana API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/nano-banana/v1/nano-banana/generateEditImageRequest
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "Add a sunset background to the beach photo",
  "image_urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "num_images": 1,
  "output_format": "jpeg",
  "sync_mode": false
}
```

```
import requests

url = "https://gateway.pixazo.ai/nano-banana/v1/nano-banana/generateEditImageRequest"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "Add a sunset background to the beach photo",
    "image_urls": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg"
    ],
    "num_images": 1,
    "output_format": "jpeg",
    "sync_mode": False
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/nano-banana/v1/nano-banana/generateEditImageRequest';

const data = {
  prompt: 'Add a sunset background to the beach photo',
  image_urls: [
    'https://example.com/image1.jpg',
    'https://example.com/image2.jpg'
  ],
  num_images: 1,
  output_format: 'jpeg',
  sync_mode: false
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -v -X POST "https://gateway.pixazo.ai/nano-banana/v1/nano-banana/generateEditImageRequest" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
--data-raw '{
  "prompt": "Add a sunset background to the beach photo",
  "image_urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "num_images": 1,
  "output_format": "jpeg",
  "sync_mode": false
}'
```

## Output

```
{
  "request_id": "nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=nano-banana&operation=edit-image-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Edit Image Request

Parameter

Required

Type

Description

prompt

Yes

string

The prompt for image editing. Google's state-of-the-art image editing model that modifies existing images based on text descriptions

image\_urls

Yes

array<string>

List of URLs of input images for editing. The images will be edited according to the provided prompt

num\_images

Optional

integer

The number of edited images to generate

output\_format

Optional

string

The format of the generated images. Values: "jpeg", "png"

sync\_mode

Optional

boolean

When true, edited images will be returned as data URIs instead of URLs

## Example Request

```
{
  "prompt": "Add a sunset background to the beach photo",
  "image_urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "num_images": 1,
  "output_format": "jpeg",
  "sync_mode": false
}
```

## Response

```
{
  "request_id": "nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'nano-banana' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "nano-banana",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "nano-banana",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/nano-banana_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/nano-banana/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Text To Image Request - Nano Banana API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/nano-banana/v1/nano-banana/generateTextToImageRequest
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "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.",
  "num_images": 1,
  "limit_generations": false,
  "output_format": "jpeg",
  "aspect_ratio": "16:9",
  "sync_mode": false
}
```

```
import requests

url = "https://gateway.pixazo.ai/nano-banana/v1/nano-banana/generateTextToImageRequest"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "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.",
    "num_images": 1,
    "limit_generations": False,
    "output_format": "jpeg",
    "aspect_ratio": "16:9",
    "sync_mode": False
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/nano-banana/v1/nano-banana/generateTextToImageRequest';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  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.',
  num_images: 1,
  limit_generations: false,
  output_format: 'jpeg',
  aspect_ratio: '16:9',
  sync_mode: false
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -v -X POST "https://gateway.pixazo.ai/nano-banana/v1/nano-banana/generateTextToImageRequest" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
--data-raw '{
  "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.",
  "num_images": 1,
  "limit_generations": false,
  "output_format": "jpeg",
  "aspect_ratio": "16:9",
  "sync_mode": false
}'
```

## Output

```
{
  "request_id": "nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=nano-banana&operation=text-to-image-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Text To Image Request

Parameter

Required

Type

Description

prompt

Yes

string

The prompt for image generation. Google's state-of-the-art image generation model that generates high-quality images based on text descriptions

num\_images

No

integer

The number of images to generate

limit\_generations

No

boolean

Experimental parameter to limit the number of generations from each round of prompting to 1. Set to True to disregard any instructions in the prompt regarding the number of images to generate

output\_format

No

string

The format of the generated images. Values: "jpeg", "png", "webp"

aspect\_ratio

No

string

Aspect ratio for generated images. Values: "21:9", "1:1", "4:3", "3:2", "2:3", "5:4", "4:5", "3:4", "16:9", "9:16"

sync\_mode

No

boolean

If True, the media will be returned as a data URI and the output data won't be available in the request history

## Example Request

```
{
  "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.",
  "num_images": 1,
  "limit_generations": false,
  "output_format": "jpeg",
  "aspect_ratio": "16:9",
  "sync_mode": false
}
```

## Response

```
{
  "request_id": "nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'nano-banana' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "nano-banana",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "nano-banana_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "nano-banana",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/nano-banana_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Image (Image Editing — Batch)

## Base URL

```
https://gateway.pixazo.ai/nano-banana-async/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Image to Image(Edit Image) - Nano Banana Async API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/nano-banana-async/v1/nano-banana-image-to-image
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "Convert to watercolor",
  "image_urls": ["https://example.com/image.jpg"]
}
```

```
import requests

url = "https://gateway.pixazo.ai/nano-banana-async/v1/nano-banana-image-to-image"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "Convert to watercolor",
    "image_urls": ["https://example.com/image.jpg"]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/nano-banana-async/v1/nano-banana-image-to-image';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const body = {
  prompt: 'Convert to watercolor',
  image_urls: ['https://example.com/image.jpg']
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(body)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -v -X POST "https://gateway.pixazo.ai/nano-banana-async/v1/nano-banana-image-to-image" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "Convert to watercolor",
    "image_urls": ["https://example.com/image.jpg"]
  }'
```

## Output

```
{
  "request_id": "nano-banana-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=nano-banana-async-api&operation=image-to-image-edit-image)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Image to Image(Edit Image)

Parameter

Required

Type

Description

prompt

Yes

string

Text description of the desired transformation (required)

image\_urls

Yes

string\[\]

Array of input image URLs (1-3 images, required)

num\_images

No

integer

Number of image variations to generate (1-10)

aspect\_ratio

No

string

Image aspect ratio (see options below)

output\_format

No

string

Output format: "jpeg", "png", or "webp"

resolution

No

string

Image resolution: "1K" or "2K"

enable\_web\_search

No

boolean

Enable Google Search grounding for more accurate results

sync\_mode

No

boolean

Return base64 data URIs instead of R2 URLs

webhook

No

string

Webhook URL for automatic completion notifications

## Example Request

```
{
  "prompt": "Transform into a detailed watercolor painting with soft brush strokes and vibrant colors",
  "image_urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg",
    "https://example.com/image3.jpg"
  ],
  "num_images": 1,
  "aspect_ratio": "21:9",
  "output_format": "png",
  "resolution": "2K",
  "enable_web_search": true,
  "sync_mode": false,
  "webhook": "https://your-domain.com/api/webhook/gemini"
}
```

## Response

```
{
  "request_id": "nano-banana-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'nano-banana-async-api' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "nano-banana-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "nano-banana-async-api",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/nano-banana-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "nano-banana-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "nano-banana-async-api",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/nano-banana-async-api_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

## Nano Banana Pro

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/nano-banana-pro-770/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Generate Request - Nano Banana Pro API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/nano-banana-pro-770/v1/nano-banana-pro-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "make a photo of the man driving the car down the california coastline",
  "image_urls": [
    "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png",
    "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input-2.png"
  ]
}
```

```
import requests

url = "https://gateway.pixazo.ai/nano-banana-pro-770/v1/nano-banana-pro-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "make a photo of the man driving the car down the california coastline",
    "image_urls": [
        "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png",
        "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input-2.png"
    ]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/nano-banana-pro-770/v1/nano-banana-pro-request';

const data = {
  prompt: 'make a photo of the man driving the car down the california coastline',
  image_urls: [
    'https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png',
    'https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input-2.png'
  ]
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/nano-banana-pro-770/v1/nano-banana-pro-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "make a photo of the man driving the car down the california coastline",
    "image_urls": [
      "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png",
      "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input-2.png"
    ]
  }'
```

## Output

```
{
  "request_id": "nano-banana-pro-770_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana-pro-770_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=nano-banana-pro-770-api&operation=nano-banana-pro-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Generate Request

Parameter

Required

Type

Description

prompt

Yes

string

The prompt describing the desired image edit or transformation. Clearly specify what should be changed, added, or preserved in the input images.

image\_urls

Yes

array<string>

List of HTTPS URLs of images used for image-to-image generation or editing. Images must be publicly accessible.

num\_images

No

integer

Number of images to generate.

aspect\_ratio

No

string

Aspect ratio of the generated image. Possible values: auto, 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16.

output\_format

No

string

Output image format. Possible values: jpeg, png, webp.

resolution

No

string

Resolution of the generated image. Possible values: 1K, 2K, 4K.

sync\_mode

No

boolean

If true, the generated image is returned as a data URI and not stored in request history.

limit\_generations

No

boolean

Experimental parameter that limits the number of generations per prompt round to 1. When set to true, any instructions in the prompt requesting multiple images are ignored.

enable\_web\_search

No

boolean

Enables web search during image generation, allowing the model to use up-to-date information from the web.

## Example Request

```
{
  "prompt": "make a photo of the man driving the car down the california coastline",
  "image_urls": [
    "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png",
    "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input-2.png"
  ]
}
```

## Response

```
{
  "request_id": "nano-banana-pro-770_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana-pro-770_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'nano-banana-pro-770' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "nano-banana-pro-770_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "nano-banana-pro-770",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/nano-banana-pro-770_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "nano-banana-pro-770_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "nano-banana-pro-770",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/nano-banana-pro-770_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Image (Image Editing — Batch)

## Base URL

```
https://gateway.pixazo.ai/nano-banana-pro-async/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Image to Image(Edit Image) - Nano Banana Pro Async API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/nano-banana-pro-async/v1/nano-banana-pro-image-to-image
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "Convert tree flower to yellow saffron",
  "image_urls": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f2.png"]
}
```

```
import requests

APIM_KEY = 'YOUR_SUBSCRIPTION_KEY'
BASE_URL = 'https://gateway.pixazo.ai/nano-banana-pro-async/v1'

headers = {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': APIM_KEY
}

response = requests.post(
    f'{BASE_URL}/nano-banana-pro-image-to-image',
    headers=headers,
    json={
        'prompt': 'Convert tree flower to yellow saffron',
        'image_urls': ['https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f2.png']
    }
)

data = response.json()
print(data)
```

```
const APIM_KEY = 'YOUR_SUBSCRIPTION_KEY';
const BASE_URL = 'https://gateway.pixazo.ai/nano-banana-pro-async/v1';

async function generateTransformation() {
  const response = await fetch(`${BASE_URL}/nano-banana-pro-image-to-image`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-cache',
      'Ocp-Apim-Subscription-Key': APIM_KEY
    },
    body: JSON.stringify({
      prompt: 'Convert tree flower to yellow saffron',
      image_urls: ['https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f2.png']
    })
  });

  const data = await response.json();
  console.log('Task Started:', data.taskId);
}
```

```
curl -v -X POST "https://gateway.pixazo.ai/nano-banana-pro-async/v1/nano-banana-pro-image-to-image" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "Convert tree flower to yellow saffron",
    "image_urls": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f2.png"]
  }'
```

## Output

```
{
  "request_id": "nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=nano-banana-pro-async-api&operation=image-to-image)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Image to Image(Edit Image)

Parameter

Required

Type

Description

prompt

Yes

string

Text description of the desired transformation (required)

image\_urls

Yes

string\[\]

Array of input image URLs (1-5 images required)

num\_images

No

integer

Number of image variations to generate (1-10)

aspect\_ratio

No

string

Output image aspect ratio (see options below)

resolution

No

string

Output image resolution: "1K", "2K", or "4K"

enable\_web\_search

No

boolean

Enable Google Search grounding for more accurate results

sync\_mode

No

boolean

Return base64 data URIs instead of R2 URLs

webhook

No

string

Webhook URL for automatic completion notifications

## Example Request

```
{
  "prompt": "Transform into cyberpunk style with neon lights and holographic effects",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f2.png"
  ],
  "num_images": 3,
  "aspect_ratio": "16:9",
  "resolution": "1K",
  "enable_web_search": true,
  "sync_mode": false,
  "webhook": "https://your-domain.com/api/webhook/gemini"
}
```

## Response

```
{
  "request_id": "nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'nano-banana-pro-async-api' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "nano-banana-pro-async-api",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "nano-banana-pro-async-api",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/nano-banana-pro-async-api_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Text to Image (Batch)

## Base URL

```
https://gateway.pixazo.ai/nano-banana-pro-async/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Text to Image - Nano Banana Pro Async API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/nano-banana-pro-async/v1/nano-banana-pro-text-to-image
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "A cute robot"
}
```

```
import requests

APIM_KEY = 'YOUR_SUBSCRIPTION_KEY'
BASE_URL = 'https://gateway.pixazo.ai/nano-banana-pro-async/v1'

headers = {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': APIM_KEY
}

response = requests.post(
    f'{BASE_URL}/nano-banana-pro-text-to-image',
    headers=headers,
    json={
        'prompt': 'A cute robot'
    }
)

data = response.json()
print('Task ID:', data['taskId'])
```

```
// Node.js example
const APIM_KEY = 'YOUR_SUBSCRIPTION_KEY';
const BASE_URL = 'https://gateway.pixazo.ai/nano-banana-pro-async/v1';

async function generateImage() {
  const response = await fetch(`${BASE_URL}/nano-banana-pro-text-to-image`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-cache',
      'Ocp-Apim-Subscription-Key': APIM_KEY
    },
    body: JSON.stringify({
      prompt: 'A cute robot'
    })
  });

  const data = await response.json();
  console.log('Image generation started!');
  console.log('Task ID:', data.taskId);
}

generateImage();
```

```
curl -X POST "https://gateway.pixazo.ai/nano-banana-pro-async/v1/nano-banana-pro-text-to-image" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A cute robot"
  }'
```

## Output

```
{
  "request_id": "nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=nano-banana-pro-async-api&operation=text-to-image)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Text to Image

Parameter

Required

Type

Description

prompt

Yes

string

Text description of the desired image (required)

num\_images

No

integer

Number of image variations to generate (1-10)

aspect\_ratio

No

string

Image aspect ratio (see options below)

resolution

No

string

Image resolution: "1K", "2K", or "4K"

enable\_web\_search

No

boolean

Enable Google Search grounding for more accurate results

sync\_mode

No

boolean

Return base64 data URIs instead of R2 URLs

webhook

No

string

Webhook URL for automatic completion notifications

## Example Request

```
{
  "prompt": "A futuristic city on Mars with flying cars and neon lights at sunset",
  "num_images": 4,
  "aspect_ratio": "16:9",
  "resolution": "4K",
  "enable_web_search": true,
  "sync_mode": false,
  "webhook": "https://your-domain.com/api/webhook/gemini"
}
```

## Response

```
{
  "request_id": "nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'nano-banana-pro-async-api' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "nano-banana-pro-async-api",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "nano-banana-pro-async-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "nano-banana-pro-async-api",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/nano-banana-pro-async-api_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.