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, in request order. 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. There are six action types (SET_BACKGROUND_MUSIC, SET_LOGO, ENABLE_CAPTIONS, DISABLE_CAPTIONS, ADD_TRANSITIONS, 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:

storyboard-to-video does not accept remix actions.

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.

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

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