---
title: "Generate an image (synchronous)"
method: POST
path: "/v1/images"
tags: ["generation"]
---

# Generate an image (synchronous)

`POST /v1/images`

## Request

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

Developer-facing image generation. Synchronous: returns { imageUrl } directly — there is no job to poll. Also available at /v1/image and /v1/image/generate. Requires generate:image scope.

## Request body

- object
  - `prompt` string, required
  - `model` string: Image model ID from GET /v1/models (e.g. nano-banana, gemini-3-pro-image, gemini-3.1-flash-image, flux-1.1-pro, dall-e-3, ideogram-v3). 'modelId' is also accepted.
  - `aspect_ratio` '16:9' | '9:16' | '1:1' | '4:5' | '21:9': 'aspectRatio' is also accepted.
  - `reference_image_url` string, uri
  - `providerOptions` object: Advanced per-model knobs (e.g. gpt-image-2 / dall-e-3 quality/background/outputFormat, flux outputFormat/safetyTolerance, ideogram/recraft style). Full field list per model: /docs/provider-options.

## Response `200`

Image generated

- object
  - `ok` boolean
  - `imageUrl` string, uri
  - `model` string
  - `cost_cents` number: What this image was charged, in cents. On the user's own provider key, the provider's price (may be fractional).
  - `billing_mode` 'platform' | 'byok'

## Other responses

- `400`: Invalid body or non-image model
- `401`: Unauthorized
- `402`: Insufficient credits (insufficient_credits): nothing was delivered or charged
- `403`: Insufficient scope (insufficient_scope; needs generate:image)
- `409`: Model unavailable or provider not configured
- `429`: rate_limited (too many requests; honour Retry-After) or daily_cap_exceeded (this key's daily spend cap is used up; not retryable until the 00:00 UTC reset or a higher cap, no Retry-After)

## Changes

- **2026-10-20** `81d0169a4897`: 1 info
  - added the non-success response with the status `429`

[Operation history](https://skmtc.dev/varosity/apis/varosity-ai-api/changes/v1/images/post.md)

---

[API](https://skmtc.dev/varosity/apis/varosity-ai-api.md) · [All operations](https://skmtc.dev/varosity/apis/varosity-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/varosity/apis/varosity-ai-api/revisions/81d0169a4897?raw)