> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# Remix actions

> Reference for VideoGen remix actions: background music, logo overlay, caption visibility and style, section and asset transitions, and natural-language editor edits. Apply them in a workflow call or via POST /v1/projects/{projectId}/remix.

A remix action is a single edit applied to a project after a workflow builds it. You send an ordered list of actions; each runs asynchronously as its own remix action. Independent actions run in parallel while actions that touch the same part of the project preserve your request order (see [Execution model](#execution-model)). This page documents every action type and the two ways to run them.

The `remixActions` array is optional, and so is each action type within it. The action types are `SET_BACKGROUND_MUSIC`, `SET_LOGO`, `ENABLE_CAPTIONS`, `DISABLE_CAPTIONS`, `ADD_TRANSITIONS`, `ADD_ZOOM`, `RESIZE_PROJECT`, `CLEAN_UP_TRANSCRIPT`, `CONVERT_IMAGES_TO_VIDEOS`, `REGENERATE_IMAGES`, `UPSCALE_ASSETS`, `CHANGE_NARRATOR`, `SHUFFLE_STOCK_VISUALS`, `GENERATE_MUSIC`, and `TRANSLATE_PROJECT`; a given array entry is exactly one of them, picked by its `type`. You only include the actions you want. In the API reference each type is shown as a variant of the `remixActions` items, so pick the ones that fit your video.

## Recommended actions by workflow

Some actions pair naturally with specific workflows. These are recommendations, not requirements:

| Workflow           | Recommended actions                                                          | Why                                                                                                                                                                         |
| ------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Script to video    | `ENABLE_CAPTIONS`, `CONVERT_IMAGES_TO_VIDEOS`, `ADD_TRANSITIONS`, `SET_LOGO` | Script to video has no native caption-style or logo fields, so captions styling, image-to-video animation, transitions between sections, and a logo overlay are added here. |
| Voiceover to video | `CONVERT_IMAGES_TO_VIDEOS`, `ADD_TRANSITIONS`                                | Captions and a logo are set directly with the `captionStyle` and `logoFileId` request fields; use remix actions to animate still images into clips and add transitions.     |
| Slideshow to video | `ADD_TRANSITIONS`, `SET_BACKGROUND_MUSIC`                                    | Transitions between slides are the highest-impact polish for a deck; captions and a logo have native fields, so remix actions cover transitions and music.                  |

## Running remix actions

There are two entry points:

* In a workflow request, via the `remixActions` array. Each action runs after the video is built. The workflow response returns one remix action id per entry in `remixActionIds`.
* On an existing project, via `POST /v1/projects/{projectId}/remix`. The response returns `{ projectId, projectUrl, remixActionIds }`. Use `projectId` for polling remix status; `projectUrl` is optional (opens the project in the app editor for manual review).

Pass `saveAsNewProject: true` on the remix endpoint to duplicate the project first and apply the edits to the copy, leaving the original untouched. The response `projectId` is then the copy.

## Tracking status

Poll `GET /v1/projects/{projectId}/remix-actions` to list every remix action applied to a project, most recent first. Each entry includes its `remixActionId`, `type`, `status` (`pending`, `running`, `succeeded`, `failed`, `cancelled`), and `progressPercentage`.

## Execution model

Remix actions are not run blindly one after another. When you submit a list, VideoGen analyzes which parts of the project each action reads and writes, then schedules the actions as a dependency graph so independent edits run concurrently and dependent edits stay correctly ordered.

The scheduling works in two steps:

1. Each action declares the project resources it touches (its music track, the logo, captions, transitions, the aspect ratio, the transcript, or asset media). An action can claim more than one resource when it reads something another action writes.
2. Actions whose resource sets overlap (directly, or transitively through a shared action) are grouped into a single serial chain that preserves your request order. Chains with no shared resources have no ordering relationship and are dispatched in parallel.

This gives you the best of both: order is guaranteed exactly where it matters, and unrelated work does not wait in line behind it.

A few consequences worth knowing:

* Conflicting writes to the same resource resolve as last-write-wins in request order. Two `SET_LOGO` actions run in sequence, and the second one wins.
* `ENABLE_CAPTIONS` followed by `DISABLE_CAPTIONS` serialize, so the final state reflects the last of the two.
* `RESIZE_PROJECT` and `CONVERT_IMAGES_TO_VIDEOS` (or `REGENERATE_IMAGES`) serialize even though one changes the aspect ratio and the other regenerates media. Media generation reads the current aspect ratio when it builds each asset, so the resize must finish first to avoid baking in a stale ratio.
* Unrelated edits (for example background music, a logo, and transitions) run at the same time, so a long-running action does not block faster ones.

You do not configure any of this. Submit the actions in the order you want for the cases where order matters, and the scheduler parallelizes the rest. Order is still observable through `GET /v1/projects/{projectId}/remix-actions`, which lists every action with its individual status and progress.

## Action types

### Set background music

`SET_BACKGROUND_MUSIC` sets, replaces, or removes the project's background music track.

| Field    | Type             | Description                                                                                                                  |
| -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `fileId` | `string \| null` | File id of an uploaded audio file to use as music. Upload via the Files API first. Pass `null` to remove the existing music. |
| `volume` | `number \| null` | Volume from 0 (silent) to 1 (full). Omit or pass `null` to keep the current volume.                                          |

### Set logo

`SET_LOGO` sets, replaces, or removes the logo overlay.

| Field         | Type             | Description                                                                                                                                         |
| ------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fileId`      | `string \| null` | File id of an uploaded image to overlay. Upload via the Files API first. Pass `null` to remove the existing logo.                                   |
| `position`    | `string \| null` | Anchor: `TOP_LEFT`, `TOP_CENTER`, `TOP_RIGHT`, `BOTTOM_LEFT`, `BOTTOM_CENTER`, or `BOTTOM_RIGHT`. Omit or pass `null` to keep the current position. |
| `sizePercent` | `number \| null` | Logo width as a percentage of the video width. Omit or pass `null` to keep the current size.                                                        |

### Enable captions

`ENABLE_CAPTIONS` shows captions on every captionable section. Optionally override the caption style.

| Field          | Type             | Description                                                                                                                                                              |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `captionStyle` | `object \| null` | Caption styling to apply. Omit or pass `null` to show captions with the current style. Any provided field overrides that field; omitted fields keep their current value. |

### Disable captions

`DISABLE_CAPTIONS` hides captions on every captionable section. It takes no additional fields.

### Add transitions

`ADD_TRANSITIONS` stamps transitions across the project. It is not per-boundary: each field you set is applied uniformly to *every* boundary in that scope, replacing any transition already there. There are two independent scopes, and a scope you omit (or set to `null`) is left untouched.

Each style is one of `DYNAMIC` (auto-varies the style from one boundary to the next), `NONE` (removes transitions in that scope), `FADE`, `RISE`, `PAN`, `POP`, or `WIPE` (the same fixed style on every boundary in that scope).

| Field               | Type             | Description                                                                                                                                                                         |
| ------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sectionTransition` | `string \| null` | Transition applied at every boundary between sections, replacing any existing section transitions. Omit or pass `null` to leave section transitions untouched.                      |
| `assetTransition`   | `string \| null` | Transition applied at every boundary between base-layer assets within sections, replacing any existing asset transitions. Omit or pass `null` to leave asset transitions untouched. |

### Add zoom

`ADD_ZOOM` applies a Ken Burns zoom to every eligible still image in the project, including uploaded images. It replaces any existing still-image effect on those assets. It takes no additional fields.

If the project has no eligible stills, the action is skipped and completes successfully without changing anything.

### Resize project

`RESIZE_PROJECT` changes the project's output aspect ratio (for example to a vertical 9:16 social format). The video is re-flowed to the new ratio.

| Field         | Type     | Description                                                                                                |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `aspectRatio` | `object` | Required. A width:height pair (e.g. `width: 9`, `height: 16` for a vertical format). Not pixel dimensions. |

### Clean up transcript

`CLEAN_UP_TRANSCRIPT` tightens every transcript in the project by removing silent pauses and/or filler words. It is useful for polishing narration captured from raw recordings.

| Field             | Type              | Description                                                                                                      |
| ----------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `removeFillers`   | `boolean \| null` | Remove filler words ("um", "uh", …). Defaults to `true`.                                                         |
| `removePauses`    | `boolean \| null` | Remove silent pauses longer than `minPauseSeconds`. Defaults to `true`.                                          |
| `fillerWords`     | `array \| null`   | Override the filler-word list to remove. Omit or pass `null` to use the built-in defaults.                       |
| `minPauseSeconds` | `number \| null`  | Shortest pause (in seconds) to remove; pauses below this stay. Omit or pass `null` to use the default threshold. |

### Convert images to videos

`CONVERT_IMAGES_TO_VIDEOS` animates every eligible still image in the project into a short AI video clip (image-to-video), replacing each image in place. Eligible images are non-SVG image assets backed by an uploaded or stock file. It runs asynchronously, generating one clip per image.

If the project has no eligible images, the action is skipped. It completes successfully without changing anything (for example, a project whose timeline is already all video clips has nothing to animate).

| Field              | Type              | Description                                                                                                                              |
| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `motionPrompt`     | `string \| null`  | Describe the motion to apply to every image (e.g. "slow cinematic push-in"). Omit or pass `null` for automatic motion.                   |
| `muteOutputVideos` | `boolean \| null` | Mute the generated clips and suppress generated background music. Recommended when the clips sit behind a voiceover. Defaults to `true`. |
| `quality`          | `string`          | Video generation quality tier: `STANDARD` (default) or `HIGH`.                                                                           |

### Regenerate images

`REGENERATE_IMAGES` restyles every eligible still image in the project to a new look (image-to-image), replacing each image in place. Eligible images are non-SVG image assets backed by an uploaded or generated file. It runs asynchronously, generating one restyled image per eligible image.

If the project has no eligible images, the action is skipped. It completes successfully without changing anything.

| Field         | Type     | Description                                                                                                                                                                                                                                                                 |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stylePrompt` | `string` | Required. A full, strict paragraph for the look (medium, texture, palette, then a simple composition lock). Do not pass a short label such as "watercolor painting". Image models pack the frame with text, charts, and diagrams unless the style keeps the picture simple. |
| `quality`     | `string` | Image generation quality tier: `STANDARD` (default) or `HIGH`.                                                                                                                                                                                                              |

### Upscale assets

`UPSCALE_ASSETS` sharpens every eligible asset in the project up to 4K, replacing each in place. It runs asynchronously, generating one upscaled asset per eligible asset.

If the project has no eligible assets, the action is skipped. It completes successfully without changing anything.

| Field                 | Type              | Description                                                                                   |
| --------------------- | ----------------- | --------------------------------------------------------------------------------------------- |
| `includeVideos`       | `boolean \| null` | Also upscale video assets (billed per output second). Defaults to `true`.                     |
| `includeStockContent` | `boolean \| null` | Also upscale stock (library) assets, not just uploaded or generated ones. Defaults to `true`. |

### Change narrator

`CHANGE_NARRATOR` re-narrates every AI-voiceover asset in the project with a new voice (and optionally an actor avatar), replacing each narration in place. It runs asynchronously, re-firing text-to-speech per asset with the original narration text.

If the project has no AI-narrated assets, the action is skipped. It completes successfully without changing anything.

| Field           | Type                             | Description                                                                                                                                                                                |
| --------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `voiceId`       | `string`                         | Required. Catalog `displayName` (e.g. `Matilda`) or voice id from `GET /v1/resources/tts-voices` to re-narrate with.                                                                       |
| `actorEntityId` | `string \| null`                 | Recommended. Optional ACTOR entity id (`vg_enti_...`) with an image reference. When set, narration is delivered by that actor avatar. Omit or pass `null` for voiceover without an avatar. |
| `avatarQuality` | `LOW \| STANDARD \| HIGH \| MAX` | Avatar generation quality tier. Applies when `actorEntityId` is set. Omit to use your account's default avatar quality.                                                                    |
| `voiceSpeed`    | `number \| null`                 | Speech rate multiplier. Omit or pass `null` to keep each asset's current speed.                                                                                                            |

### Shuffle stock visuals

`SHUFFLE_STOCK_VISUALS` replaces every stock (library) visual in the project with a fresh alternative from the same search, replacing each in place. It runs asynchronously, re-running each stock asset's original search while excluding the currently-shown result. It takes no additional fields.

If the project has no shuffleable stock visuals, the action is skipped. It completes successfully without changing anything.

### Generate music

`GENERATE_MUSIC` generates a background music track from a text prompt and sets it as the project's background music, replacing any existing track. It runs asynchronously.

| Field    | Type     | Description                                                                                              |
| -------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `prompt` | `string` | Required. Describe the music to generate (e.g. "upbeat corporate background music with a driving beat"). |

### Translate project

`TRANSLATE_PROJECT` translates the whole project into another language: every piece of text (title, section names, on-screen text overlays, transcripts, and narration scripts) is translated, and — unless disabled — each AI voiceover is re-narrated in the new language. It runs asynchronously and requires a Pro subscription. Retrieve the list of supported language codes from `GET /v1/resources/languages`.

| Field                | Type              | Description                                                                                                                                                                       |
| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `languageCode`       | `string`          | Required. Target language code to translate the project into (e.g. `es`, `fr`, `ja`). Must be one of the codes returned by `GET /v1/resources/languages`.                         |
| `changeVoice`        | `boolean \| null` | Swap each AI voiceover to a voice that natively matches the target language. Recommended, since keeping the original voice usually produces a foreign accent. Defaults to `true`. |
| `translateImageText` | `boolean \| null` | Also re-generate every eligible image so that text baked into the image is translated too (image-to-image). Billed per generated image. Defaults to `false`.                      |

## Example

Apply music and a logo to an existing project, then poll for completion:

#### TypeScript

```typescript
import { VideoGen } from "@videogen/sdk";

const client = new VideoGen({ apiKey: "sk_videogen_live_..." });

const { remixActionIds } = await client.projects.remixProject({
  projectId,
  remixActions: [
    { type: "SET_BACKGROUND_MUSIC", fileId: "vg_file_...", volume: 0.3 },
    { type: "SET_LOGO", fileId: "vg_file_...", position: "BOTTOM_RIGHT", sizePercent: 12 },
  ],
});

const { remixActions } = await client.projects.listProjectRemixActions({ projectId });
console.log(remixActions.map((action) => `${action.type}: ${action.status}`));
```

#### cURL

```bash
curl -X POST https://api.videogen.io/v1/projects/PROJECT_ID/remix \
  -H "Authorization: Bearer sk_videogen_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "remixActions": [
      { "type": "SET_BACKGROUND_MUSIC", "fileId": "vg_file_...", "volume": 0.3 },
      { "type": "SET_LOGO", "fileId": "vg_file_...", "position": "BOTTOM_RIGHT", "sizePercent": 12 }
    ]
  }'

# Poll for status
curl https://api.videogen.io/v1/projects/PROJECT_ID/remix-actions \
  -H "Authorization: Bearer sk_videogen_live_..."
```

## Endpoint reference

| Method | Path                                     | Purpose                                                                         |
| ------ | ---------------------------------------- | ------------------------------------------------------------------------------- |
| `POST` | `/v1/projects/{projectId}/remix`         | Apply an ordered list of remix actions. Returns one remix action id per action. |
| `GET`  | `/v1/projects/{projectId}/remix-actions` | List remix actions for a project, most recent first, with status and progress.  |