Script to video
script_to_videoUse 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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"script": "<script>"
},
"name": "script_to_video"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | Visual style for generated images: a full, strict paragraph describing medium, texture, palette, and composition. Copy a full app default from get_workflows_guidance, or describe a custom look. Omit for the Realistic default. Image models can add extra objects, text, charts, diagrams, tables, and labels. To keep the picture simple, include this composition lock verbatim: A clear uncluttered subject centered in the frame, occupying only the middle half of the image, with generous empty margins on all four sides, no background clutter. No on-image text, letters, labels, captions, charts, diagrams, tables, legends, or infographic layout unless the user explicitly asked for one specific word or number on screen. | |
| script | Yes | Narration script, spoken verbatim. | |
| quality | No | Generation quality. Omit to use workspace settings. | |
| voiceId | No | Catalog display name (e.g. Matilda) or voice id from list_tts_voices. | |
| language | No | Output language as a BCP-47 code, such as en, es, or fr. | |
| autoExport | No | When true (the default), the run stays in progress until an MP4 is ready. Use downloadUrl from the result. Set false only if you will call remix_project and then export_project yourself. | |
| aspectRatio | No | Output aspect ratio as width:height units (not pixels). Example: { width: 16, height: 9 }. | |
| actorEntityId | No | Id of an ACTOR entity (vg_enti_...) with an image reference. When set, narration is delivered by that actor avatar. | |
| avatarQuality | No | Avatar generation quality tier. Applies when actorEntityId is provided. Omit to use workspace settings. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Error details when status is failed; otherwise null. | |
| status | No | Job status: pending, running, succeeded, failed, or cancelled. | |
| exportId | No | Export id when autoExport succeeded (vg_expo_...). | |
| projectId | Yes | Project created for this exact workflow attempt (vg_proj_...). A retry creates a different project. | |
| projectUrl | Yes | Deep link to the project created for this exact workflow attempt. Keep it paired with workflowRunId; a retry returns a new URL. | |
| downloadUrl | No | Signed MP4 download URL when autoExport succeeded. Give this to the user. | |
| attemptIndex | No | Current or latest attempt index. | |
| exportFileId | No | File id of the rendered MP4 when autoExport succeeded. | |
| workflowType | No | Workflow type (present after polling). | |
| workflowRunId | Yes | Workflow run id (vg_work_...). Keep it paired with this response's projectId and projectUrl; a retry returns a new tuple. | |
| remixActionIds | No | Remix action ids from the start response (empty when none requested). | |
| progressPercentage | No | Completion progress 0-100 (present after polling). | |
| downloadUrlExpiresAt | No | Unix expiry for downloadUrl. |