---
url: /orchestration/reference/operations/InvokeComposeMediaStepTemplate.md
description: 'POST /v2/consumer/recipes/composeMedia — Compose Media'
---

> Documentation index: https://developer.civitai.com/llms.txt — every page on this site has a markdown version at its URL + `.md`.

# Compose Media

`POST https://orchestration.civitai.com/v2/consumer/recipes/composeMedia`

Operation `InvokeComposeMediaStepTemplate` · Recipes · Civitai Orchestration API, generated from the published OpenAPI spec ([v2-consumers.json](https://developer.civitai.com/openapi/v2-consumers.json)); the interactive HTML page is this URL without `.md`.

Composes audio and/or video elements onto one timeline and canvas: overlay and stack videos, mix and place audio,
/// and apply per-element transformers (fades, volume). Produces a video blob when any element is video, otherwise an audio blob.

## Authentication

Send `Authorization: Bearer <token>` (the spec's `ApiKey` scheme); this operation documents `401 Unauthorized` for a missing or invalid token. See [Authentication](https://developer.civitai.com/orchestration/guide/authentication.md).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `experimental` | query | boolean | no |  |
| `allowMatureContent` | query | boolean | no |  |
| `whatif` | query | boolean | no |  |
| `ephemeral` | query | boolean | no |  |
| `tier` | query | `WorkflowTier` (one of `paid`, `free`) | no | How a workflow is paid for. |

## Request body

Optional. Content types: `application/json`, `text/json`, `application/*+json`.

Schema `ComposeMediaInput`.

| Field | Type | Required | Description |
|---|---|---|---|
| `elements` | array of `ComposeMediaElementInput` | yes | Elements in implicit sequencing order; overlapping audio is mixed, overlapping video is layered by canvas `zOrder` then array order. To stitch videos end-to-end, list them with no `at`/`offset`. |
| `canvas` | `MediaCanvas` | no | Output geometry for video output; when omitted, derived from the elements (largest video, fastest frame rate). Supplying a canvas does not by itself force video output — see `output`. |
| `output` | `ComposeMediaOutputSpec` | no | Desired output kind and container. When omitted, the kind is derived from the elements and the container defaults to MP4 (video) or Ogg (audio). |
| `normalize` | boolean | no | Divide the audio mix by the number of overlapping elements to avoid clipping. Defaults to false. (default `false`) |

### Types used by the request body

#### ComposeMediaElementInput

Schema `ComposeMediaElementInput` — A single audio or video element participating in a composition.

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string (uri), nullable | no | The source media URL. Either a direct `"https://..."` URL or a `$ref` to a prior step's `Output.AudioBlob.Url` or `Output.VideoBlob.Url`. |
| `at` | number (float), nullable | no | Absolute start time on the output timeline, in seconds; anchors the element outside the implicit sequencing chain (e.g. a music bed). When unset, the element starts after the previous non-anchored element ends, nudged by `offset`. |
| `offset` | number (float) | no | Seconds to shift this element from its after-previous position: negative overlaps, positive leaves a gap. Ignored when `at` is set. (default `0`) |
| `layout` | `MediaLayout` | no | Spatial placement of this element on the output canvas. Ignored for audio elements and for all-audio compositions. |
| `transformers` | array of `MediaTransformer` | no | Ordered per-element transformers (fades, volume, ...) applied in array order. |

#### MediaCanvas

Schema `MediaCanvas` — Output canvas geometry. Set this to produce a video composition; leave it null for an all-audio mixdown.

| Field | Type | Required | Description |
|---|---|---|---|
| `width` | integer (int32) | yes | Output width in pixels. |
| `height` | integer (int32) | yes | Output height in pixels. |
| `fps` | integer (int32) | no | (default `30`) |
| `background` | string | no | Hex background colour (e.g. `"#000000"`) painted where no element covers the canvas. An 8-digit `"#RRGGBBAA"` sets the alpha, which needs an alpha-capable output container (webp). (default `"#000000"`) |

#### ComposeMediaOutputSpec

Schema `ComposeMediaOutputSpec` — Describes the desired output of a composition. Both fields are optional — leave `type` unset to derive the kind from the elements.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `MediaOutputType` (one of `audio`, `video`) | no | Forces the output kind. When null, it is derived from the elements: video if any element is video or a canvas is supplied, otherwise audio. |
| `container` | `MediaContainer` (one of `auto`, `mp4`, `webm`, `ogg`, `mp3`, `webp`) | no | Output container. Auto selects MP4 for video and Ogg for audio. (default `"auto"`) |

## Responses

### 200 OK

Content type: `application/json`.

Schema `ComposeMediaOutput`.

Polymorphic: the `type` field selects the concrete type — `audio` → `AudioComposeMediaOutput`, `video` → `VideoComposeMediaOutput`.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | yes |  |
| `elements` | array of `ComposeMediaResolvedElement` | yes | Per-element resolved timing in input order — useful for rendering subtitles, speaker highlights, or chapter markers without re-probing every source clip. |

### 400 Bad Request

Content type: `application/json`.

Schema `ProblemDetails`.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string, nullable | no |  |
| `title` | string, nullable | no |  |
| `status` | integer (int32), nullable | no |  |
| `detail` | string, nullable | no |  |
| `instance` | string, nullable | no |  |

### 401 Unauthorized

Content type: `application/json`.

Schema `ProblemDetails` — fields as listed above.

### 403 Forbidden

Content type: `application/json`.

Schema `ProblemDetails` — fields as listed above.