> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana 2.1 API: Image Generation & Editing

> Generate and edit images with up to 10 references and 1K, 2K, or 4K output

## Overview

Nano Banana 2.1 supports text-to-image generation and reference-guided image editing. It accepts flexible aspect ratios, up to 10 reference images in image-to-image mode, and 1K, 2K, or 4K output.

| Capability | Value |
| - | - |
| Model ID | `nano-banana-2-1` |
| Modes | `text-to-image`, `image-to-image` |
| Prompt length | 1-20,000 characters |
| Reference images | Required for `image-to-image`; up to 10 URLs |
| Aspect ratios | `auto`, `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| Resolution tiers | `1K`, `2K`, `4K` |
| Output formats | `jpg`, `jpeg`, `png` |

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint | Purpose |
| - | - | - |
| `POST` | `/generateTask/nano-banana-2-1` | Submit a generation task |
| `GET` | `/statusTask/nano-banana-2-1?taskId={taskId}` | Poll task status and retrieve results |

All requests require your APIXO API key:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

This request submits a text-to-image task and returns a `taskId`.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/nano-banana-2-1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-image",
      "prompt": "A cinematic banana-shaped spaceship above a neon city",
      "aspect_ratio": "16:9",
      "resolution": "2K",
      "output_format": "jpg"
    }
  }'
```

Successful response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
```

Save the `taskId`; you need it to poll for the final result.

## Poll for result

```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/nano-banana-2-1?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Processing response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "processing",
    "createTime": 1791469979361
  }
}
```

Success response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/xxx.jpg\"]}",
    "createTime": 1791469979361,
    "completeTime": 1791470020749,
    "costTime": 41388
  }
}
```

Failed response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "SensitiveContent",
    "failMsg": "Content violates safety policy, please adjust the prompt",
    "createTime": 1791469979361,
    "completeTime": 1791469990132
  }
}
```

Parse `resultJson` after `state` becomes `success`:

```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;
```

## Request body

### Text-to-image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "A warm editorial portrait with soft window light",
    "aspect_ratio": "4:5",
    "resolution": "2K",
    "output_format": "png"
  }
}
```

### Image-to-image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "image-to-image",
    "prompt": "Keep the subject and change the background to a snowy mountain",
    "image_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "3:2",
    "resolution": "4K",
    "output_format": "jpg"
  }
}
```

## Parameters

<ParamField body="request_type" type="string" default="async">
  Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
</ParamField>

<ParamField body="callback_url" type="string">
  Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks).
</ParamField>

<ParamField body="input" type="object" required>
  Nano Banana 2.1 input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" required>
      Generation mode. Supported values: `text-to-image`, `image-to-image`.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Text prompt describing the desired image or edit. Leading and trailing whitespace is ignored for validation. Supports 1-20,000 characters.
    </ParamField>

    <ParamField body="image_urls" type="string[]">
      Reference image URLs. Required for `image-to-image`; provide 1-10 public, directly fetchable image URLs. Optional in `text-to-image` mode.
    </ParamField>

    <ParamField body="aspect_ratio" type="string" default="1:1">
      Output aspect ratio. Supported values: `auto`, `1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
    </ParamField>

    <ParamField body="resolution" type="string" default="1K">
      Output resolution tier. Supported values: `1K`, `2K`, `4K`. Values are case-insensitive.
    </ParamField>

    <ParamField body="output_format" type="string" default="jpg">
      Output image format. Supported values: `jpg`, `jpeg`, `png`. `jpeg` is accepted as an alias for `jpg`.
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  `image_urls` is required only when `mode` is `image-to-image`. When omitted, `aspect_ratio`, `resolution`, and `output_format` default to `1:1`, `1K`, and `jpg`.
</Note>

## Response format

### Submit task response

`POST /generateTask/nano-banana-2-1` returns a task ID when the task is accepted:

<ResponseField name="code" type="integer">
  API status code. `200` means the task was accepted.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="data.taskId" type="string">
  Unique task identifier used with the status endpoint.
</ResponseField>

### Status response fields

