Generate images

Use POST /v2/images/generations to create images synchronously. The API waits for completion and returns the finished files in the same response.

POST https://api.getimg.ai/v2/images/generations

What to send

At minimum, send a model and prompt.

import GetimgAI from "getimg-ai";

const client = new GetimgAI();

const result = await client.images.generate({
  model: "seedream-5-lite",
  prompt: "A cinematic portrait of a cat astronaut",
});

from getimg import GetimgAI

client = GetimgAI()

result = client.images.generate(
    model="seedream-5-lite",
    prompt="A cinematic portrait of a cat astronaut",
)

curl -X POST https://api.getimg.ai/v2/images/generations \
  -H "Authorization: Bearer $GETIMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-lite",
    "prompt": "A cinematic portrait of a cat astronaut"
  }'

Key parameters

Parameter	Type	Default	Description
`model`	string	required	Model identifier. See Models.
`prompt`	string	required	Text description of the image to generate.
`aspect_ratio`	string	model default	Aspect ratio. Common values: `1:1`, `16:9`, `9:16`, `2:3`, `3:2`.
`resolution`	string	model default	Resolution label. Common values: `1K`, `2K`, `4K`.
`output_format`	string	`jpeg`	Output format: `png`, `jpeg`, `webp`.
`images`	array	—	Reference images for guided generation.

Using reference images

Pass one or more reference images in the images array. Each image requires a url and a role.

{
  "model": "seedream-5-lite",
  "prompt": "Product photo in warm studio lighting",
  "images": [
    {
      "url": "https://your-bucket.s3.amazonaws.com/reference.png",
      "role": "reference_image"
    }
  ],
  "aspect_ratio": "1:1",
  "resolution": "2K",
  "output_format": "webp"
}

Use reference_image when you need tighter control over style, composition, or subject.

Response handling

A completed image generation returns:

id for the generation
status: "completed"
data, which contains one or more generated files
usage, which contains billing details for the generation

Each item in data includes a signed download URL and a deletes_at timestamp. Download the file before it expires if you need to keep it in your own system. See Media responses for the full response shape.

Common failure cases

Invalid model, aspect ratio, or resolution returns 400.
Missing or invalid API keys return 401.
Insufficient balance returns 402.
Safety failures for prompts or reference images return 422.
Rate or concurrency limits return 429.

See Errors for error handling details.

Full example

import { writeFile } from "node:fs/promises";
import GetimgAI from "getimg-ai";

const client = new GetimgAI();

const result = await client.images.generate({
  model: "seedream-5-lite",
  prompt: "A watercolor painting of a mountain village at dawn",
  aspect_ratio: "16:9",
  resolution: "2K",
  output_format: "png",
});

const download = await fetch(result.data[0].url);
const buffer = Buffer.from(await download.arrayBuffer());
await writeFile("output.png", buffer);

console.log(`Saved output.png (${result.data[0].width}x${result.data[0].height})`);
console.log(`Cost: ${result.usage?.total_cost} (${result.usage?.billable_unit})`);

import httpx
from getimg import GetimgAI

client = GetimgAI()

result = client.images.generate(
    model="seedream-5-lite",
    prompt="A watercolor painting of a mountain village at dawn",
    aspect_ratio="16:9",
    resolution="2K",
    output_format="png",
)

with open("output.png", "wb") as f:
    f.write(httpx.get(result.data[0].url).content)

print(f"Saved output.png ({result.data[0].width}x{result.data[0].height})")
print(f"Cost: {result.usage.total_cost} ({result.usage.billable_unit})")

curl -X POST https://api.getimg.ai/v2/images/generations \
  -H "Authorization: Bearer $GETIMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-lite",
    "prompt": "A watercolor painting of a mountain village at dawn",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "output_format": "png"
  }'

Getting started

Generation

Concepts

What to send

Key parameters

Using reference images

Response handling

Common failure cases

Full example

​What to send

​Key parameters

​Using reference images

​Response handling

​Common failure cases

​Full example

​Related pages

What to send

Key parameters

Using reference images

Response handling

Common failure cases

Full example

Related pages