Async Image Generation

In this page's examples, {BASE_URL} is https://api.uniall.ai.

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

POST /v1/images/tasks

supports:

• task_type = text2image
• task_type = image2image

1.2 Query Async Image Task

GET /v1/images/tasks/{task_id}

1.3 Details

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	Image generation and editing model

3. Request Body Parameters

These fields apply to NanoBanana and gpt-image-2 unless a model is specified in the row.

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-2size options; NanoBanana prefer using aspect_ratio controlRatio
aspect_ratio	string	model-dependent optional values	NanoBanana, NanoBananaPro-*, NanoBanana2-* supports, NanoBanana Capability;gpt-image-2 does not support
quality	string	No	quality.gpt-image-2 supported values: see gpt-image-2quality 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;gpt-image-2 supported values: see gpt-image-2output_format options
background	string	No	For gpt-image-2 only; pending release. auto (model chooses from the prompt), opaque (opaque background), or transparent (transparent background). Omitted or null: auto.

3.1 reference pass

recommended Field:

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

{
  "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

{
  "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

{
  "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

Use size for output dimensions, quality for image quality, n for the image count, and output_format for the image format.

Background control is pending release. Pass background at the top level of the request body.

• auto: the model chooses the background from the prompt. This is the default when omitted or set to null.
• opaque: request an opaque background.
• transparent: request a transparent background. Set output_format to png or webp; if omitted, it defaults to png.

An invalid background value or a transparent/jpeg combination returns HTTP 400 during request validation, before generation starts.

5.1 JSON

{
  "model": "gpt-image-2",
  "task_type": "text2image",
  "prompt": "An orange cat sticker, full subject visible, transparent background",
  "size": "1024x768",
  "quality": "low",
  "background": "transparent",
  "output_format": "webp",
  "n": 1,
  "response_format": "url"
}

5.2 JSON

{
  "model": "gpt-image-2",
  "task_type": "image2image",
  "prompt": "Keep the product shape and remove the background to make it transparent",
  "image": "https://example.com/input.png",
  "size": "1024x1024",
  "quality": "medium",
  "background": "transparent",
  "output_format": "png",
  "n": 1,
  "response_format": "url"
}

5.3 multipart

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 product shape and remove the background to make it transparent" \
 -F "size=1024x1024" \
 -F "quality=medium" \
 -F "background=transparent" \
 -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; output dimensions. See size guidance.
aspect_ratio	does not support; use size control sizeandRatio
quality	Optional values, default medium, supported values: see gpt-image-2 quality options
output_format	Optional values, supported values: see gpt-image-2output_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

Use size to specify output dimensions for gpt-image-2, such as 1024x1024. Omit aspect_ratio; use quality for image quality and n for the image count.

6. Response Examples

submitSuccess returntaskobject.

{
  "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

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

Successresponses:

{
  "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. Request Examples

8.1 NanoBanana

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

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": "An orange cat sticker, full subject visible, transparent background",
 "size": "1024x768",
 "quality": "low",
 "background": "transparent",
 "output_format": "webp",
 "n": 1,
 "response_format": "url"}'

8.3 Query Task

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
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-2size 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.