---
title: "Start a product-mockup generation (async)"
method: POST
path: "/v1/images/mockup"
tags: ["Images"]
---

# Start a product-mockup generation (async)

`POST /v1/images/mockup`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/images/mockup`
- 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`)

Places one or more product images into a generated scene.

ASYNCHRONOUS, and NOT through the normal job endpoint: it returns a `job_id`
that is polled with `GET /v1/images/mockup-status`, not with `GET /v1/jobs/{id}`.
Give the product image as a library file uuid (`file_uuid`), or INLINE as base64
(`images`, or the single-image `imageData` + `mimeType` pair).

## Request body

- object
  - `prompt` string, required: What the mockup scene should show.
  - `file_uuid` string, uuid: Uuid of a library image to place in the scene. Use this or the inline `images` / `imageData`.
  - `images` object[]: Product images. Each entry is {data, mimeType}. Alternatively send the single-image `imageData` + `mimeType` pair.
    - `data` string
    - `mimeType` string
  - `imageData` string: Single-image alternative to `images`: a base64 payload. Requires `mimeType`.
  - `mimeType` string: Mime type of `imageData`.
  - `variability` integer: How many variations to produce. Defaults to 1.
  - `modelVariant` string: Model variant. Defaults to `standard`.
  - `modelOptions` object: Per-model options; see GET /v1/models.

## Response `200`

Queued. Poll GET /v1/images/mockup-status with the returned job_id.

- object
  - `success` boolean
  - `data` object
  - `timestamp` string, date-time

## Other responses

- `400`: No image (`file_uuid`, `images` or `imageData`/`mimeType`), or file_uuid together with inline data.
- `401`: Missing or invalid API key.
- `402`: Insufficient credits.
- `403`: file_uuid belongs to another user.
- `404`: file_uuid was 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)