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

# Start an AI image generation

`POST /ai/generate`

## Request

- Base URL: `https://api.dynapictures.com`
- URL: `https://api.dynapictures.com/ai/generate`
- Auth: HTTP bearer

Starts generating a standalone image, not tied to a template, and returns immediately. Poll the `Location` URL every 2 seconds or so until `status` is `done` or `error`; generation usually takes 10 to 60 seconds. Uses AI credits, charged only on success.

## Request body

- AiGenerateRequest
  - `modelId` string, required: The AI model. The API reference lists every model with its credit cost, e.g. `flux-2-pro`, `gemini-3.1-flash-image` or `gpt-image-2-med`.
  - `prompt` string, required: What to generate. May contain `[name]` tokens that refer to `referenceImages`.
  - `ratio` '1:1' | '3:2' | '2:3' | '16:9' | '9:16' | '4:3' | '3:4': The aspect ratio. Supported ratios vary by model.
  - `sourceImage` string, uri: URL of a photo to edit. Leave it out for text-to-image.
  - `referenceImages` ReferenceImage[]: Named reference images. At most 6 input images in total, counting `sourceImage`.
    - `name` string, required: Short name used in the prompt as `[name]`, e.g. `logo`.
    - `url` string, uri, required: Public URL of the reference image.

## Response `202`

The job was queued.

- AiJobStarted
  - `jobUid` string, required: The ID of the job. Use it to poll for the result.
  - `status` 'queued', required: Always `queued` on a new job.

## Other responses

- `400`: The request is invalid. `message` says why.
- `401`: The API key is missing or wrong.
- `402`: The workspace is out of AI credits. No job was created.

---

[API](https://skmtc.dev/dynapictures/apis/dynapictures-api.md) - [All operations](https://skmtc.dev/dynapictures/apis/dynapictures-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dynapictures/apis/dynapictures-api/revisions/a9820777cfb3?raw)