Remix actions

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). 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, RESIZE_PROJECT, CLEAN_UP_TRANSCRIPT, CONVERT_IMAGES_TO_VIDEOS, REGENERATE_IMAGES, UPSCALE_ASSETS, CHANGE_NARRATOR, SHUFFLE_STOCK_VISUALS, GENERATE_MUSIC, TRANSLATE_PROJECT, and EDIT_WITH_AGENT; 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:

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 }.

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.

Set logo

SET_LOGO sets, replaces, or removes the logo overlay.

Enable captions

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

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. To change transitions on specific scenes only, use EDIT_WITH_AGENT instead.

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).

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.

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.

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).

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.

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.

Change narrator

CHANGE_NARRATOR re-narrates every AI-voiceover asset in the project with a new voice (and optionally a presenter 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.

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.

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.

Edit with agent

EDIT_WITH_AGENT applies an open-ended, natural-language edit. An editing agent interprets the prompt, makes the changes, validates them, and visually checks the result. It is well suited to tasks like replacing placeholder copy with your own text.

Example

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

1
import { VideoGenClient } from "@videogen/sdk";
2
3
const client = new VideoGenClient({ token: process.env.VIDEOGEN_API_KEY });
4
5
const { remixActionIds } = await client.projects.remixProject({
6
  projectId,
7
  remixActions: [
8
    { type: "SET_BACKGROUND_MUSIC", fileId: "vg_file_...", volume: 0.3 },
9
    { type: "SET_LOGO", fileId: "vg_file_...", position: "BOTTOM_RIGHT", sizePercent: 12 },
10
    { type: "EDIT_WITH_AGENT", prompt: "Replace the headline with 'Summer Sale - 40% off'" },
11
  ],
12
});
13
14
const { remixActions } = await client.projects.listProjectRemixActions({ projectId });
15
console.log(remixActions.map((action) => `${action.type}: ${action.status}`));

Endpoint reference