VideoGen

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. For a BRAND, set role BRAND_LOGO for its overlay logo or BRAND_STYLE_GUIDE for its visual generation reference. 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.

Soft-archive a team entity so it no longer appears in lists or pickers. Returns entityId and archived. This tool has no restore operation; retrying an archived entity can fail because it is no longer active. Built-in entities cannot be archived.

Cancel this unpaid order. If payment already settled, return its paid outcome; this does not refund a settled payment. Check status after a cancellation or payment race.

Request cancellation of an API-started media generation or transformation. Pending work is stopped; completed files are not deleted. Any open review for a completed result is dismissed. Returns only toolExecutionId as an acknowledgment; use get_tool_execution to read status and results.

Request cancellation of an API-started workflow and its related generation, remix, and export tasks. This stops pending work; it does not delete the project or undo completed work. Terminal runs are unchanged. Returns workflowRunId, projectId, projectUrl, and remixActionIds as an acknowledgment; use get_workflow_run for status.

Sensitive write: pay only this exact quoted order after explicit approval of its complete terms. Requires a compatible wallet supplying a scoped credential through secure request metadata. Never ask the user to paste payment credentials or put them in arguments. Reuse the original order, revision and idempotency key after an uncertain outcome. A paid result is separate from fulfilled credits. No recurring subscriptions.

Prepare a one-time credit quote for an eligible active USD subscriber, without paying or generating. Use a fresh UUID for a new quote and reuse it for quote retries. Show seller, beneficiary team, credits, total, currency, taxes, fees, expiry and refund terms before asking approval. Existing accounts and credentials have billing access off until explicitly enabled in VideoGen.

Create an ACTOR (character), PRODUCT (something the user sells or promotes), VISUAL_STYLE, SLIDESHOW_THEME, BRAND, LOCATION (place or set), or PROP (background object that is not for sale) entity. Anything the user sells is a PRODUCT, never a PROP. A BRAND accepts brandConfig with fonts, colors, and writingStyle. Returns the new entity record with entityId and references. After create, attach references 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 / slideshow_to_video, as productEntityIds or actorEntityIds on storyboard_to_video (request and each scene that should show it), as visualStyleEntityId on each storyboard scene, or as slideshowThemeEntityId on slideshow_to_video.

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.

Use when the user wants to download or deliver a finished VideoGen video as an MP4. Export the existing editable project; this does not publish to social media or an ad account. Wait for pending generation or remix work before exporting. Returns exportId on hosted clients; poll get_project_export with the same projectId for status, progress, errors, and downloadUrl when ready. Local calls wait for an export snapshot. Exports often take a few minutes; explain that wait before starting.

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. Returns toolExecutionId; get_tool_execution provides status and results with the avatar video file and download URL.

Use for a standalone AI image: product imagery, ad concepts, storyboard frames, or campaign visuals. Generate from a prompt, optionally using source images and saved actor, product, or visual-style entity ids. References guide the result without guaranteeing exact reproduction. Creates an image file using team credits; it does not create a finished video project. Typically takes 15–60 seconds; explain that wait before starting. Poll get_tool_execution for the output file and downloadUrl.

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 music track from a text prompt. Typically takes 1–5 minutes depending on track length. Tell the user that wait up front.

Synthesize a standalone audio effect from a description of the desired sound and timing. Returns toolExecutionId; use get_tool_execution to retrieve the generated audio file and download URL.

Use for standalone text to video or image to video: animate a product photo, generate a product-in-use shot, or create a clip from reference footage. Accepts a text prompt, source images, source videos, spokenDialogue, or reference audio. Image and video references can be combined at every quality. References guide generation without guaranteeing exact reproduction. Creates a media file using team credits; use storyboard_to_video for an editable multi-scene ad. Typically takes 1–3 minutes (HIGH/MAX can take longer). Explain that wait and poll get_tool_execution for the output file and downloadUrl.

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.

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.

Read the selected team's usable credit balance and explicitly delegated billing access. Connecting an account alone grants no billing access. This read makes no payment or permission changes.

Read the original order's current payment and credit fulfillment status. Check this before retrying an uncertain purchase. Paid pending fulfillment means payment settled but credits are not yet confirmed. This read never collects money or grants credits.

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

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.

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.

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

Return a project's title, readiness status, editor projectUrl, timestamps, aspectRatio, and assistantId when available. Use the projectId for subsequent remix and export calls.

Return an export snapshot with status, progress, errors, and downloadUrl, exportFileId, thumbnailUrl, and file metadata when ready. Poll until status is succeeded, failed, or cancelled.

Return a tool execution snapshot with status, progress, attemptIndex, error details, and results. Each result includes fileId, file metadata, downloadUrl, and thumbnailUrl when available. Use this to poll a started generation without creating another asset.

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.

Return a workflow run with status, progress, error details, projectId, projectUrl, and downloadUrl when auto-export has finished. Use this to poll an existing run without starting another project.

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.

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

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

List files visible to the current API key.

Return supported narration and caption languages as languageCode and English name pairs. Use these codes when selecting workflow output languages.

Return remix actions for a project with action ids, types, status, progress, attempts, and error details, plus pagination metadata. Poll after remix_project to determine when edits are ready for export.

Browse projects in the authenticated team, including dashboard-created projects, most recently updated first. Returns project ids, titles, status, editor URLs, timestamps, and aspect ratios with a pagination cursor.

List past tool executions, most recent first.

Return a page of narration voices with voiceId, display name, language, accent, description, deprecation status, and supportsDirectToolExecution. Use a voice with supportsDirectToolExecution true for text_to_speech; nextCursor fetches more voices.

