OpenAI Images Format

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

Use this format when your integration expects OpenAI-style JSON fields and image URLs. Text-to-image and image editing have synchronous endpoints; UniAll also provides an asynchronous task flow for clients that should not keep a long connection open.

Endpoints

Workflow	Method and path	Behavior
Text to image	POST /v1/images/generations	Waits and returns the image URL.
Image editing	POST /v1/images/edits	Waits and returns the image URL.
Asynchronous generation or editing	POST /v1/images/tasks	Returns a task ID immediately.
Query asynchronous task	GET /v1/images/tasks/{task_id}	Returns status and results.

Authentication

Authorization: Bearer sk-***
Content-Type: application/json

x-api-key: sk-*** is also accepted, but Bearer authentication is recommended for OpenAI-style clients.

Request Parameters

Parameter	Type	Required	Description
model	string	Yes	nano-banana-2, nano-banana-pro, or nano-banana-2-lite.
prompt	string	Yes	Generation or editing instruction.
resolution	string	No	0.5k, 1k, 2k, or 4k; defaults to 1k. Model limits apply.
aspect_ratio	string	No	Output ratio such as 1:1, 3:4, or 16:9.
images	string[]	Conditional	Reference image URLs or complete Data URLs for editing.
n	integer	No	Keep at 1; each request currently generates one image.
output_format	string	No	Output format such as png.
request_id	string	No	Your non-sensitive correlation ID for asynchronous tasks.

0.5K is available only for nano-banana-2 and must be written as resolution: "0.5k".

Synchronous Text-To-Image

curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A cinematic product photo of a clear perfume bottle on black stone, blue mist, no text",
    "resolution": "0.5k",
    "aspect_ratio": "1:1",
    "n": 1,
    "output_format": "png"
  }'

Synchronous Image Editing

curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "Keep the subject and composition; replace the background with a rainy neon street",
    "images": ["https://example.com/reference/person.png"],
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "n": 1,
    "output_format": "png"
  }'

Reference URLs must be directly accessible to the service. Put multiple references in images in the order the prompt describes them.

Synchronous Response

{
  "created": 1787366400,
  "data": [
    {
      "url": "https://media.example.com/generated/image.png",
      "width": 512,
      "height": 512
    }
  ]
}

Read data[0].url and transfer the asset if you need permanent retention.

Asynchronous Task

Generation and editing share POST /v1/images/tasks. Including images makes the request an editing task.

curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A cinematic product photo of a clear perfume bottle on black stone",
    "resolution": "0.5k",
    "aspect_ratio": "1:1",
    "n": 1,
    "output_format": "png",
    "request_id": "image-20260822-0001"
  }'

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "image.generation.job",
  "model": "nano-banana-2",
  "status": "PENDING",
  "progress": 0,
  "image_url": null
}

Save task_id; do not create a replacement merely because the task is still pending.

Task Status And Result

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

Poll every 2 to 3 seconds initially, then back off to every 5 to 10 seconds. Use ?refresh=true only when you need an immediate upstream refresh, not on every poll.

Status	Meaning	Action
PENDING	Waiting for processing	Continue polling.
IN_PROGRESS	Generating	Continue polling.
COMPLETED	Finished	Read data[0].url; fall back to image_url.
FAILED	Failed	Read the public error and stop.
CANCELLED	Cancelled	Stop polling.

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "model": "nano-banana-2",
  "status": "COMPLETED",
  "progress": 100,
  "image_url": "https://media.example.com/generated/image.png",
  "data": [
    {
      "url": "https://media.example.com/generated/image.png",
      "width": 512,
      "height": 512
    }
  ],
  "error": null
}

Legacy Model IDs

Fixed-resolution aliases such as NanoBanana2-0.5K and NanoBananaPro-4K may still work for compatibility. They are deprecated and may be removed at any time. Use a unified model ID plus resolution for new code.

Billing Notes

Billing depends on the selected model and resolution. Check the current price available to your account. A disconnected synchronous request or client timeout does not guarantee that generation stopped.

Common Errors

• Sending resolution: "512" or "512K" instead of "0.5k".
• Requesting 0.5K from nano-banana-pro or nano-banana-2-lite.
• Supplying a reference URL that requires a login or temporary cookie.
• Retrying a timed-out request immediately and creating duplicate generations.
• Branching on error-message text instead of HTTP status and structured error fields.

Related Pages

• Nano Series
• Gemini generateContent Format
• Async Image Generation