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

# Start video edits

POST https://api.videogen.io/v1/projects/{projectId}/video-edits
Content-Type: application/json

Apply ordered background edits to a specific video. Poll the video edit list for completion. Each edit retains its own status and runs after the previous edit applies.

Reference: https://docs.videogen.io/rest-api-reference/projects/start-video-edits

## Authentication

- `Authorization` header (bearer token, required) — API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

## Request

### Path parameters

- `projectId` (string, required)

### Body (application/json)

This endpoint expects a StartVideoEditsRequest.

- `editableVideoId` (string, required)
- `videoEdits` (list of VideoEditOperation, required)
- `saveAsNewProject` (boolean, optional, default: false)

## Response

### 202

Video edits accepted

- `projectId` (string, required)
- `projectUrl` (string, required)
- `videoEditIds` (list of string, required)

## Types

### VideoEditOperation

A single edit applied to a project. Each array entry is exactly one of the action types below, chosen by its `type` field; the variants are mutually-exclusive options, not fields you must all provide. Include only the actions you want.

- `type`: `SET_BACKGROUND_MUSIC` (SET_BACKGROUND_MUSIC)
  - `fileId` (string, optional, nullable) — File id of an uploaded audio file to use as background music (e.g. `vg_file_...`). Upload it first via `POST /v1/files/upload`. Pass `null` to remove the existing background music.
  - `volume` (double, optional, nullable) — Music volume from 0 (silent) to 1 (full). Omit or pass `null` to keep the current volume.
- `type`: `SET_LOGO` (SET_LOGO)
  - `fileId` (string, optional, nullable) — File id of an uploaded image to overlay as a logo (e.g. `vg_file_...`). Upload it first via `POST /v1/files/upload`. Pass `null` to remove the existing logo.
  - `position` (enum, optional) — Position the logo is anchored to. Omit or pass `null` to keep the current position.
    - Allowed values: `TOP_LEFT`, `TOP_CENTER`, `TOP_RIGHT`, `BOTTOM_LEFT`, `BOTTOM_CENTER`, `BOTTOM_RIGHT`
  - `sizePercent` (double, optional, nullable) — Logo width as a percentage of the video width. Omit or pass `null` to keep the current size.
- `type`: `ENABLE_CAPTIONS` (ENABLE_CAPTIONS)
  - `captionStyle` (WorkflowCaptionStyle, optional, nullable) — 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.
- `type`: `DISABLE_CAPTIONS` (DISABLE_CAPTIONS)
- `type`: `ADD_TRANSITIONS` (ADD_TRANSITIONS)
  - `assetTransition` (enum, optional, nullable) — 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.
    - Allowed values: `DYNAMIC`, `NONE`, `FADE`, `RISE`, `PAN`, `POP`, `WIPE`
  - `sectionTransition` (enum, optional, nullable) — Transition applied at every boundary between sections, replacing any existing section transitions. Omit or pass `null` to leave section transitions untouched.
    - Allowed values: `DYNAMIC`, `NONE`, `FADE`, `RISE`, `PAN`, `POP`, `WIPE`
- `type`: `ADD_ZOOM` (ADD_ZOOM)
- `type`: `RESIZE_PROJECT` (RESIZE_PROJECT)
  - `aspectRatio` (AspectRatio, required) — Aspect ratio as a width:height pair (e.g. 16 and 9 for 16:9). Not pixel dimensions.
- `type`: `CLEAN_UP_TRANSCRIPT` (CLEAN_UP_TRANSCRIPT)
  - `fillerWords` (list of string, optional, nullable) — Override the filler-word list to remove. Omit or pass `null` to use the built-in defaults.
  - `minPauseSeconds` (double, optional, nullable) — Shortest pause (in seconds) to remove; pauses below this stay. Omit or pass `null` to use the default threshold.
  - `removeFillers` (boolean, optional, nullable) — Remove filler words ("um", "uh", …). Defaults to `true`.
  - `removePauses` (boolean, optional, nullable) — Remove silent pauses longer than `minPauseSeconds`. Defaults to `true`.
- `type`: `CONVERT_IMAGES_TO_VIDEOS` (CONVERT_IMAGES_TO_VIDEOS)
  - `motionPrompt` (string, optional, nullable) — Describe the motion to apply to every image (e.g. "slow cinematic push-in"). Omit or pass `null` for automatic motion.
  - `muteOutputVideos` (boolean, optional, nullable) — Mute the generated clips and suppress generated background music. Recommended when the clips sit behind a voiceover. Defaults to `true`.
  - `quality` (enum, optional) — Video generation quality tier for the image-to-video conversions (`LOW`, `STANDARD`, `HIGH`, or `MAX`). Optional; when omitted, your account's Default AI quality for video is used (change it at https://app.videogen.io/settings/account).
    - Allowed values: `LOW`, `STANDARD`, `HIGH`, `MAX`
- `type`: `REGENERATE_IMAGES` (REGENERATE_IMAGES)
  - `stylePrompt` (string, required) — A full, strict paragraph for the look of every image (medium, texture, palette, then composition). Do not pass a short label such as `watercolor painting`. Image models pack the frame with text, charts, diagrams, and extra objects unless the style forbids that. Keep the picture simple: one uncluttered subject in the middle half of the frame, empty margins, and no on-image text or diagrams unless you asked for one specific word or number.
  - `quality` (enum, optional) — Image generation quality tier for the restyled images. Optional; when omitted, your account's Default AI quality for images is used (change it at https://app.videogen.io/settings/account).
    - Allowed values: `LOW`, `STANDARD`, `HIGH`, `MAX`
