# Async Image Generation

This file is the focused AI-readable context for one UniAll documentation page.

URL: https://docs.uniall.ai/models/image/async-image-generation
Locale: en
Markdown: https://docs.uniall.ai/ai/pages/models/image/async-image-generation.md
Description: Async image generation source documentation.

Agent guidance:
- Use this page when the user is asking about this specific route or model capability.
- Preserve endpoint paths, JSON keys, model IDs, and placeholder values exactly.
- Treat examples such as `sk-***`, `{BASE_URL}`, and `task_xxx` as safe placeholders, not real secrets.

## Page Markdown

Updated: 2026-04-29

This document explains how to use the async image task endpoint to call NanoBanana model and `gpt-image-2`, including request flow, Parameters, responses, billing detail rules and differences between the two model families.

## 1. Endpoint Overview

### 1.1 Submit Async Image Task

```http
POST /v1/images/tasks
```

supports:
- `task_type = text2image`
- `task_type = image2image`

### 1.2 Query Async Image Task

```http
GET /v1/images/tasks/{task_id}
```

### 1.3 Details
```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 2. Model

### 2.1 NanoBanana

upstream Nano Model:

| Model | Note |
| --- | --- |
| `NanoBanana` | NanoBanana Model |
| `NanoBanana2-0.5K` | NanoBanana2, 0.5K |
| `NanoBanana2-1K` | NanoBanana2, 1K |
| `NanoBanana2-2K` | NanoBanana2, 2K |
| `NanoBanana2-4K` | NanoBanana2, 4K |
| `NanoBananaPro-1K` | NanoBanana Pro, 1K |
| `NanoBananaPro-2K` | NanoBanana Pro, 2K |
| `NanoBananaPro-4K` | NanoBanana Pro, 4K |
| `NanoBananaPro-8K` | NanoBanana Pro, 8K |

Note: Whether the user can call Model, the platform Whether and billing detail Model.
### 2.2 gpt-image-2

| Model | Note |
| --- | --- |
| `gpt-image-2`|`size + quality + n` Parameters billing detail image model |

## 3. Request Parameters

 These fields apply to NanoBanana and `gpt-image-2`.

| Parameters | Type | Required | Note |
| --- | --- | --- | --- |
| `model`| string | Yes | Model,`NanoBanana2-0.5K`, `gpt-image-2` |
| `prompt` | string | Yes | image generation or editing prompt |
| `task_type`| string | No |`text2image` or `image2image`. pass, Whether image |
| `image` | string / file | Required | reference. JSON pass an image URL; |
| `images` | string[] | Required | multiple reference images URL, recommended field |
| `size`| string | Model | size.`gpt-image-2` Required, supported values: see [gpt-image-2`size` options](#gpt-image-2-size-options); NanoBanana prefer using `aspect_ratio` controlRatio |
| `aspect_ratio`| string | model-dependent optional values |`NanoBanana`, `NanoBananaPro-*`, `NanoBanana2-*` supports, [NanoBanana Capability](#nanobanana-capability-options);`gpt-image-2` does not support |
| `quality`| string | No | quality.`gpt-image-2` supported values: see [gpt-image-2`quality` options](#gpt-image-2-quality-options); NanoBanana model tier |
| `n`| integer | No | generation. default `1`. `gpt-image-2` `1-8`; NanoBanana does not support|
| `output_format`| string | Optional values | control image type. Nano supported values: see [NanoBanana Capability](#nanobanana-capability-options);`gpt-image-2` supported values: see [gpt-image-2`output_format` options](#gpt-image-2-output-format-options) |


### 3.1 reference pass

 recommended Field:

```json
{
  "image": "https://example.com/input.png"
}
```

```json
{
  "images": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
```

do not reference Field. compatibility Field, reference. For new integrations, use `image` or `images`.

Task type Rules:

- image: `text2image` processing
- `image`/`images`/ multipart image file:`image2image` processing
- pass `task_type`, value

## 4. NanoBanana Parameters

NanoBanana use async image task Structure.

### 4.1 JSON

```json
{
  "model": "NanoBanana2-0.5K",
  "task_type": "text2image",
  "prompt": "A small red cube on a clean white desk, minimal product photo, soft daylight",
  "aspect_ratio": "1:1",
  "output_format": "png",
  "n": 1,
  "response_format": "url"
}
```

### 4.2 JSON

```json
{
  "model": "NanoBanana2-0.5K",
  "task_type": "image2image",
  "prompt": "Turn the reference image into a clean product render",
  "image": "https://example.com/input.png",
  "aspect_ratio": "16:9",
  "output_format": "jpeg",
  "n": 1,
  "response_format": "url"
}
```

### 4.3 Parameter Constraints

| Parameters | NanoBanana Rules |
| --- | --- |
| `model` | pass Nano Model |
| `prompt` | Required |
| `task_type`|`text2image`/`image2image`, the platform |
| `aspect_ratio`| recommended to use; control output aspect ratio. value `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, supported range upstream model |
| `output_format`| recommended to use; control image type.`NanoBanana` supports `png`/`jpeg`/`webp`; `NanoBananaPro-*`, `NanoBanana2-*` supports `png`/`jpeg` |
| `size` | NanoBanana controlParameters; pass in, upstreamcompatibilityCapabilityprocessing |
| `quality` | NanoBanana the platform billing detail; model tier |
| `n`| Optional values; default `1`. billing detail generation, value upstreamconstraints |
| `response_format`| recommended `url` |
| image Field | use for single-image input `image`, use for multi-image input `images`; multipart passfile use `image` |

###### NanoBanana capability options

### 4.4 NanoBanana Capability

| Model | `aspect_ratio`|`output_format` |
| --- | --- | --- |
| `NanoBanana`| supports | supports `png`/`jpeg`/`webp` |
| `NanoBananaPro-*`| supports | supports `png`/`jpeg` |
| `NanoBanana2-*`| supports | supports `png`/`jpeg` |

### 4.5 billing detail

NanoBanana Model billing detail, generation `n` or upstreamreturn result.

`aspect_ratio` and `output_format` controlgeneration, and the platform billing detail; Nano model tier model pricing.

 `NanoBanana2-0.5K`, the platform pricing and.

If NanoBanana Model, requires model pricing.

## 5. gpt-image-2 Parameters

`gpt-image-2` useParameters billing detail.`size` YesRequired Parameters;`quality` and `n` defaultvalue;`output_format` control image type; does not support `aspect_ratio`.

### 5.1 JSON

```json
{
  "model": "gpt-image-2",
  "task_type": "text2image",
  "prompt": "A small blue glass sphere on a clean white desk, minimal product photo, soft daylight",
  "size": "1024x768",
  "quality": "low",
  "output_format": "webp",
  "n": 1,
  "response_format": "url"
}
```

### 5.2 JSON

```json
{
  "model": "gpt-image-2",
  "task_type": "image2image",
  "prompt": "Keep the product shape, change the background to a bright studio scene",
  "image": "https://example.com/input.png",
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "n": 1,
  "response_format": "url"
}
```

### 5.3 multipart

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
 -H "Authorization: Bearer sk-***" \
 -F "model=gpt-image-2" \
 -F "task_type=image2image" \
 -F "prompt=Keep the subject, make it a clean studio product photo" \
 -F "size=1024x1024" \
 -F "quality=medium" \
 -F "output_format=png" \
 -F "n=1" \
 -F "response_format=url" \
 -F "image=@/path/to/input.png"
```

### 5.4 Parameter Constraints

| Parameters | Rules |
| --- | --- |
| `size`| Required, must be [gpt-image-2`size` options](#gpt-image-2-size-options) value |
| `aspect_ratio`| does not support; use `size` control sizeandRatio |
| `quality`| Optional values, default `medium`, supported values: see [gpt-image-2 `quality` options](#gpt-image-2-quality-options) |
| `output_format`| Optional values, supported values: see [gpt-image-2`output_format` options](#gpt-image-2-output-format-options) |
| `n`| Optional values, default `1`, range `1-8` |
| `response_format`| recommended `url` |
| `task_type`|`text2image`/`image2image`, the platform |

###### GPT Image 2 quality options

`quality` supportsvalue:

| value | |
| --- | --- |
| `low`|`low` |
| `medium`|`medium` |
| `high`|`high` |

###### GPT Image 2 output format options

`output_format` supportsvalue:

| value |
| --- |
| `png` |
| `jpeg` |
| `webp` |

###### GPT Image 2 size options

### 5.5 gpt-image-2 `size` options

`gpt-image-2` `size` control sizeandRatio, does not support pass `aspect_ratio`. `quality` pass `low`, `medium`, `high`; `n` generation.

| Size | Ratio | Orientation | |
| --- | --- | --- | --- |
| `1024x768`|`4:3`| Landscape |`1K` |
| `768x1024`|`3:4`| Portrait |`1K` |
| `1344x1024`|`4:3`| Landscape |`1K` |
| `1024x1344`|`3:4`| Portrait |`1K` |
| `1280x1024`|`5:4`| Landscape |`1K` |
| `1024x1280`|`4:5`| Portrait |`1K` |
| `1360x768`|`16:9`| Landscape |`1K` |
| `768x1360`|`9:16`| Portrait |`1K` |
| `1536x864`|`16:9`| Landscape |`1K` |
| `864x1536`|`9:16`| Portrait |`1K` |
| `1024x1024`|`1:1`| Square |`1K` |
| `1536x1024`|`3:2`| Landscape |`1K` |
| `1024x1536`|`2:3`| Portrait |`1K` |
| `2048x1024`|`2:1`| Landscape |`1K` |
| `1024x2048`|`1:2`| Portrait |`1K` |
| `2016x864`|`21:9`| Landscape |`1K` |
| `864x2016`|`9:21`| Portrait |`1K` |
| `1920x1080`|`16:9`| Landscape |`2K` |
| `1080x1920`|`9:16`| Portrait |`2K` |
| `1536x1536`|`1:1`| Square |`2K` |
| `2048x1360`|`3:2 approximately`| Landscape |`2K` |
| `1360x2048`|`2:3 approximately`| Portrait |`2K` |
| `2048x1536`|`4:3`| Landscape |`2K` |
| `1536x2048`|`3:4`| Portrait |`2K` |
| `2160x1440`|`3:2`| Landscape |`2K` |
| `1440x2160`|`2:3`| Portrait |`2K` |
| `2048x1152`|`16:9`| Landscape |`2K` |
| `1152x2048`|`9:16`| Portrait |`2K` |
| `2688x1344`|`2:1`| Landscape |`2K` |
| `1344x2688`|`1:2`| Portrait |`2K` |
| `2688x1152`|`21:9`| Landscape |`2K` |
| `1152x2688`|`9:21`| Portrait |`2K` |
| `2560x1440`|`16:9`| Landscape |`2K` |
| `1440x2560`|`9:16`| Portrait |`2K` |
| `2048x2048`|`1:1`| Square |`4K` |
| `2560x2048`|`5:4`| Landscape |`2K` |
| `2048x2560`|`4:5`| Portrait |`2K` |
| `2880x2880`|`1:1`| Square |`4K` |
| `3264x2448`|`4:3`| Landscape |`4K` |
| `2448x3264`|`3:4`| Portrait |`4K` |
| `3504x2336`|`3:2`| Landscape |`4K` |
| `2336x3504`|`2:3`| Portrait |`4K` |
| `3840x1920`|`2:1`| Landscape |`4K` |
| `1920x3840`|`1:2`| Portrait |`4K` |
| `3840x1648`|`21:9 approximately`| Landscape |`4K` |
| `1648x3840`|`9:21 approximately`| Portrait |`4K` |
| `3840x2160`|`16:9`| Landscape |`4K` |
| `2160x3840`|`9:16`| Portrait |`4K` |

## 6. submitresponses

submitSuccess returntaskobject.

```json
{
  "task_id": "task_xxx",
  "status": "succeeded",
  "progress": "100%",
  "result_url": "https://example.com/result.png",
  "metadata": {
    "task_type": "text2image",
    "result_count": 1
  },
  "error": null
}
```

Field Reference:

| Field | Note |
| --- | --- |
| `task_id` | the platformtask ID, query |
| `status`|`queued`, `processing`, `succeeded`, `failed` |
| `progress`| task,`0%`, `50%`, `100%` |
| `result_url` | oneresult URL |
| `metadata.task_type` | Task type |
| `metadata.result_count` | result |
| `metadata.result_urls` | result return URL array |
| `error`| Failed Error, Success `null` |

## 7. queryresponses

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
 -H "Authorization: Bearer sk-***"
```

Successresponses:

```json
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxx",
    "status": "succeeded",
    "progress": "100%",
    "result_url": "https://example.com/result.png",
    "metadata": {
      "task_type": "text2image",
      "result_count": 1
    },
    "error": null
  }
}
```

recommended poll `2-5`. task `succeeded` or `failed` poll.

## 8. curl Example

### 8.1 NanoBanana

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "NanoBanana2-0.5K",
 "task_type": "text2image",
 "prompt": "A small red cube on a clean white desk, minimal product photo, soft daylight",
 "aspect_ratio": "1:1",
 "output_format": "png",
 "n": 1,
 "response_format": "url"}'
