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

# Create image generation (Nano Banana Pro)

> Generate images with nano-banana-pro, with async tasks and per-resolution pricing.

`nano-banana-pro` is DimiLinks' image generation model, billed per resolution tier. Use async mode (`?async=true`): creation returns a `task_id`, then poll with [Retrieve image task](https://docs.dimilinks.com/en/api-reference/images/gpt-image-2/tasks.md) to fetch the result.

## Endpoint

```http theme={null}
POST https://api-direct.dimilinks.com/v1/images/generations?async=true
Content-Type: application/json
Authorization: Bearer <DIMILINKS_API_KEY>
```

## Text-to-image example

```bash theme={null}
curl "https://api-direct.dimilinks.com/v1/images/generations?async=true" \
  -H "Authorization: Bearer $DIMILINKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "A warm breakfast table close-up, natural light, shallow depth of field",
    "resolution": "2k",
    "size": "1:1"
  }'
```

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | yes | Always `nano-banana-pro`. |
| `prompt` | string | yes | Image description. |
| `resolution` | string | no | `1k` / `2k` / `4k`; determines the per-image price. |
| `size` | string | no | Aspect ratio or exact pixels, e.g. `1:1`, `16:9`, `1024x1024`. |
| `image_urls` | string\[] | no | Public reference image URLs for image-to-image. |

## Pricing

| Resolution | Price per image (¥) |
| - | -: |
| 1k | 0.12 |
| 2k | 0.18 |
| 4k | 0.195 |

Prices may change; use `GET /api/pricing` as the runtime source of truth.

## Next step

In async mode, save the `task_id` from the response and poll [Retrieve image task](https://docs.dimilinks.com/en/api-reference/images/gpt-image-2/tasks.md) until completion; sync mode returns image data directly. See [Errors](https://docs.dimilinks.com/en/api-reference/errors.md) for common error codes.


## OpenAPI

````yaml POST /images/generations
openapi: 3.1.0
info:
  title: DimiLinks API
  description: >-
    DimiLinks unified API for chat (OpenAI-compatible and Anthropic native),
    image generation/editing, and video generation.
  version: 1.1.0
servers:
  - url: https://api-direct.dimilinks.com/v1
    description: OpenAI 兼容入口：chat completions / images / videos / models / tasks
security:
  - bearerAuth: []
tags:
  - name: Models
  - name: Chat
  - name: Images
  - name: Videos
  - name: Tasks
paths:
  /images/generations:
    post:
      tags:
        - Images
      summary: Create image generation
      operationId: createImageGeneration
      parameters:
        - name: async
          in: query
          description: Set to true to submit an async image task.
          schema:
            type: boolean
        - name: wait_for_result
          in: query
          description: Set to false to submit an async image task.
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerationRequest'
      responses:
        '200':
          description: Image generation result or async submission
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ImageSubmitResponse'
                  - $ref: '#/components/schemas/ImageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ImageGenerationRequest:
      type: object
      properties:
        model:
          type: string
          default: gpt-image-2
        prompt:
          type: string
        'n':
          type: integer
          default: 1
          minimum: 1
          maximum: 4
          description: 1k resolution allows n=1 only; 2k and 4k allow up to 4.
        size:
          type: string
          examples:
            - '1:1'
            - '16:9'
            - 3840x2160
        resolution:
          type: string
          enum:
            - 1k
            - 2k
            - 4k
        output_format:
          type: string
          examples:
            - png
            - jpeg
            - webp
        output_compression:
          type: integer
        background:
          type: string
          examples:
            - auto
            - transparent
            - opaque
        moderation:
          type: string
          examples:
            - auto
            - low
        wait_for_result:
          type: boolean
        image_urls:
          $ref: '#/components/schemas/ReferenceImages'
        mask_url:
          type: string
        response_format:
          type: string
          examples:
            - b64_json
        user:
          type: string
      required:
        - prompt
    ImageSubmitResponse:
      type: object
      properties:
        created:
          type: integer
          example: 1777080000
        task_id:
          type: string
          example: task_xxx
        data:
          type: array
          items:
            $ref: '#/components/schemas/ImageData'
          example: []
      required:
        - task_id
        - data
    ImageResponse:
      type: object
      properties:
        created:
          type: integer
          example: 1777080000
        task_id:
          type: string
          example: task_xxx
        data:
          type: array
          items:
            $ref: '#/components/schemas/ImageData'
    ReferenceImages:
      oneOf:
        - type: string
        - type: array
          items:
            oneOf:
              - type: string
              - type: object
                additionalProperties: true
          maxItems: 9
        - type: object
          additionalProperties: true
    ImageData:
      type: object
      properties:
        url:
          type: string
          example: >-
            https://lmage2.dimilinks.com/p/img/img_xxx/0?exp=1777166400000&sig=...
        file_id:
          type: string
          example: file_xxx
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    ErrorObject:
      type: object
      properties:
        message:
          type: string
        type:
          type: string
          example: invalid_request_error
        code:
          oneOf:
            - type: string
            - type: integer
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Model is not allowed for this API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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