Return a page of workflow runs, most recent first, with run and project ids, status, progress, errors, and export URLs when available, plus nextCursor for pagination.

Open the complete VideoGen app inside ChatGPT. Use its existing navigation, assistants, editable examples, media library and editor. Opening the app does not generate media or spend credits.

Open an in-chat file uploader (ChatGPT only). The user picks a file, it is uploaded to VideoGen, and its file id (vg_file_...) is reported back for use in voiceover_to_video, slideshow_to_video, logos, or B-roll. Prefer this over asking the user to paste a link. On clients without in-chat UI, use upload_file (small files) or create_file_upload (large files) instead. Returns the uploader launch status; the file id arrives after the user completes the upload.

Use for text to video when the user wants one short AI-generated shot in a new editable project, such as a product teaser or background clip. Use storyboard_to_video for a sequence of planned shots, or generate_video_clip for a standalone media file without a project. Creates a new project and uses team credits. Returns workflowRunId, projectId, and projectUrl; poll get_workflow_run for status and downloadUrl after auto-export.

Use for AI video editing of an existing VideoGen project: apply caption, transition, or camera-motion edits, or animate its still images. The original project is edited in place unless saveAsNewProject is true; use that flag when the user wants a separate version. CONVERT_IMAGES_TO_VIDEOS generates clips from every still and uses substantial team credits. ZOOM adds camera motion at lower cost. Use only actions in the input schema; this is not arbitrary timeline editing. Poll list_project_remix_actions until edits finish, then export_project for a fresh MP4.

Soft-archive a reference attachment on a team entity without deleting the source file. If it was the default reference, another reference is promoted when available. Returns the entity with its remaining references. Retrying a removed attachment can fail because it is no longer active. Built-in entities cannot have references removed.

Create a new image with the background removed. The source file is left unchanged. Returns toolExecutionId; get_tool_execution provides status and results with the output image fileId and downloadUrl.

Create a new video with the background removed. The source file is left unchanged. Returns toolExecutionId; get_tool_execution provides status and results with the output video fileId and downloadUrl.

Sensitive write: submit a support-reviewed refund request for this paid order. Obtain approval for the request. Requested does not mean approved, refunded or credits reversed. This operation never automatically issues a refund.

Use for script to video: turn a verbatim narration script into an editable video with AI visuals and captions. Fits narrated product demos, marketing explainers, training, and lessons, especially around a minute or longer. Prefer storyboard_to_video for short product ads requiring control over each shot. For avatar narration, pass actorEntityId and optionally avatarQuality. Creates a new project and uses team credits. Returns workflowRunId, projectId, and projectUrl; poll get_workflow_run for progress and downloadUrl after auto-export.

Use when an existing PDF or slide deck should become an editable narrated video, such as a product overview, sales presentation, or training lesson. Upload the file first and pass its fileId; this converts supplied slides rather than creating a slide deck. For avatar narration, pass actorEntityId and optionally avatarQuality. Creates a new project and uses team credits. Returns workflowRunId, projectId, and projectUrl; poll get_workflow_run for progress and downloadUrl after auto-export.

Use for AI video ads, UGC-style product ads, ecommerce product videos, consumer-app launches, or cinematic scenes that need control over each shot. Turn an ordered storyboard into a new editable video project. For product photos, actors, or visual styles, pass productEntityIds, actorEntityIds, or visualStyleEntityId on every scene needing those references (create_entity and add_entity_reference first). Prompt text alone does not attach images; references guide generation without guaranteeing exact reproduction. Uses more team credits than script_to_video: use at most 3 scenes unless the user explicitly requests more. Prefer script_to_video for longer narrated explainers. If no workflow has been selected, explain the tradeoffs and ask before starting. Poll get_workflow_run for progress and downloadUrl after auto-export.

Synthesize spoken audio from text using a catalog voice that supportsDirectToolExecution. Returns toolExecutionId on hosted clients; poll get_tool_execution for status and results containing the audio fileId, downloadUrl, and file metadata. Local calls wait for a status snapshot.

Overwrite supplied display name, description, or complete brandConfig fields on an existing team entity. Omitted fields stay unchanged. Returns the updated entity. Built-in entities cannot be updated.

Upload a small file (image, logo, or short audio) to VideoGen by passing its base64-encoded contents, 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. For large files, use create_file_upload instead.

Create a higher-resolution copy of an existing image for sharper presentation. Returns toolExecutionId; get_tool_execution provides status and the output image file. The source file is unchanged.

Create a higher-resolution copy of an existing video. Returns toolExecutionId; get_tool_execution provides status and the output video file. The source file is unchanged.

Create an SVG vector version of an existing raster image. Returns toolExecutionId; get_tool_execution provides status and results with the SVG fileId and downloadUrl.

Use when the user wants to restyle existing footage from a text prompt while keeping its length and timing. Creates an editable project and uses team credits. Pass videoFileId from an upload or a public videoUrl, which the run imports itself. Restyles up to 120 seconds per run. For captions, transitions, or other supported edits to an existing VideoGen project, use remix_project instead. This changes the footage's visual treatment; it does not publish or manage an ad campaign.

Use when the user already has a recorded voiceover and wants a finished video around that audio. Build an editable video with AI visuals and captions from the uploaded audio file. Fits recorded product pitches, explainers, and training narration. Use script_to_video when the source is written narration rather than audio. Creates a new project and uses team credits. Poll get_workflow_run for progress and downloadUrl after auto-export.