- `type`: `UPSCALE_ASSETS` (UPSCALE_ASSETS)
  - `includeStockContent` (boolean, optional, nullable) — Also upscale stock (library) assets, not just uploaded or generated ones. Defaults to `true`.
  - `includeVideos` (boolean, optional, nullable) — Also upscale video assets (billed per output second). Defaults to `true`.
- `type`: `CHANGE_NARRATOR` (CHANGE_NARRATOR)
  - `voiceId` (string, required) — Catalog `displayName` (e.g. `Matilda`) or voice id from `GET /v1/resources/tts-voices` (e.g. `vg_voic_...`) to re-narrate with.
  - `actorEntityId` (string, optional, nullable) — Recommended. Optional id of a built-in stock actor or an ACTOR entity (e.g. `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` (enum, optional) — Avatar generation quality tier. Applies when `actorEntityId` is provided. Optional; when omitted, your account's Default AI quality for avatars is used.
    - Allowed values: `LOW`, `STANDARD`, `HIGH`, `MAX`
  - `voiceSpeed` (double, optional, nullable) — Speech rate multiplier, between 0.5 (half speed) and 2 (double speed). Omit or pass `null` to keep each asset's current speed.
- `type`: `SHUFFLE_STOCK_VISUALS` (SHUFFLE_STOCK_VISUALS)
- `type`: `GENERATE_MUSIC` (GENERATE_MUSIC)
  - `prompt` (string, required) — Describe the music to generate (e.g. "upbeat corporate background music with a driving beat").
- `type`: `TRANSLATE_PROJECT` (TRANSLATE_PROJECT)
  - `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, optional, nullable) — 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`.
  - `dubVideos` (boolean, optional, nullable) — Also dub the speech in the project's uploaded videos into the target language, replacing their original audio. Expensive: billed per second of every video with speech, and each source file is dubbed once even when the project uses several clips of it. When `false`, those videos keep their original audio and their captions are still translated. Videos longer than 8 minutes keep their original audio. Rejected with a 400 if the target language does not support dubbing. Defaults to `false`.
  - `translateImageText` (boolean, optional, nullable) — 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`.

### WorkflowCaptionStyle

Caption styling. Any omitted field falls back to the VideoGen default caption style. Provide an empty object (`{}`) to keep the default style but ensure captions are shown. Pass `null` for the whole `captionStyle` field to hide captions entirely.

- `fontName` (string, optional) — Font family name.
- `fontSize` (double, optional) — Font size in pixels at 1080p. Must be greater than 0.
- `fontWeight` (enum, optional) — Numeric font weight (400 = regular, 700 = bold).
  - Allowed values: `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`
- `textColor` (WorkflowRgbColor, optional) — An RGB color. Each channel is an integer from 0 to 255.
- `textJustification` (enum, optional)
  - Allowed values: `LEFT`, `CENTER`, `RIGHT`
- `verticalAlignment` (enum, optional) — Vertical position of the caption block in the frame.
  - Allowed values: `TOP`, `MIDDLE`, `BOTTOM`
- `strokeColor` (WorkflowRgbColor, optional, nullable) — Outline color around glyphs, or null for no outline.
- `strokeWeight` (double, optional) — Outline thickness in pixels. 0 disables the outline.
- `backgroundStyle` (WorkflowCaptionBackgroundStyle, optional, nullable) — Background drawn behind the text, or null for no background.
- `spokenTextColor` (WorkflowRgbColor, optional, nullable) — Color applied to the currently spoken word for karaoke-style highlighting, or null to keep the base text color.
- `spokenTextStrokeColor` (WorkflowRgbColor, optional, nullable) — Outline color applied to the currently spoken word, or null.
- `persistSpokenTextColor` (boolean, optional) — When true, a word keeps the spoken-text color after it has been spoken instead of reverting.

### AspectRatio

Aspect ratio as a width:height pair (e.g. 16 and 9 for 16:9). Not pixel dimensions.

- `width` (integer, required)
- `height` (integer, required)

### WorkflowRgbColor

An RGB color. Each channel is an integer from 0 to 255.

- `red` (integer, required)
- `green` (integer, required)
- `blue` (integer, required)

### WorkflowCaptionBackgroundStyle

Background drawn behind caption text.

- `type` (enum, required) — RECT draws one rectangle behind the whole line; WRAPPED hugs the text; WORD_BY_WORD draws a box per word.
  - Allowed values: `RECT`, `WRAPPED`, `WORD_BY_WORD`
- `backgroundColor` (WorkflowRgbColor, required) — An RGB color. Each channel is an integer from 0 to 255.
- `borderRadiusProportion` (double, optional) — Corner rounding as a proportion of the background height, between 0 (square corners) and 1 (fully rounded).
- `opacityProportion` (double, optional) — Background opacity from 0 (transparent) to 1 (opaque).

## Examples

**Request**

```json
{
  "editableVideoId": "string",
  "videoEdits": [
    {
      "type": "SET_BACKGROUND_MUSIC"
    }
  ]
}
```

**Response**

```json
{
  "projectId": "string",
  "projectUrl": "string",
  "videoEditIds": [
    "string"
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.videogen.io/v1/projects/projectId/video-edits"

payload = {
    "editableVideoId": "string",
    "videoEdits": [{ "type": "SET_BACKGROUND_MUSIC" }]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```