---
title: "Generate an image"
method: POST
path: "/ai/images"
tags: ["Generation"]
---

# Generate an image

`POST /ai/images`

## Request

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

Generate a still with optional referenceUrls (up to 5 images: your uploads or public HTTPS images). provider accepts grok, openai or auto (default). Google models are not offered through the API: provider vertex is refused with a 400. quoteOnly:true returns the initial and maximum credits without spending. Retain provider:auto with the quoted maxCredits to allow safe quota fallback; explicit providers never switch. OpenAI GPT Image 2.5 Flare costs 128 at 1k or 256 at 2k plus 8 per reference. Only the successful asset is charged. Studio.

## Request body

- object
  - `prompt` string, required: Up to 800 characters.
  - `provider` 'auto' | 'grok' | 'openai': Who generates it. Auto picks the lowest compatible quote between Grok and OpenAI.
  - `resolution` '1k' | '2k': Affects OpenAI prices.
  - `aspectRatio` string: For example `16:9`, `9:16`, `1:1`, `4:5`, `21:9`.
  - `referenceUrls` string[]: Up to 5 reference images: your upload URLs (png, jpg, webp, avif) or public HTTPS URLs.
  - `maxCredits` number: Never spend more than this.
  - `quoteOnly` boolean: `true` returns the route and price without generating or charging.

## Response `200`

Generate an image

- object
  - `url` string: The image. Use as a clip `src`.
  - `route` object: The provider route chosen: `provider`, `model`, `credits`, `maxCredits`, `reason` and `policy` (and `voiceId` for speech).
  - `credits` object: `{ charged, remaining }`: what this call cost and the balance after it.
  - `hint` string: What to do with it.

## Other responses

- `400`: `invalid_request`: No prompt, a refused reference, provider `vertex` (Google models are not offered through the API), or no provider matches the options and `maxCredits`.
- `402`: `plan_required`: The plan has no image generation. `insufficient_credits`: The balance cannot cover the call. Nothing ran. `remaining` is the balance.
- `422`: `prompt_rejected`: The prompt failed the safety check. Nothing was charged. `field` names the field.
- `502`: `provider_error`: The generation provider failed. The charge is refunded.

---

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