Async Image Generation

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

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

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

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

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

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-2size options value
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

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.

{
  "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. curl Example

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

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