docs/images

Image Generation

Create production-ready images from text prompts with one authenticated API call.

Overview

Image generation fits visual content workflows such as product concepts, campaign assets, and illustrations. Try it interactively in the Image Studio, or choose media units in photo packages.

Quick start

Use the same sk-ag-* API key accepted by the other API endpoints.

bash

curl https://api.aggregate.ai/v1/images/generations \
  -H "Authorization: Bearer sk-ag-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image-standard",
    "prompt": "A sunlit glass greenhouse on Mars, botanical photography",
    "n": 1,
    "size": "1024x1024"
  }'

Request body

Name	Type	Required	Default	Description
model	string	yes	—	Image model ID from the model catalog.
prompt	string	yes	—	Text description of the image.
n	integer	no	1	Number of images. Values greater than 1 use an internal batch.
size	string	no	model default	Requested image dimensions, for example 1024x1024.
negative_prompt	string	no	none	Content or visual qualities to avoid.
seed	integer	no	random	Seed for reproducible generation when supported by the model.

Response body

json

{
  "data": [{ "url": "https://.../image.png" }],
  "created": 1760000000
}

When an internal batch does not finish within the 60-second block-poll window, the endpoint returns 202 with { batch_id, status: "in_progress" }. Poll GET /v1/batches/{id} for the result.

Errors

400	Invalid generation request or unsupported model.
402	Insufficient units.
422	Validation error in the request body.
500	Upstream generation failure.

Pricing

Each generation consumes fixed media units determined by the selected model and media package. See photo package pricing.

Models

Use an image model whose public catalog modality is image. The available IDs and provider metadata are listed in Models (the catalog shape is normalized by frontend/src/lib/public-models.ts:13-18).

Endpoint schema: services/api-proxy/app/routers/images.py:69-83. Billing and media-package lookup: services/api-proxy/app/routers/images.py:99-159.