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

# Create Nano Banana task

> 创建 GPT Image 2 或 Nano Banana 异步生图任务。

Create an async Nano Banana image task. Poll with [Query image task](/en/api-reference/images/query) and read `result.image_url` when completed.

For GPT Image 2, see [Create GPT Image 2 task](/en/api-reference/images/create).

## Models

| `model` | Notes | `resolution` | Billing key examples |
| - | - | - | - |
| `nano-banana-2` | Balanced; draft through 4K | `0.5k` / `1k` / `2k` / `4k` | `nanobanana2-1k` |
| `nano-banana-2.1` | Fast iteration with better detail and text | `1k` / `2k` / `4k` | `nanobanana2.1-2k` |
| `nano-banana-pro` | Commercial detail and lighting | `1k` / `2k` / `4k` | `nanobananapro-4k` |

Billing is by resolution (`per_task`, 1 image per request). Check [Model catalog](/en/api-reference/common/model-catalog) and the create response `cost` for live prices.

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `model` | string | yes | See table above |
| `prompt` | string | conditional | Required for text-to-image; optional when `images` is set. Up to **10000** characters |
| `n` | int | no | Always **1** |
| `ratio` | string | no | Aspect ratio; `size` is an alias. Common: `1:1` / `9:16` / `16:9` / `auto` |
| `size` | string | no | Alias of `ratio` |
| `resolution` | string | no | Resolution tier, default `1k` (see table) |
| `images` | string\[] | no | Public reference image URLs, max **5** |

## Examples

### Text-to-image (Nano Banana 2)

```bash theme={null}
curl -X POST 'https://sigrunai.com/v1/images' \
  -H 'Authorization: Bearer sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-2",
    "prompt": "Cinematic sunset over a lake, golden light on distant mountains",
    "ratio": "16:9",
    "resolution": "2k"
  }'
```

### Image-to-image (Nano Banana Pro)

```bash theme={null}
curl -X POST 'https://sigrunai.com/v1/images' \
  -H 'Authorization: Bearer sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "Keep the product look, switch to soft studio lighting",
    "ratio": "1:1",
    "resolution": "4k",
    "images": ["https://example.com/product.jpg"]
  }'
```

### Nano Banana 2.1

```bash theme={null}
curl -X POST 'https://sigrunai.com/v1/images' \
  -H 'Authorization: Bearer sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-2.1",
    "prompt": "Product poster with clear Chinese title, clean background",
    "ratio": "1:1",
    "resolution": "1k"
  }'
```

Success response:

```json theme={null}
{
  "code": 20000,
  "msg": "提交成功",
  "data": {
    "task_id": "img_xxxxxxxx",
    "status": "queued",
    "progress": 0,
    "model": "nanobanana2-2k",
    "cost": 0.05,
    "result": {}
  }
}
```


## OpenAPI

````yaml POST /v1/images
openapi: 3.1.0
info:
  title: AI Platform OpenAPI
  description: 异步图片与视频生成。创建后轮询 task_id；结果 URL 约保留 3 天。
  version: 1.0.0
servers:
  - url: https://sigrunai.com
    description: AI Platform 生产环境
security:
  - bearerAuth: []
paths:
  /v1/images:
    post:
      tags:
        - Images
      summary: Create image task
      description: Create an async GPT Image 2 or Nano Banana image task.
      operationId: createImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageCreateRequest'
            examples:
              gptImage2:
                summary: gpt-image-2
                value:
                  model: gpt-image-2
                  prompt: Minimal product still life, white background, soft light
                  quality: medium
                  'n': 1
                  ratio: '1:1'
              nanoBanana2:
                summary: nano-banana-2
                value:
                  model: nano-banana-2
                  prompt: >-
                    Cinematic sunset over a lake, golden light on distant
                    mountains
                  ratio: '16:9'
                  resolution: 2k
              nanoBananaPro:
                summary: nano-banana-pro
                value:
                  model: nano-banana-pro
                  prompt: Keep the product look, switch to soft studio lighting
                  ratio: '1:1'
                  resolution: 4k
                  images:
                    - https://example.com/product.jpg
      responses:
        '200':
          description: 提交成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskQueryResponse'
components:
  schemas:
    ImageCreateRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
          description: >-
            gpt-image-2 (plus low/medium/high) or nano-banana-2 /
            nano-banana-2.1 / nano-banana-pro
          example: nano-banana-2
        prompt:
          type: string
          minLength: 1
          maxLength: 10000
          description: >-
            GPT Image 2 max 4000; Nano Banana max 10000. Optional when images
            are provided
        quality:
          type: string
          enum:
            - auto
            - low
            - medium
            - high
          default: auto
        'n':
          type: integer
          minimum: 1
          maximum: 4
          default: 1
        ratio:
          type: string
        size:
          type: string
          description: ratio 别名
        resolution:
          type: string
          description: 'Nano Banana: 0.5k/1k/2k/4k depending on model'
        images:
          type: array
          items:
            type: string
            format: uri
          maxItems: 15
          description: Reference image URLs. GPT Image 2 max 15; Nano Banana max 5
    TaskQueryResponse:
      type: object
      properties:
        code:
          type: integer
          example: 20000
        msg:
          type: string
        data:
          $ref: '#/components/schemas/TaskQueryData'
    TaskQueryData:
      type: object
      properties:
        task_id:
          type: string
        status:
          type: string
          description: queued / processing / completed / failed 等
        progress:
          type: integer
        model:
          type: string
        created_at:
          type: integer
        completed_at:
          type: integer
        cost:
          type: number
        error_message:
          type: string
        result:
          $ref: '#/components/schemas/TaskResult'
    TaskResult:
      type: object
      properties:
        image_url:
          type: string
        video_url:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 控制台创建的 API Key，格式：Bearer sk_xxx

````

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