> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getimg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate images

> Create images from text and reference images.

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

```text theme={null}
POST https://api.getimg.ai/v2/images/generations
```

## What to send

At minimum, send a `model` and `prompt`.

<CodeGroup>
  ```javascript Node.js theme={null}
  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",
  });
  ```

  ```python Python theme={null}
  from getimg import GetimgAI

  client = GetimgAI()

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

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

## Key parameters

| Parameter       | Type   | Default       | Description                                                             |
| --------------- | ------ | ------------- | ----------------------------------------------------------------------- |
| `model`         | string | required      | Model identifier. See [Models](https://getimg.ai/app/developer/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`.

```json theme={null}
{
  "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](/guides/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](/guides/errors) for error handling details.

## Full example

<CodeGroup>
  ```javascript Node.js theme={null}
  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})`);
  ```

  ```python Python theme={null}
  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})")
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

## Related pages

* [Quickstart](/guides/quickstart)
* [Media responses](/guides/media-responses)
* [Errors](/guides/errors)
* [Models](/guides/models)