How to authenticate, verify with get_me, introduce VideoGen with workflow example prompts, choose workflows vs media tools, and follow VideoGen id conventions. Call when connecting, onboarding, the user asks what VideoGen can do, or how to set up the API or MCP. Equivalent to reading the guidance://getting-started MCP resource — provided as a tool for clients that don't read resources directly.

How to handle async workflows, tool executions, and exports: statuses, hosted vs local wait caps, polling with get_* tools, and when webhooks apply outside MCP. Call before polling or when a start tool returns a still-running snapshot. Equivalent to reading the guidance://async-tasks MCP resource — provided as a tool for clients that don't read resources directly.

Canonical run → remix → export flow and when to use each workflow tool. Prefer script_to_video for longer narrated / informational videos; keep storyboard_to_video to ≤3 scenes unless the user asks for more. Call before starting a full video project. Equivalent to reading the guidance://workflows MCP resource — provided as a tool for clients that don't read resources directly.

When to use standalone media tools (automatic model routing for a single asset) versus workflows (full editable professional video). Call when choosing between generate_* tools and workflow tools. Equivalent to reading the guidance://tools-vs-workflows MCP resource — provided as a tool for clients that don't read resources directly.

Preferred for narrated / informational / explainer videos from text, especially ~1 minute or longer. Turn a verbatim narration script into an editable video with AI-generated visuals and captions. Prefer this over storyboard_to_video unless the user wants a short shot-directed storyboard. For avatar narration, pass actorEntityId and optionally set avatarQuality.

Build an editable video with AI-generated visuals from an uploaded voiceover audio file.

Build an editable narrated video from an uploaded PDF or slideshow file. Upload the file first with upload_file, then pass its fileId. For avatar narration, pass actorEntityId and optionally set avatarQuality.

Build an editable video from an ordered storyboard (frame-by-frame shot list). Every scene needs a visual prompt and may include spoken words. Much more credit-heavy than script_to_video: use at most 3 scenes unless the user explicitly asks for more. Prefer script_to_video for ~1 minute+ narrated / informational videos. If the user has not named a workflow, ask with pros/cons before calling this.

Generate one short AI video clip from a prompt inside an editable project.

List workflow runs, most recent first.

Fetch the current status and result of a single workflow run.

Request cancellation of an in-progress workflow run.

Generate an image from a text prompt, optionally conditioned on source images (image-to-image) and actor, product, or visual-style entity ids. Typically takes 15–60 seconds. Tell the user that wait up front.

Generate a video clip from a text prompt, source images, source videos, spokenDialogue, or reference audio. quality is optional (LOW, STANDARD, HIGH, or MAX). Typically takes 1–3 minutes (HIGH/MAX can be longer). Tell the user that wait up front and keep polling calmly.

Convert text into spoken audio using a selectable voice.

Generate a sound effect from a text prompt.

Generate a music track from a text prompt. Typically takes 1–5 minutes depending on track length. Tell the user that wait up front.

Generate an animated motion graphic video from a text prompt. Best for precise text animations (typing effects, kinetic typography, lower thirds) that stock or generated footage can't express. Outputs a transparent WebM overlay by default; set transparentBackground to false for an opaque MP4. Optionally pass reference media file ids to display or animate. Typically takes 2–5 minutes because VideoGen writes animation code and then renders it; complex prompts can take longer. Tell the user that wait before starting and keep polling calmly — a healthy in-progress job is expected.

Generate a talking-head avatar video from an ACTOR entity and an uploaded audio file. Pass actorEntityId and optionally set avatarQuality. Typically takes a few minutes (longer for longer audio). Tell the user that wait up front.

Convert a raster image into a vector (SVG).

Remove the background from an image.

Remove the background from a video.

Increase the resolution of an image.

Increase the resolution of a video.

Add 3D parallax motion to a still image, producing a video.

List past tool executions, most recent first.

Fetch the current status and results of a single tool execution.

Request cancellation of an in-progress tool execution.

List projects. API-created projects only by default; pass includeUiProjects to also include dashboard projects.

Fetch metadata and the shareable URL for a single project.

Export a project to an MP4 and return its status or download URL. Renders often take a few minutes. Tell the user that wait up front.

Fetch the current status of a project export. Poll until status is succeeded, failed, or cancelled.

Apply curated edits to an existing project. CONVERT_IMAGES_TO_VIDEOS generates AI video clips from every still and is expensive. Use ZOOM for cheap Ken Burns camera motion. Poll with list_project_remix_actions for status.

List the status of remix actions applied to a project.

Upload a local file to VideoGen and wait until it is processed. Returns the file with its id (vg_file_...) and signed URLs. Use the returned fileId for voiceover_to_video, slideshow_to_video, logos, or B-roll. To upload a remote asset, download it first and pass its local path.

Start an upload for a large file, or when file bytes cannot be inlined. Returns { fileId, uploadUrl }. PUT the raw file bytes to uploadUrl with NO Authorization header (it is a short-lived pre-signed URL). Then call get_file with { fileId, wait: true } to wait until processing finishes, and pass the returned fileId to workflows, tools, logos, or B-roll. For small files, prefer upload_file.

Fetch a file by id with freshly hydrated (non-expired) signed URLs for its thumbnail, preview, and download renditions. Set wait: true to poll until the file finishes processing — use this right after PUTting bytes to a create_file_upload URL.

List files visible to the current API key.

List built-in actors, products, visual styles, and slideshow themes plus team entities. Built-in rows have isBuiltIn true and cannot be updated or archived. Filter with entityType when you only need one kind.

Create an ACTOR (character), PRODUCT (product/object), VISUAL_STYLE, or SLIDESHOW_THEME entity. After create, attach at least one reference with add_entity_reference (upload the file first). Slideshow themes may attach an image or a PDF / PowerPoint. Use the returned entityId as actorEntityId on generate_avatar / script_to_video, a product/style reference in storyboard scenes, or slideshowThemeEntityId on slideshow_to_video.

Fetch one entity by id, including its reference images. Built-in catalog entities are included and have isBuiltIn true.

Update an entity's display name and/or description. Built-in entities cannot be updated.

Archive an entity so it no longer appears in lists or pickers. Built-in entities cannot be archived.

Attach an uploaded file (vg_file_...) as a reference on an entity. Images work for every entity type. Slideshow themes may also attach a PDF or PowerPoint. Built-in entities cannot have references added. For new PRODUCT/ACTOR entities, call this right after create_entity with isDefault: true so the entity has a usable thumbnail and generation reference.

Detach a reference image from an entity by file id. Built-in entities cannot have references removed.

List available text-to-speech voices for narration, text_to_speech, and workflows.

List supported languages for narration and captions.

Fetch the account and team behind the API key (apiKeyId, apiKeyNickname, email, displayName, teamId). Use it as a connection test.

Build a VideoGen app URL that opens a modal or navigates after the user signs in (upgrade, buy credits, enable top-ups, invite teammates, submit feedback, integrations, account settings, or a NAVIGATE destination). Prefer this when the user needs to complete something in the VideoGen UI that MCP tools cannot do inline — especially credits or plan gates. Return the url to the user so they can open it.