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	—	Up to 20 reference images for guided generation. HTTPS URL or base64 data URL.

Using reference images

Pass up to 20 reference images in the images array. Each item needs a url.

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

Use reference images when you need tighter control over style, composition, or subject. How many reference images a model accepts is in its supported_references field. See Models.

Reference image sources

url accepts either form:

a publicly accessible HTTPS URL
a base64 data URL, such as data:image/png;base64,...

Use a data URL when the image only exists on your side and you don’t want to host it first.

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

const client = new GetimgAI();

const bytes = await readFile("reference.png");
const dataUrl = `data:image/png;base64,${bytes.toString("base64")}`;

const result = await client.images.generate({
  model: "seedream-5-lite",
  prompt: "Product photo in warm studio lighting",
  images: [{ url: dataUrl }],
});

import base64
from getimg import GetimgAI

client = GetimgAI()

with open("reference.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()

result = client.images.generate(
    model="seedream-5-lite",
    prompt="Product photo in warm studio lighting",
    images=[{"url": f"data:image/png;base64,{encoded}"}],
)

Inline images must be PNG, JPEG, or WebP. Bare base64 without the data: prefix is rejected.

A decoded reference image can be up to 10 MiB, and the whole JSON request must fit within 25 MiB. Base64 adds roughly 33% to the original file size, so budget for that before you inline several images. Pass an HTTPS URL instead when you’re close to the limit.

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. Generated media is retained for 24 hours, so download the file within that window 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

Reference image sources

Response handling

Common failure cases

Full example

​What to send

​Key parameters

​Using reference images

​Reference image sources

​Response handling

​Common failure cases

​Full example

​Related pages

What to send

Key parameters

Using reference images

Reference image sources

Response handling

Common failure cases

Full example

Related pages