---
title: "Start an image generation"
method: POST
path: "/ai/images"
tags: ["AI"]
---

# Start an image generation

`POST /ai/images`

## Request

- Base URL: `https://post.adaptlypost.com/post/api/v1`
- URL: `https://post.adaptlypost.com/post/api/v1/ai/images`
- Auth: HTTP bearer

Queues an image and returns a `jobId` right away. Poll GET /ai/images/{jobId} until `status` is `completed` or `failed`; a completed job carries the `imageUrl`. Images take roughly 10 to 40 seconds. Credits are charged when generation starts and refunded if it fails.. Requires the `ai.generate` permission.

## Headers

- `X-Workspace-Id` string

## Request body

- GenerateImageRequest
  - `prompt` string, required
  - `aspectRatio` '1:1' | '16:9' | '9:16' | '3:2' | '2:3' | '4:5' | '5:4' | '21:9' | '9:21': The image comes back at exactly this ratio: 1:1 is 1024x1024, 3:2 is 1536x1024, 2:3 is 1024x1536, 5:4 is 1280x1024, 4:5 is 1024x1280, 16:9 is 1536x864, 9:16 is 864x1536, 21:9 is 1792x768 and 9:21 is 768x1792. With your own Google key Google picks the pixel size, and 9:21 comes back as 9:16
  - `model` 'standard' | 'premium'
  - `quality` 'LOW' | 'MEDIUM' | 'HIGH': Used only when you generate with your own OpenAI key. On AdaptlyPost credits `model` sets the quality and this field is ignored
  - `sessionId` string, uuid: Groups images together. Omit it and a new session is created, then reuse the returned sessionId to keep related images in one place.
  - `referenceImages` string[]: Public image URLs to steer the result

## Response `201`

Image generation queued

- GenerateImageResponse
  - `jobId` string
  - `sessionId` string, uuid
  - `status` 'queued' | 'processing' | 'generating' | 'completed' | 'failed'

## Other responses

- `400`: Validation error
- `401`: Invalid or missing API key
- `403`: The key's role does not hold `ai.generate`
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/adaptlypost/apis/adaptlypost-public-api.md) · [All operations](https://skmtc.dev/adaptlypost/apis/adaptlypost-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adaptlypost/apis/adaptlypost-public-api/revisions/8390a5fa9a0d?raw)