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

# Nano Banana: Create an Async Image Generation Task

> POST /kyyReactApiServer/v1/banana/images — Submit an async Nano Banana image generation task. Supports up to 4K resolution and 6 reference images.

The Nano Banana image generation endpoint creates an async task that generates high-quality AI images from a text prompt. You'll receive a task ID to poll for the result. Because generation happens asynchronously, your application can continue doing other work while the image is being produced.

## Base URL

```
https://zcbservice.aizfw.cn/kyyReactApiServer
```

## Endpoint

```
POST /v1/banana/images
```

## Authentication

Include your API key as a Bearer token in the `Authorization` header on every request:

```
Authorization: Bearer YOUR_API_KEY
```

***

## Models

Choose the model that best fits your quality and speed requirements.

| Model                    | Description                            |
| ------------------------ | -------------------------------------- |
| `nano-banana`            | Base model, fast generation            |
| `nano-banana-2`          | Enhanced model with resolution support |
| `nano-banana-pro`        | Professional — up to 4K                |
| `nano-banana-2-stable`   | Stable version of nano-banana-2        |
| `nano-banana-pro-stable` | Stable professional version            |

***

## Request Parameters

<ParamField body="model" type="string" required>
  The model to use for image generation. See the Models table above for valid values.
</ParamField>

<ParamField body="prompt" type="string" required>
  A text description of the image you want to generate. Clear, descriptive prompts produce the best results. Example: `"A cute orange cat sitting on a windowsill, golden hour lighting"`.
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  The output resolution of the generated image. Defaults to `1k` for all models.

  | Value | Resolution                                                                  |
  | ----- | --------------------------------------------------------------------------- |
  | `1k`  | 1K resolution (default, supported by all models)                            |
  | `2k`  | 2K resolution (supported by `nano-banana-pro` and `nano-banana-pro-stable`) |
  | `4k`  | 4K resolution (supported by `nano-banana-pro` and `nano-banana-pro-stable`) |

  `nano-banana`, `nano-banana-2`, and `nano-banana-2-stable` have limited resolution capability — use `1k` for these models.
</ParamField>

<ParamField body="size" type="string">
  The aspect ratio of the generated image. If omitted, the model uses its default aspect ratio.

  Supported values: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9`
</ParamField>

<ParamField body="image_urls" type="array">
  An array of reference image URLs used to guide the style of the generated image. You may provide up to **6** images. Reference images are optional but can significantly improve style consistency.
</ParamField>

***

## Response Fields

<ResponseField name="id" type="string">
  The unique task ID for this generation job. Use this value to poll the [Query Image Task](/api-reference/image/nano-banana-query) endpoint for the result.
</ResponseField>

<ResponseField name="object" type="string">
  The object type. Always `nanobanana`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp indicating when the task was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model name used for this task.
</ResponseField>

<ResponseField name="status" type="string">
  The initial task status. Will be `queued` or `processing` immediately after creation.

  | Value        | Meaning                          |
  | ------------ | -------------------------------- |
  | `queued`     | Task is waiting in the queue     |
  | `processing` | Task is actively being processed |
</ResponseField>

<ResponseField name="error" type="string">
  An error message describing what went wrong. Only present when `status` is `failed`.
</ResponseField>

***

## Code Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://zcbservice.aizfw.cn/kyyReactApiServer/v1/banana/images \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "nano-banana-2",
      "prompt": "A cute orange cat sitting on a windowsill, golden hour lighting",
      "resolution": "2k",
      "size": "16:9"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://zcbservice.aizfw.cn/kyyReactApiServer/v1/banana/images"

  payload = {
      "model": "nano-banana-2",
      "prompt": "A cute orange cat sitting on a windowsill, golden hour lighting",
      "resolution": "2k",
      "size": "16:9"
  }

  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

### Success Response

```json theme={null}
{
  "id": "abc123",
  "object": "nanobanana",
  "created": 1761635478,
  "model": "nano-banana-2",
  "status": "queued"
}
```

### Failure Response

```json theme={null}
{
  "id": "abc123",
  "object": "nanobanana",
  "created": 1761635478,
  "model": "nano-banana-2",
  "status": "failed",
  "error": "Invalid prompt: content policy violation"
}
```

***

<Note>
  Image generation is processed **asynchronously**. The create endpoint returns a task `id` immediately — use that ID with the [Query Image Task](/api-reference/image/nano-banana-query) endpoint (`GET /v1/result/{id}`) to check task status and retrieve your image URL when generation is complete.
</Note>

<Tip>
  **Polling interval:** Check the task status every **2–5 seconds**. Polling too frequently may result in rate limiting, while longer intervals simply delay when you first see the result. Stop polling as soon as `status` is `completed` or `failed`.
</Tip>