curl --request POST \
  --url https://api.loova.ai/api/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt_image_2",
  "prompt": "A small orange cat beside a green plant",
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "quality": "low",
  "output_format": "png",
  "count": 1
}
'

{
  "code": 200,
  "trace_id": "45c30d76f06549b199a3775544523689",
  "message": null,
  "data": {
    "task_id": "record_id",
    "status": "running",
    "created_at": "2026-07-15T12:00:00Z",
    "credits_cost": 2
  }
}

{
  "code": 123,
  "trace_id": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "code": 123,
  "trace_id": "<string>",
  "message": "<string>",
  "data": {}
}

API Reference

Create Image Task

Creates an asynchronous text-to-image or image-to-image generation task.

GPT Image 2.5 (gpt_image_2_5_flare, gpt_image_2_5_sunburst) supports up to 16 reference images, PNG/JPEG/WebP output, auto/transparent/opaque background, and low, medium, high, xhigh, or max quality; its defaults are auto background and high quality. When routed to Vidu, explicit aspect ratios must be paired with a supported 1K, 2K, or 4K size.

Model-specific parameters for grok_imagine_image:

image_urls: omit for text-to-image; provide 1 to 3 publicly accessible URLs for image-to-image
aspect_ratio: 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, or 1:2; auto maps to 1:1 for text-to-image and preserves the first input ratio for image-to-image
resolution: 1K or 2K; default 1K
output_format: jpeg, png, or webp; default jpeg
quality: unsupported and ignored
count: 1 to 4; default 1

POST

images

generations

curl --request POST \
  --url https://api.loova.ai/api/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt_image_2",
  "prompt": "A small orange cat beside a green plant",
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "quality": "low",
  "output_format": "png",
  "count": 1
}
'

{
  "code": 200,
  "trace_id": "45c30d76f06549b199a3775544523689",
  "message": null,
  "data": {
    "task_id": "record_id",
    "status": "running",
    "created_at": "2026-07-15T12:00:00Z",
    "credits_cost": 2
  }
}

{
  "code": 123,
  "trace_id": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "code": 123,
  "trace_id": "<string>",
  "message": "<string>",
  "data": {}
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Validation rules:

Requests must use application/json; multipart file upload is not supported
model and a non-empty prompt are required
image_urls must contain publicly accessible HTTP or HTTPS image URLs; GPT Image 2 and GPT Image 2.5 accept at most 16, while grok_imagine_image accepts at most 3
An empty image_urls array creates a text-to-image task; a non-empty array creates an image-to-image task
aspect_ratio defaults to auto; Grok text-to-image maps it to 1:1, while Grok image-to-image preserves the first input ratio
grok_imagine_image supports only 1K and 2K resolution
GPT Image 2.5 supports background=auto|transparent|opaque and defaults it to auto
GPT Image 2.5 defaults quality to high and supports low, medium, high, xhigh, and max; auto is rejected
output_format must be jpeg, png, or webp; it is supported by GPT Image 2, GPT Image 2.5, and grok_imagine_image

model

enum<string>

required

Image model to use. Each model has different parameter support; see the model-specific parameter rules in this operation's description.

Available options:

gpt_image_2,

gpt_image_2_5_flare,

gpt_image_2_5_sunburst,

nano_banana_2_lite,

nano_banana_2,

nano_banana_pro,

gemini_25_flash_image,

grok_imagine_image

prompt

string

required

Text instruction for image generation or editing.

Minimum string length: 1

image_urls

string<uri>[]

Publicly accessible HTTP or HTTPS input image URLs. Omit or pass an empty array for text-to-image. gpt_image_2, gpt_image_2_5_flare, and gpt_image_2_5_sunburst accept up to 16 images; grok_imagine_image accepts up to 3 images. Multipart file upload is not supported.

Maximum array length: 16

aspect_ratio

enum<string>

default:auto

Output aspect ratio. Supported values vary by model. For grok_imagine_image, auto resolves to 1:1 for text-to-image and preserves the first input image ratio for image-to-image. When GPT Image 2.5 is routed to Vidu, use auto or one of 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9, and 9:21 with a supported resolution.

Available options:

auto,

9:16,

2:3,

3:4,

4:5,

1:1,

5:4,

4:3,

3:2,

16:9,

20:9,

19.5:9,

21:9,

9:21,

9:19.5,

9:20,

1:2,

2:1,

1:4,

4:1,

1:8,

8:1

resolution

enum<string>

default:1K

Output resolution. nano_banana_2_lite and gemini_25_flash_image support only 1K; grok_imagine_image supports 1K and 2K; the other models support 1K, 2K, and 4K.

Available options:

1K,

2K,

4K

quality

enum<string>

Output quality. gpt_image_2 supports low, medium, and high and defaults to low; its legacy auto value maps to low. gpt_image_2_5_flare and gpt_image_2_5_sunburst support low, medium, high, xhigh, and max, default to high, and reject auto. Other models ignore this field.

Available options:

auto,

low,

medium,

high,

xhigh,

max

background

enum<string>

default:auto

Output background mode. Supported by gpt_image_2_5_flare and gpt_image_2_5_sunburst only; defaults to auto.

Available options:

auto,

transparent,

opaque

output_format

enum<string>

Output image format. Supported by GPT Image 2 and GPT Image 2.5 models (default png) and grok_imagine_image (default jpeg). Other models must omit this field.

Available options:

jpeg,

png,

webp

count

integer

default:1

Number of output images.

Required range: 1 <= x <= 4

Response

Task created successfully

code

integer

trace_id

string

message

string | null

data

object

Show child attributes

Getting Started

Guides

API Reference

Create Image Task

Authorizations

Body

Response