<ResponseField name="taskId" type="string">
  Unique task identifier.
</ResponseField>

<ResponseField name="state" type="string">
  Current task state: `pending`, `processing`, `success`, or `failed`.
</ResponseField>

<ResponseField name="resultJson" type="string">
  JSON string containing a `resultUrls` array. Present when `state` is `success`.
</ResponseField>

<ResponseField name="failCode" type="string">
  Machine-readable failure code. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="failMsg" type="string">
  Human-readable failure message. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="createTime" type="integer">
  Task creation timestamp in Unix milliseconds.
</ResponseField>

<ResponseField name="completeTime" type="integer">
  Task completion timestamp in Unix milliseconds. Present after completion.
</ResponseField>

<ResponseField name="costTime" type="integer">
  Processing duration in milliseconds. Present after successful completion when available.
</ResponseField>

## Webhook callback mode

Use callback mode when your backend should receive the final result automatically instead of polling.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/nano-banana-2-1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/webhooks/apixo",
    "input": {
      "mode": "image-to-image",
      "prompt": "Turn this product photo into a polished studio ad",
      "image_urls": [
        "https://example.com/product.png"
      ],
      "aspect_ratio": "1:1",
      "resolution": "2K",
      "output_format": "png"
    }
  }'
```

See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior.

## Billing

Nano Banana 2.1 is billed per generated image. The selected `resolution` determines the unit price.

| Resolution | APIXO price |
| - | -: |
| `1K` | `$0.04 / image` |
| `2K` | `$0.06 / image` |
| `4K` | `$0.135 / image` |

For current published pricing, see [Pricing](https://apixo.ai/pricing).

## Latency and polling

Actual latency varies by prompt complexity, reference image accessibility, resolution, and current queue load.

| Stage | Guidance |
| - | - |
| First poll | Wait 10s-20s after task creation before the first status request |
| Poll interval | Poll every 10s while `state` is `pending` or `processing` |
| Production delivery | Use callback mode for high-concurrency workloads |

<Tip>
  Download and store important outputs promptly instead of relying on result URLs as permanent storage.
</Tip>

Rate limits and concurrency vary by account and API key. If you receive `429`, slow down requests and retry with backoff.

## Errors and troubleshooting

### HTTP errors

| Code | Meaning | What to do |
| - | - | - |
| `400` | Invalid request body, mode, parameter, or image URL shape | Fix the request before retrying |
| `401` | Missing or invalid API key | Check the `Authorization` header |
| `402` | Insufficient balance or quota | Add balance or switch account/key |
| `403` | Your key cannot access the model | Check account permissions |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error | Retry with backoff |
| `502` | Generation service error | Retry with backoff |
| `504` | Generation timeout | Retry or use callback mode for long-running jobs |

### Task failure codes

| Fail code | Meaning | What to do |
| - | - | - |
| `PromptInvalid` | Prompt was invalid or rejected | Revise the prompt |
| `SensitiveContent` | Prompt, reference, or output violated safety policy | Change the prompt or reference image |
| `ImageFormatIncorrect` | A reference image could not be processed | Use a public, directly fetchable image URL in a common image format |
| `MissingParameter` | A required parameter was missing | Check `mode`, `prompt`, and `image_urls` when editing |
| `RateLimited` | Generation capacity was temporarily limited | Retry with backoff |
| `Timeout` | Generation timed out | Retry or use callback mode |
| `Unknown error` | The failure did not match a known rule | Retry with backoff or contact support with the `taskId` |

See [Error Codes](/docs/api-reference/errors) for the full error reference.

## Related links

* [Generation API Overview](/docs/models)
* [Image Models](/docs/models/image)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Error Codes](/docs/api-reference/errors)
* [Nano Banana](/docs/models/image/nano-banana)
* [Nano Banana Pro](/docs/models/image/nano-banana-pro)
* [Nano Banana 2](/docs/models/image/nano-banana-2)
* [Try Nano Banana 2.1 in the APIXO Playground](https://apixo.ai/models/nano-banana-2-1)
* [Pricing](https://apixo.ai/pricing)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.