```

### 8.2 gpt-image-2

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
 -H "Authorization: Bearer sk-***" \
 -H "Content-Type: application/json" \
 -d '{"model": "gpt-image-2",
 "task_type": "text2image",
 "prompt": "A small blue glass sphere on a clean white desk, minimal product photo, soft daylight",
 "size": "1024x768",
 "quality": "low",
 "output_format": "webp",
 "n": 1,
 "response_format": "url"}'
```

### 8.3 Query Task

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
 -H "Authorization: Bearer sk-***"
```

## 9. NanoBanana and gpt-image-2

| | NanoBanana | `gpt-image-2` |
| --- | --- | --- |
| Modellist | Model, Pro andResolution tier | Model |
| | `NanoBanana2-0.5K`|`gpt-image-2` |
| Billing mode | Model * generation | `size + quality` Parameters billing detail *`n` |
| Ratiocontrol | supports `aspect_ratio`, `1:1`,`2:3`,`3:2`,`3:4`,`4:3`,`4:5`,`5:4`,`9:16`,`16:9`,`21:9`| does not support `aspect_ratio`; use `size`, `1024x768`, `1024x1024` |
| formatcontrol | `NanoBanana` supports `png`/`jpeg`/`webp`; `NanoBananaPro-*`, `NanoBanana2-*` supports `png`/`jpeg`| supports `png`/`jpeg`/`webp` |
| `size`| controlParameters; model tierand `aspect_ratio`| Required, [gpt-image-2`size` options](#gpt-image-2-size-options) |
| `quality`| the platform billing detail; model tier | Optional values, default `medium`, and billing detail |
| `n`| Optional values, default `1`, value upstreamconstraints | Optional values, default `1`, range `1-8` |
| `response_format`| recommended `url`| recommended `url` |
| | use for single-image input `image`, use for multi-image input `images`, passreference /editingPath | use for single-image input `image`, use for multi-image input `images`, passreference /editingPath |


## 10. Details
1. use `POST /v1/images/tasks` submit task.
2. return `task_id`.
3. use `GET /v1/images/tasks/{task_id}` polltask.
4. `status = succeeded` read `result_url`.