---
title: "Create an image variation (async, image-to-image)"
method: POST
path: "/v1/images/vary"
tags: ["Images"]
---

# Create an image variation (async, image-to-image)

`POST /v1/images/vary`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/images/vary`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

Generate a new image based on a source image, guided by a prompt.
Give the source either as a library `file_uuid` (upload via POST /v1/files/upload)
or inline as base64 in `image_data`; exactly one of the two.
Returns immediately with a `job_id` - poll `GET /v1/jobs/{id}` until
`status` is `completed`, then use `download_url`.
Discover valid `model` values via GET /v1/models.

With `guided: true` the prompt is wrapped in the instructions the Image Variator
uses (shaped by `variability`), `prompt` may be empty, and the editing fields apply:
`mask_data` (inpainting: a PNG the size of the source, black marks what to regenerate),
`crop` (vary only that region), `extension_direction` and `aspect_ratio_processed`
(the source was padded with lime green #00FF00 areas to fill). Without `guided`,
`prompt` is required and sent to the model as written.

## Request body

- object
  - `file_uuid` string: UUID of a source image already in your library. Use this or `image_data`.
  - `image_data` string: The source image inline, as base64 or a data URL (PNG, JPEG, WebP or GIF). Use this or `file_uuid`.
  - `prompt` string: How the variation should differ from the source. Required unless `guided` is true.
  - `model` 'standard' | 'lite' | 'pro' | 'flux' | 'seedream' | 'seedream5': Model to use for the variation.
  - `aspect_ratio` '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '3:2' | '2:3': Output aspect ratio. Omit to keep the source ratio.
  - `variability` integer: How far the result may stray from the source (1 = subtle, 5 = experimental).
  - `options` object: Model-specific options.
    - `resolution` '1024' | '2048' | '4096': Output resolution (pro model only).
    - `seed` integer: Seed for reproducible output, where the model supports one.
  - `guided` boolean: Wrap the prompt in the Image Variator instructions and allow the editing fields below.
  - `mask_data` string: Guided only. Inpainting mask as base64 PNG, same size as the source: black pixels are regenerated, the rest is kept.
  - `crop` object: Guided only. Vary just this region of the source, in source pixels.
    - `x` integer, required
    - `y` integer, required
    - `width` integer, required
    - `height` integer, required
  - `extension_direction` 'top' | 'right' | 'bottom' | 'left': Guided only. The side the source was extended on; the lime green area is filled.
  - `aspect_ratio_processed` boolean: Guided only. The source was padded to a new aspect ratio with lime green areas to fill.

## Response `202`

Job queued

- JobQueued
  - `success` boolean
  - `data` object
    - `job_id` integer
    - `generation_id` integer
    - `generation_uuid` string, uuid
    - `status` string
    - `estimated_credits` number, float
  - `timestamp` string, date-time

## Other responses

- `400`: No source image or both forms of it, a missing prompt, an unusable image, or invalid editing fields
- `401`: Missing or invalid API key
- `402`: Insufficient credits
- `403`: File belongs to another user
- `404`: Source file not found
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

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