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

# Slideshow to video

POST https://api.videogen.io/v1/workflows/slideshow-to-video
Content-Type: application/json

Creates a project from an uploaded PDF or PowerPoint file and generates an AI-narrated video walking through each slide. Upload the file via `POST /v1/files/upload` first.

Reference: https://docs.videogen.io/rest-api-reference/workflows/slideshow-to-video

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

### Body (application/json)

This endpoint expects a SlideshowToVideoRequest.

- `fileId` (string, required) — Opaque file id of an uploaded PDF or PowerPoint file (e.g. `vg_file_...`). Upload the file first via `POST /v1/files/upload`.
- `slideScripts` (list of string, optional) — Optional per-slide narration, in slide order, applied by index: each slide uses its matching entry, and an empty string makes that slide silent. If you provide fewer entries than slides, the remaining slides are silent; extra entries are ignored. Omit this field entirely to narrate each slide from its speaker notes in the uploaded file. To guarantee no narration on any slide, pass an empty array.
- `aspectRatio` (AspectRatio, optional) — Aspect ratio as a width:height pair (e.g. 16 and 9 for 16:9). Not pixel dimensions.
- `language` (string, optional) — Output language as a BCP-47 code (e.g. `en`, `es`, `fr`). Defaults to English.
- `voiceId` (string, optional, nullable) — Catalog `displayName` (e.g. `Matilda`) or voice id from `GET /v1/resources/tts-voices` (e.g. `vg_voic_...`). A default voice is used when omitted. Any voice may be used here, including voices where `supportsDirectToolExecution` is false.
- `voiceSpeed` (double, optional) — Speech rate multiplier, between 0.5 (half speed) and 2 (double speed). Defaults to the voice's default speed.
- `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`
- `slideshowThemeEntityId` (string, optional) — Optional id of a SLIDESHOW_THEME entity (e.g. `vg_enti_...`) whose reference board defines the shared slide design system (fonts, colors, layout) applied to generated or edited slides. Create one via `POST /v1/entities` with `entityType` SLIDESHOW_THEME and attach a reference image or a PDF / PowerPoint. Omit when converting an uploaded deck's original pages into a video; VideoGen derives a theme from those pages in the background so later edits can match the original slides.
- `captionStyle` (WorkflowCaptionStyle, optional, nullable) — Caption styling. Omit to use the default style with captions shown. Pass an object to override individual style fields (any omitted field uses the default). Pass `null` to hide captions entirely.
- `logoFileId` (string, optional, nullable) — Optional file id of an uploaded logo image to overlay on the video (e.g. `vg_file_...`). Upload the image first via `POST /v1/files/upload`. Only image files are accepted.
- `remixActions` (list of RemixAction, optional) — Optional edits applied to the project after the video is built, in order. Each action runs asynchronously; the response returns one remix action id per action. Captions and a logo are set with the `captionStyle` and `logoFileId` request fields above; recommended remix actions here are `CONVERT_IMAGES_TO_VIDEOS` to animate still images into clips, and `ADD_TRANSITIONS` to stamp transitions between sections and assets. See the [Remix actions](/remix-actions) guide.
- `isOutputTemporary` (boolean, optional, default: false) — When true, the video's generated OUTPUT files (AI images, video clips, voiceover audio, avatars) are created as temporary: guaranteed available for 24 hours, after which they may be archived and later deleted. This also covers files produced by post-build remix actions (e.g. generated background music, image-to-video conversions). Use this when your integration downloads or re-hosts the results itself and does not need VideoGen to retain them. The project and its metadata are unaffected. Defaults to false.
- `hideFromUi` (boolean, optional, default: false) — When true, the project is hidden from Home and Projects by default, and generated files are hidden from the Media page. The project and files remain accessible through the API. Defaults to false.
- `autoExport` (boolean, optional, default: false) — When true, VideoGen exports an MP4 after the video is built (and after any `remixActions` on this request finish). The workflow run stays `running` until that export succeeds or fails. On success, poll `GET /v1/workflows/runs/{workflowRunId}` and use `downloadUrl`. Defaults to false.
- `exportOptions` (ExportProjectRequest, optional) — Export settings used when `autoExport` is true. Ignored when `autoExport` is false. Omitted fields use the same defaults as `POST /v1/projects/{projectId}/export`.

## Response

### 202

Workflow run accepted.

- `workflowRunId` (string, required) — Opaque workflow run id (e.g. `vg_work_...`).
- `projectId` (string, required) — Id of the project created for this workflow run (e.g. `vg_proj_...`).
- `projectUrl` (string, required) — Deep link to open this project in the VideoGen web editor. Not required for an API-only integration: store `projectId` and use the Projects API (export, remix, metadata). Use `projectUrl` when a person should open the project in the app to review or edit it manually. The project is visible only to members of your team and any project collaborators, the same access model as a project created in the dashboard.
- `remixActionIds` (list of string, required) — Opaque remix action ids (e.g. `vg_rmix_...`), one per `remixActions` entry in request order. Empty when no remix actions were requested. Each runs after the video is built; poll `GET /v1/projects/{projectId}/remix-actions`.

