Images

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

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.

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)

Request body

file_uuidstring

UUID of a source image already in your library. Use this or image_data.

image_datastring

The source image inline, as base64 or a data URL (PNG, JPEG, WebP or GIF). Use this or file_uuid.

promptstring

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.

variabilityinteger

How far the result may stray from the source (1 = subtle, 5 = experimental).

guidedboolean

Wrap the prompt in the Image Variator instructions and allow the editing fields below.

mask_datastring

Guided only. Inpainting mask as base64 PNG, same size as the source: black pixels are regenerated, the rest is kept.

extension_direction'top' | 'right' | 'bottom' | 'left'

Guided only. The side the source was extended on; the lime green area is filled.

aspect_ratio_processedboolean

Guided only. The source was padded to a new aspect ratio with lime green areas to fill.

Example request

{
  "file_uuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "prompt": "Same composition, but at sunset with warm golden light"
}

Response

Job queued

successboolean
timestampstring date-time

Example response

{
  "success": true,
  "data": {
    "status": "pending"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.