Skip to main content
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",
});

​
Key parameters

ParameterTypeDefaultDescription
modelstringrequiredModel identifier. See Models.
promptstringrequiredText description of the image to generate.
aspect_ratiostringmodel defaultAspect ratio. Common values: 1:1, 16:9, 9:16, 2:3, 3:2.
resolutionstringmodel defaultResolution label. Common values: 1K, 2K, 4K.
output_formatstringjpegOutput format: png, jpeg, webp.
imagesarray—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})`);