## Types

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

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

### RemixAction

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

### ExportProjectRequest

- `quality` (enum, optional) — Vertical resolution tier for the rendered MP4.
  - Allowed values: `STANDARD`, `HIGH`, `FULL_HIGH`, `ULTRA_HIGH`
- `watermarkMode` (enum, optional, default: AUTO) — Controls whether the VideoGen watermark is applied to the output. `AUTO` applies the watermark unless you have a Pro plan. `VIDEO_GEN` always applies it. `NONE` removes the watermark (requires Pro; returns an error if you don't have it).
  - Allowed values: `NONE`, `VIDEO_GEN`, `AUTO`
- `endScreenMode` (enum, optional, default: AUTO) — Controls whether a short 'Made with VideoGen' end screen is appended to the output. `AUTO` appends it unless you have a Pro plan. `VIDEO_GEN` always appends it. `NONE` removes it (requires Pro; returns an error if you don't have it).
  - Allowed values: `NONE`, `VIDEO_GEN`, `AUTO`
- `deliveryDestinations` (list of ExportDeliveryDestination, optional) — Destinations to deliver the finished export to when it completes, in addition to any delivery destinations already saved for the team. Each destination references a connected integration.

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

### ExportDeliveryDestination

- `integrationConnectionId` (string, required) — Id of the connected integration that will receive this export.
- `type` (enum, required) — Where to deliver the export within the connected integration.
  - Allowed values: `SLACK_CHANNEL`, `GOOGLE_DRIVE_FOLDER`
- `slackChannelId` (string, optional, nullable) — Target channel id. Required when `type` is `SLACK_CHANNEL`.
- `googleDriveFolderId` (string, optional, nullable) — Target folder id. Required when `type` is `GOOGLE_DRIVE_FOLDER`.

## Examples

**Request**

```json
{
  "fileId": "vg_file_obLD1OX2eJCrEs0071Z4kA",
  "actorEntityId": "vg_enti_3mK8qR2vN5xT7wP1cL9dFs",
  "avatarQuality": "HIGH",
  "slideshowThemeEntityId": "vg_enti_8kP2nW4sL6qR0tY3bH5mCz",
  "remixActions": [
    {
      "type": "ADD_TRANSITIONS",
      "assetTransition": "FADE",
      "sectionTransition": "DYNAMIC"
    },
    {
      "type": "CONVERT_IMAGES_TO_VIDEOS",
      "motionPrompt": "subtle zoom with soft easing",
      "muteOutputVideos": true,
      "quality": "HIGH"
    }
  ],
  "autoExport": true
}
```

**Response**

```json
{
  "workflowRunId": "vg_work_ccm3abc123defcm3xyz789ghi",
  "projectId": "vg_proj_9dTk3mQ1rZ7xP4vN2sB6wc",
  "projectUrl": "https://app.videogen.io/project/1f0a2b3c-4d5e-6789-ab12-cdef34567890",
  "remixActionIds": [
    "vg_rmix_ka9d2mZq7vTb1n0847PceR",
    "vg_rmix_pQ0s6xLm4dWc9r2318YgHt"
  ]
}
```

**SDK Code**

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

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

const run = await client.workflows.slideshowToVideoAndWait({
  fileId: "vg_file_obLD1OX2eJCrEs0071Z4kA",
  actorEntityId: "vg_enti_3mK8qR2vN5xT7wP1cL9dFs",
  avatarQuality: "HIGH",
  slideshowThemeEntityId: "vg_enti_8kP2nW4sL6qR0tY3bH5mCz",
  autoExport: true,
  remixActions: [
    {
      type: "ADD_TRANSITIONS",
      sectionTransition: "DYNAMIC",
      assetTransition: "FADE",
    },
    {
      type: "CONVERT_IMAGES_TO_VIDEOS",
      motionPrompt: "subtle zoom with soft easing",
      muteOutputVideos: true,
      quality: "HIGH",
    },
  ],
});
console.log(run.downloadUrl);
```

```python
from videogen import VideoGen

client = VideoGen(api_key="sk_videogen_live_...")

run = client.workflows.slideshow_to_video_and_wait(
    file_id="vg_file_obLD1OX2eJCrEs0071Z4kA",
    actor_entity_id="vg_enti_3mK8qR2vN5xT7wP1cL9dFs",
    avatar_quality="HIGH",
    slideshow_theme_entity_id="vg_enti_8kP2nW4sL6qR0tY3bH5mCz",
    auto_export=True,
    remix_actions=[
      {
        "type": "ADD_TRANSITIONS",
        "section_transition": "DYNAMIC",
        "asset_transition": "FADE",
      },
      {
        "type": "CONVERT_IMAGES_TO_VIDEOS",
        "motion_prompt": "subtle zoom with soft easing",
        "mute_output_videos": True,
        "quality": "HIGH",
      },
    ],
)
print(run.download_url)
```