{"openapi":"3.1.0","info":{"title":"VideoGen API","version":"1.0.0","description":"Programmatically generate images, videos, voiceovers, sound effects, and avatar clips. All tool runs are asynchronous: `POST /v1/tools/...` returns a `toolExecutionId`; poll `GET /v1/tools/executions/{toolExecutionId}` until `status` is `succeeded`, `failed`, or `cancelled`, or subscribe to webhooks. Workflow runs use `workflowRunId` (`vg_work_...`); poll `GET /v1/workflows/runs/{workflowRunId}`. All IDs are prefixed strings (e.g. `vg_tool_...`, `vg_work_...`, `vg_file_...`). Store them as-is and do not parse them."},"servers":[{"url":"https://api.videogen.io","description":"Production"}],"tags":[{"name":"Workflows","description":"End-to-end async video workflows. Each endpoint starts a workflow run that creates a project and generates a video."},{"name":"Projects","description":"Read project metadata and status."},{"name":"Assistant","description":"Converse with the VideoGen AI assistant inside a project. Start a chat, send messages, and act on the assistant's suggestions (pick a workflow, approve a plan, generate). All calls are asynchronous: POSTing a message returns a `messageId` (e.g. `vg_mesg_...`); poll `GET /v1/assistant-messages/{messageId}` until `status` is `succeeded`, `failed`, or `cancelled`, or subscribe to `assistant_message.*` webhooks."},{"name":"Tools","description":"Generate images, videos, audio, and more. All tool endpoints are asynchronous."},{"name":"Text","description":"Generate text with a general-purpose language model. Synchronous — the response includes the generated text."},{"name":"Files","description":"List and retrieve metadata for generated files."},{"name":"Entities","description":"Reusable actors and visual styles. Attach their reference images to workflows for consistent characters and looks across generations."},{"name":"Resources","description":"Discover available avatar presenters and TTS voices to use in tool requests."},{"name":"Webhooks","description":"Register endpoints to receive `tool_execution.*` and `workflow_run.*` events instead of polling."},{"name":"Account","description":"Look up the account and team behind the API key. Useful as a connection test to confirm a key is valid."},{"name":"Webhook events","description":"Event payloads delivered to your registered webhook endpoints."}],"security":[{"bearerAuth":[]}],"paths":{"/v1/workflows/script-to-video":{"post":{"tags":["Workflows"],"operationId":"scriptToVideo","x-fern-audiences":["rest"],"summary":"Script to video","description":"Creates a project and generates a narrated video from a prompt or script. Returns immediately with a workflow run id; poll or subscribe to webhooks for completion.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScriptToVideoRequest"}}}},"responses":{"202":{"description":"Workflow run accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/add-visuals-narrations-and-captions-to-script":{"post":{"tags":["Workflows"],"operationId":"addVisualsNarrationsAndCaptionsToScript","x-fern-audiences":["internal"],"deprecated":true,"summary":"Script to video (legacy alias)","description":"Legacy alias for `POST /v1/workflows/script-to-video`. Use that endpoint instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScriptToVideoRequest"}}}},"responses":{"202":{"description":"Workflow run accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/voiceover-to-video":{"post":{"tags":["Workflows"],"operationId":"voiceoverToVideo","x-fern-audiences":["rest"],"summary":"Voiceover to video","description":"Creates a project from an uploaded voiceover file and generates a video with matching b-roll. Upload the voiceover via the files API first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceoverToVideoRequest"}}}},"responses":{"202":{"description":"Workflow run accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/add-visuals-and-captions-to-voiceover":{"post":{"tags":["Workflows"],"operationId":"addVisualsAndCaptionsToVoiceover","x-fern-audiences":["internal"],"deprecated":true,"summary":"Voiceover to video (legacy alias)","description":"Legacy alias for `POST /v1/workflows/voiceover-to-video`. Use that endpoint instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceoverToVideoRequest"}}}},"responses":{"202":{"description":"Workflow run accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/slideshow-to-video":{"post":{"tags":["Workflows"],"operationId":"slideshowToVideo","x-fern-audiences":["rest"],"summary":"Slideshow to video","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlideshowToVideoRequest"}}}},"responses":{"202":{"description":"Workflow run accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/add-narration-transitions-and-captions-to-slideshow":{"post":{"tags":["Workflows"],"operationId":"addNarrationTransitionsAndCaptionsToSlideshow","x-fern-audiences":["internal"],"deprecated":true,"summary":"Slideshow to video (legacy alias)","description":"Legacy alias for `POST /v1/workflows/slideshow-to-video`. Use that endpoint instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlideshowToVideoRequest"}}}},"responses":{"202":{"description":"Workflow run accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/storyboard-to-video":{"post":{"tags":["Workflows"],"operationId":"storyboardToVideo","x-fern-audiences":["internal"],"summary":"Storyboard to video","description":"Creates a project from an ordered list of scenes and generates one section per scene. Each scene is generated from its prompt as either a still image or a video clip; the scenes are then assembled into a single video. Returns immediately with a workflow run id; poll or subscribe to webhooks for completion.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoryboardToVideoRequest"}}}},"responses":{"202":{"description":"Workflow run accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/generate-scenes-from-storyboard":{"post":{"tags":["Workflows"],"operationId":"generateScenesFromStoryboard","x-fern-audiences":["internal"],"deprecated":true,"summary":"Storyboard to video (legacy alias)","description":"Legacy alias for `POST /v1/workflows/storyboard-to-video`. Use that endpoint instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoryboardToVideoRequest"}}}},"responses":{"202":{"description":"Workflow run accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/prompt-to-video-clip":{"post":{"tags":["Workflows"],"operationId":"promptToVideoClip","x-fern-audiences":["rest"],"summary":"Prompt to video clip","description":"Creates a project from a text prompt and generates one short AI video clip (up to 15 seconds). VideoGen first generates an opening frame from the prompt (optionally guided by reference images), then animates that frame into a video. Returns immediately with a workflow run id; poll or subscribe to webhooks for completion. For a standalone clip without an editable project, use `POST /v1/tools/generate-video-clip` instead. For longer narrated multi-scene videos, use `POST /v1/workflows/script-to-video`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptToVideoClipRequest"}}}},"responses":{"202":{"description":"Workflow run accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/content-outline-to-video":{"post":{"tags":["Workflows"],"operationId":"contentOutlineToVideo","x-fern-audiences":["internal"],"summary":"Content outline to video","description":"Creates a project from a content outline (a Markdown brief) and generates a full video from it. This experimental, fully-agentic workflow reads the outline, plans the video, and builds it section by section — generating any narration, visuals, and media it needs. Returns immediately with a workflow run id; poll or subscribe to webhooks for completion.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentOutlineToVideoRequest"}}}},"responses":{"202":{"description":"Workflow run accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/runs":{"get":{"tags":["Workflows"],"operationId":"listWorkflowRuns","x-fern-audiences":["rest"],"summary":"List workflow runs","description":"List workflow runs started via the API, most recently created first. Use `selfOnly=true` to restrict results to the calling API key's user; otherwise all runs for the team are returned. Cursor-paginated; see the [Pagination](/pagination) guide.","parameters":[{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"},{"$ref":"#/components/parameters/SelfOnlyQuery"}],"responses":{"200":{"description":"Paginated list of workflow runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRunListResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/runs/{workflowRunId}":{"get":{"tags":["Workflows"],"operationId":"getWorkflowRun","x-fern-audiences":["rest"],"summary":"Get workflow run status","parameters":[{"$ref":"#/components/parameters/WorkflowRunIdPath"}],"responses":{"200":{"description":"Current workflow run state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRun"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/workflows/runs/{workflowRunId}/cancel":{"post":{"tags":["Workflows"],"operationId":"cancelWorkflowRun","x-fern-audiences":["rest"],"summary":"Cancel a workflow run","parameters":[{"$ref":"#/components/parameters/WorkflowRunIdPath"}],"responses":{"202":{"description":"Cancellation request accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects":{"get":{"tags":["Projects"],"operationId":"listProjects","x-fern-audiences":["rest"],"summary":"List projects","description":"Returns projects, most recently updated first. By default only API-created projects are included; pass `includeUiProjects=true` to also include dashboard-created projects. Use `selfOnly=true` to restrict results to the calling API key's user; otherwise all matching projects for the team are returned. Cursor-paginated; see the [Pagination](/pagination) guide.","parameters":[{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"},{"$ref":"#/components/parameters/SelfOnlyQuery"},{"$ref":"#/components/parameters/IncludeUiProjectsQuery"}],"responses":{"200":{"description":"Paginated list of projects.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListProjectsResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{projectId}":{"get":{"tags":["Projects"],"operationId":"getProject","x-fern-audiences":["rest"],"summary":"Get project metadata","description":"Returns a simplified view of a project including its title, aspect ratio, status, and URL.","parameters":[{"$ref":"#/components/parameters/ProjectIdPath"}],"responses":{"200":{"description":"Project metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{projectId}/export":{"post":{"tags":["Projects"],"operationId":"exportProject","x-fern-audiences":["rest"],"summary":"Export a project as MP4","description":"Starts an export of a project to MP4. Returns immediately with an export id; the file becomes available when the export task completes. Exporting requires a paid plan in the app, but the API lets you export for free with a VideoGen watermark and a short 'Made with VideoGen' end screen appended to the video. To export without them, purchase the Production API add-on and set `watermarkMode` and `endScreenMode` to `NONE`.","parameters":[{"$ref":"#/components/parameters/ProjectIdPath"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportProjectRequest"}}}},"responses":{"202":{"description":"Export accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportProjectResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{projectId}/exports":{"get":{"tags":["Projects"],"operationId":"listProjectExports","x-fern-audiences":["rest"],"summary":"List project exports","description":"Returns a project's exports, newest first, as fully hydrated `ProjectExport` objects (status, signed download/thumbnail URLs, and the embedded `file`). Signed URLs are re-signed when within an hour of expiring, so they are always valid long enough to use. Cursor-paginated; see the [Pagination](/pagination) guide.","parameters":[{"$ref":"#/components/parameters/ProjectIdPath"},{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"}],"responses":{"200":{"description":"Project exports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListProjectExportsResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{projectId}/exports/{exportId}":{"get":{"tags":["Projects"],"operationId":"getProjectExport","x-fern-audiences":["rest"],"summary":"Get project export","description":"Returns the current status of a project export started via `POST /v1/projects/{projectId}/export`, and — once `status` is `succeeded` — the signed download/thumbnail URLs and the hydrated export `file`. Poll this endpoint until `status` is `succeeded`, `failed`, or `cancelled`. The signed URLs are private and valid for 24 hours; this endpoint automatically re-signs them when they are within an hour of expiring, so a caller always receives a URL valid long enough to use. Every endpoint that returns hydrated files auto-rehydrates this way — only the file endpoints (`GET /v1/files/{fileId}` and `POST /v1/files/{fileId}/hydrate`) are the explicit, on-demand hydration paths. Use `exportFileId` with `POST /v1/files/{fileId}/hydrate` if you need to re-sign the export file directly later.","parameters":[{"$ref":"#/components/parameters/ProjectIdPath"},{"$ref":"#/components/parameters/ExportIdPath"}],"responses":{"200":{"description":"Export status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectExport"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{projectId}/timeline-interchange":{"post":{"tags":["Projects"],"operationId":"createTimelineInterchange","x-fern-audiences":["rest"],"summary":"Create a timeline interchange","description":"Starts a timeline interchange job that converts a project into an editor interchange document (Final Cut Pro FCPXML, Adobe Premiere Pro XML, OpenTimelineIO, or an SRT caption sidecar). Returns immediately with an interchange job id; the file becomes available when the job completes. Unlike `POST /v1/projects/{projectId}/export` (which renders a flattened MP4), this preserves the project as an editable timeline of separate clips, tracks, and captions so you can keep editing it in a desktop video editor. Choose `mediaDelivery` to control how the document references media: `REMOTE_URLS` produces a single document that links to signed media URLs, while `BUNDLE` produces a zip containing the document plus every referenced media file for durable offline relinking.","parameters":[{"$ref":"#/components/parameters/ProjectIdPath"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTimelineInterchangeRequest"}}}},"responses":{"202":{"description":"Timeline interchange accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTimelineInterchangeResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/timeline-interchange/{interchangeJobId}":{"get":{"tags":["Projects"],"operationId":"getTimelineInterchange","x-fern-audiences":["rest"],"summary":"Get timeline interchange job","description":"Returns the current status of a timeline interchange job started via `POST /v1/projects/{projectId}/timeline-interchange`, and, once `status` is `succeeded`, the signed download URL and the hydrated interchange `file`. Poll this endpoint until `status` is `succeeded`, `failed`, or `cancelled`. The signed URL is private and valid for 24 hours; this endpoint automatically re-signs it when it is within an hour of expiring. Use `interchangeFileId` with `POST /v1/files/{fileId}/hydrate` if you need to re-sign the file directly later.","parameters":[{"$ref":"#/components/parameters/InterchangeJobIdPath"}],"responses":{"200":{"description":"Timeline interchange status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineInterchange"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{projectId}/remix":{"post":{"tags":["Projects"],"operationId":"remixProject","x-fern-audiences":["rest"],"summary":"Apply remix actions to a project","description":"Applies an ordered list of edits (background music, logo overlay, caption visibility/style) to a project. Each action runs asynchronously as its own remix action; the response returns one remix action id per action in order. Set `saveAsNewProject` to apply the edits to a copy and leave the original untouched. Poll `GET /v1/projects/{projectId}/remix-actions` for status.","parameters":[{"$ref":"#/components/parameters/ProjectIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixProjectRequest"}}}},"responses":{"202":{"description":"Remix actions accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixProjectResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{projectId}/remix-actions":{"get":{"tags":["Projects"],"operationId":"listProjectRemixActions","x-fern-audiences":["rest"],"summary":"List remix actions for a project","description":"Returns remix actions applied to a project (via `POST /v1/projects/{projectId}/remix` or as a post-workflow step), most recent first, with each action's status and progress. Cursor-paginated; see the [Pagination](/pagination) guide.","parameters":[{"$ref":"#/components/parameters/ProjectIdPath"},{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"}],"responses":{"200":{"description":"Remix actions for the project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListRemixActionsResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/generate-image":{"post":{"tags":["Tools"],"operationId":"generateImage","x-fern-audiences":["rest"],"summary":"Generate image","description":"Generate an image from a text prompt, optionally guided by one or more reference images. When reference images are provided, the prompt describes the desired transformation. VideoGen automatically routes each request to the most effective state-of-the-art image model for your prompt, reference images, and quality tier, so you don't pick a model.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateImageRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/generate-video-clip":{"post":{"tags":["Tools"],"operationId":"generateVideoClip","x-fern-audiences":["rest"],"summary":"Generate video clip","description":"Generate a single short video clip (up to 15 seconds) from a text prompt, optionally guided by reference images, videos, and audio. At least one of `prompt`, `imageFileIds`, `videoFileIds`, or `audioFileIds` must be provided. VideoGen automatically routes each request to the most effective state-of-the-art video model for your inputs and settings, so you don't pick a model. This endpoint returns one standalone clip. For longer, higher-quality, professionally edited videos with narration, captions, music, and multiple scenes, use a video workflow such as [Script to video](/workflows) (`POST /v1/workflows/script-to-video`) instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateVideoClipRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/generate-motion-graphic":{"post":{"tags":["Tools"],"operationId":"generateMotionGraphic","x-fern-audiences":["rest"],"summary":"Generate motion graphic","description":"Generate an animated motion graphic video from a text prompt. This is an experimental, fully agentic alternative to a video workflow: VideoGen plans the animation, optionally generates or fetches supporting media, and renders a self-contained animated clip. It is especially well suited to precise text animations (e.g. a typing effect, animated captions, kinetic typography, lower thirds) that are hard to express with stock or generated footage. Optionally pass uploaded `fileIds` for reference media the animation may display. This endpoint returns one standalone video. For longer, narrated, multi-scene videos, use a video workflow such as [Script to video](/workflows) (`POST /v1/workflows/script-to-video`) instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateMotionGraphicRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/text-to-speech":{"post":{"tags":["Tools"],"operationId":"textToSpeech","x-fern-audiences":["rest"],"summary":"Text to speech","description":"Convert text into a spoken audio file. Only voices with `supportsDirectToolExecution` set to true can be used. Optionally choose a voice, language, speed, and pronunciation overrides.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TextToSpeechRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/generate-sound-effect":{"post":{"tags":["Tools"],"operationId":"generateSoundEffect","x-fern-audiences":["rest"],"summary":"Generate sound effect","description":"Generate a sound effect from a text description. Optionally control the duration and prompt influence. VideoGen automatically routes each request to the most effective state-of-the-art sound effect model for your prompt and settings, so you don't pick a model.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateSoundEffectRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/generate-music":{"post":{"tags":["Tools"],"operationId":"generateMusic","x-fern-audiences":["rest"],"summary":"Generate music","description":"Generate an instrumental music track from a text description. The returned track is approximately 30 seconds long. VideoGen automatically routes each request to the most effective state-of-the-art music model for your prompt, so you don't pick a model.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateMusicRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/generate-avatar":{"post":{"tags":["Tools"],"operationId":"generateAvatar","x-fern-audiences":["rest"],"summary":"Generate avatar clip","description":"Generate a talking-head avatar video by pairing a presenter with an audio file, typically from a prior text-to-speech result.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateAvatarRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/vectorize-image":{"post":{"tags":["Tools"],"operationId":"vectorizeImage","x-fern-audiences":["rest"],"summary":"Vectorize image","description":"Convert any raster image into a scalable vector graphic (SVG). The output traces the shapes and colors of the input image.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageAssetRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/remove-image-background":{"post":{"tags":["Tools"],"operationId":"removeImageBackground","x-fern-audiences":["rest"],"summary":"Remove background from an image","description":"Remove the background from an image, returning a transparent-background PNG of the foreground subject.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageAssetRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/remove-video-background":{"post":{"tags":["Tools"],"operationId":"removeVideoBackground","x-fern-audiences":["rest"],"summary":"Remove background from a video","description":"Remove the background from a video, producing a transparent-background video of the foreground subject.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoAssetRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/upscale-image":{"post":{"tags":["Tools"],"operationId":"upscaleImage","x-fern-audiences":["rest"],"summary":"Upscale an image","description":"Increase the resolution of an image while preserving detail and sharpness.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageAssetRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/upscale-video":{"post":{"tags":["Tools"],"operationId":"upscaleVideo","x-fern-audiences":["rest"],"summary":"Upscale a video","description":"Increase the resolution of a video while preserving detail and sharpness.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoAssetRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/image-3d-effect":{"post":{"tags":["Tools"],"operationId":"image3dEffect","x-fern-audiences":["rest"],"summary":"Add 3D motion to an image","description":"Turn a still image into a short video clip with a 3D parallax motion effect, simulating camera movement through the scene.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageAssetRequest"}}}},"responses":{"202":{"description":"Execution accepted; poll until complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/executions/{toolExecutionId}/cancel":{"post":{"tags":["Tools"],"operationId":"cancelToolExecution","x-fern-audiences":["rest"],"summary":"Cancel tool execution","description":"Request cancellation of a running tool execution. The execution transitions to `cancelled` if it has not already completed.","parameters":[{"$ref":"#/components/parameters/ToolExecutionIdPath"}],"responses":{"202":{"description":"Cancellation request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartToolExecutionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/executions":{"get":{"tags":["Tools"],"operationId":"listToolExecutions","x-fern-audiences":["rest"],"summary":"List tool executions","description":"List tool executions started via the API, most recently created first. Use `selfOnly=true` to restrict results to the calling API key's user; otherwise all executions for the team are returned. Cursor-paginated; see the [Pagination](/pagination) guide. Executions remain listable indefinitely (including those older than 24 hours). For efficiency this list does not re-sign result download URLs, so `downloadUrl`/`thumbnailUrl` reflect the last time they were signed and may be expired (always check `downloadUrlExpiresAt`). To obtain a fresh signed URL, GET the individual execution (`GET /v1/tools/executions/{toolExecutionId}`) or hydrate the file (`GET /v1/files/{fileId}` / `POST /v1/files/{fileId}/hydrate`).","parameters":[{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"},{"$ref":"#/components/parameters/SelfOnlyQuery"}],"responses":{"200":{"description":"Paginated list of tool executions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolExecutionListResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tools/executions/{toolExecutionId}":{"get":{"tags":["Tools"],"operationId":"getToolExecutionInfo","x-fern-audiences":["rest"],"summary":"Get tool execution info","description":"Retrieve the current status and result of a tool execution. Poll this endpoint until `status` is `succeeded`, `failed`, or `cancelled`. Each succeeded result carries signed `downloadUrl`/`thumbnailUrl` (with matching `*ExpiresAt` timestamps) alongside the full hydrated `file`. The signed URLs are private and valid for 24 hours; this single-execution endpoint automatically re-signs them when they are within an hour of expiring, so a caller always receives a URL valid long enough to use. Results remain retrievable indefinitely, including executions older than 24 hours. Note that list endpoints (e.g. `GET /v1/tools/executions`) do not re-sign URLs: they return the last-signed URL, which may already be expired (check `downloadUrlExpiresAt`). To refresh a URL, GET the individual execution here, or hydrate the file directly via `GET /v1/files/{fileId}` / `POST /v1/files/{fileId}/hydrate`.","parameters":[{"$ref":"#/components/parameters/ToolExecutionIdPath"}],"responses":{"200":{"description":"Current execution state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutedTool"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files":{"get":{"tags":["Files"],"operationId":"getFiles","x-fern-audiences":["rest"],"summary":"List files","description":"List files in your account. By default this returns your standalone files (direct tool-call outputs and uploads) and omits two categories: export files (the raw output files of your exports) and project files (the generative files created within a project, e.g. each AI image and text-to-speech file in a script-to-video workflow output). Set `includeExportFiles` and/or `includeProjectFiles` to true to include them — both require the Production API add-on. Files are returned most recently updated first. Cursor-paginated; see the [Pagination](/pagination) guide.","parameters":[{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"},{"$ref":"#/components/parameters/IncludeExportFilesQuery"},{"$ref":"#/components/parameters/IncludeProjectFilesQuery"}],"responses":{"200":{"description":"File list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetFilesResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/search":{"post":{"tags":["Files"],"operationId":"searchFiles","x-fern-audiences":["rest"],"summary":"Search files","description":"Semantic vector search over your files. Embeds the query text and returns the closest matching files ranked by cosine similarity. Only files with indexed descriptions are searchable.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchFilesRequest"}}}},"responses":{"200":{"description":"Search results ordered by descending similarity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchFilesResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/{fileId}":{"get":{"tags":["Files"],"operationId":"getFile","x-fern-audiences":["rest"],"summary":"Get file","description":"Retrieve metadata for a single file by its id.","parameters":[{"$ref":"#/components/parameters/FileIdPath"}],"responses":{"200":{"description":"File metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileInfo"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/upload":{"post":{"tags":["Files"],"operationId":"createFileUpload","x-fern-audiences":["rest"],"summary":"Create file upload","description":"Create a new file and receive a pre-signed upload URL. PUT the file bytes to the returned URL, then poll `GET /v1/files/{fileId}` until the file is ready.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileUploadRequest"}}}},"responses":{"200":{"description":"Upload instructions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/{fileId}/hydrate":{"post":{"tags":["Files"],"operationId":"hydrateFile","x-fern-audiences":["rest"],"summary":"Hydrate file","description":"Generate fresh signed URLs for all available renditions of a file. Call this when source URLs are missing or expired. Returns the full file object with populated `downloadSource`, `thumbnailSource`, and `previewSource` (and the convenience root-level `downloadUrl` / `thumbnailUrl`).","parameters":[{"$ref":"#/components/parameters/FileIdPath"}],"responses":{"200":{"description":"File with hydrated sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileInfo"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/{fileId}/archive":{"post":{"tags":["Files"],"operationId":"archiveFile","x-fern-audiences":["rest"],"summary":"Archive file","description":"Archive a file by setting its archived timestamp. Archived files are excluded from list results. Returns the updated file object.","parameters":[{"$ref":"#/components/parameters/FileIdPath"}],"responses":{"200":{"description":"Archived file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileInfo"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/{fileId}/enable-public-preview":{"post":{"tags":["Files"],"operationId":"enablePublicPreview","x-fern-audiences":["rest"],"summary":"Enable public preview","description":"Enable public preview for a file. Works for any file type. Copies the file to a permanent public URL (`staticPublicPreviewSource`) and, for video and audio, registers a public embed playback id (`publicPlaybackId`) for use with `@videogen/player`. If streaming playback is still processing, the endpoint polls briefly and background processing finishes creating the embed playback id. Returns the updated file.","parameters":[{"$ref":"#/components/parameters/FileIdPath"}],"responses":{"200":{"description":"File with public preview enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileInfo"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/{fileId}/disable-public-preview":{"post":{"tags":["Files"],"operationId":"disablePublicPreview","x-fern-audiences":["rest"],"summary":"Disable public preview","description":"Disable public preview for a file. Removes the permanent public URL copy and revokes unauthenticated embed streaming access. Authenticated signed URLs remain functional. Returns the updated file.","parameters":[{"$ref":"#/components/parameters/FileIdPath"}],"responses":{"200":{"description":"File with public preview disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileInfo"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities":{"get":{"tags":["Entities"],"operationId":"listEntities","x-fern-audiences":["rest"],"summary":"List entities","description":"List the actors and visual styles available to your team, most recently updated first. Cursor-paginated; see the [Pagination](/pagination) guide.","parameters":[{"$ref":"#/components/parameters/EntityTypeQuery"},{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"}],"responses":{"200":{"description":"Entity list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEntitiesResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Entities"],"operationId":"createEntity","x-fern-audiences":["rest"],"summary":"Create entity","description":"Create a new actor or visual style. Attach reference images with `POST /v1/entities/{entityId}/references`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEntityRequest"}}}},"responses":{"200":{"description":"The created entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{entityId}":{"get":{"tags":["Entities"],"operationId":"getEntity","x-fern-audiences":["rest"],"summary":"Get entity","description":"Retrieve a single entity by its id, including its reference images.","parameters":[{"$ref":"#/components/parameters/EntityIdPath"}],"responses":{"200":{"description":"Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{entityId}/update":{"post":{"tags":["Entities"],"operationId":"updateEntity","x-fern-audiences":["rest"],"summary":"Update entity","description":"Update an entity's name or description. Provide at least one field.","parameters":[{"$ref":"#/components/parameters/EntityIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEntityRequest"}}}},"responses":{"200":{"description":"The updated entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{entityId}/archive":{"post":{"tags":["Entities"],"operationId":"archiveEntity","x-fern-audiences":["rest"],"summary":"Archive entity","description":"Archive an entity. Archived entities no longer appear in `GET /v1/entities` and can't be attached to new workflows.","parameters":[{"$ref":"#/components/parameters/EntityIdPath"}],"responses":{"200":{"description":"Archive acknowledged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityArchiveResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{entityId}/references":{"post":{"tags":["Entities"],"operationId":"addEntityReference","x-fern-audiences":["rest"],"summary":"Add entity reference","description":"Attach an image file as a reference for the entity. Upload the image first via `POST /v1/files/upload`. Returns the updated entity.","parameters":[{"$ref":"#/components/parameters/EntityIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddEntityReferenceRequest"}}}},"responses":{"200":{"description":"The updated entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{entityId}/references/remove":{"post":{"tags":["Entities"],"operationId":"removeEntityReference","x-fern-audiences":["rest"],"summary":"Remove entity reference","description":"Detach a reference image from the entity. Returns the updated entity.","parameters":[{"$ref":"#/components/parameters/EntityIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveEntityReferenceRequest"}}}},"responses":{"200":{"description":"The updated entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/assistants":{"post":{"tags":["Assistant"],"operationId":"startAssistantChat","x-fern-audiences":["rest"],"summary":"Start an assistant chat","description":"Creates a new project and sends the first message to the VideoGen AI assistant, exactly like typing into the assistant on a new project in the app. Asynchronous: the response contains the `messageId` of the assistant's pending reply (e.g. `vg_mesg_...`). Poll `GET /v1/assistant-messages/{messageId}` until `status` is `succeeded`, `failed`, or `cancelled`, or subscribe to `assistant_message.*` webhooks. Fetch the parent assistant with `GET /v1/assistants/{assistantId}` to list all messages in the chat.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartAssistantChatRequest"}}}},"responses":{"202":{"description":"Assistant message accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartAssistantChatResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/assistants/{assistantId}":{"get":{"tags":["Assistant"],"operationId":"getAssistant","x-fern-audiences":["rest"],"summary":"Get an assistant chat","description":"Returns the assistant chat identified by `assistantId`, including every message in it (user and assistant turns) in chronological order.","parameters":[{"$ref":"#/components/parameters/AssistantIdPath"}],"responses":{"200":{"description":"The assistant chat and its messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAssistantResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/assistants/{assistantId}/messages":{"post":{"tags":["Assistant"],"operationId":"sendAssistantMessage","x-fern-audiences":["rest"],"summary":"Send an assistant message","description":"Sends a follow-up message to an existing assistant chat started with `POST /v1/assistants`. Asynchronous: the response contains the `messageId` of the assistant's pending reply. Poll `GET /v1/assistant-messages/{messageId}` until `status` is terminal, or subscribe to `assistant_message.*` webhooks.","parameters":[{"$ref":"#/components/parameters/AssistantIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAssistantMessageRequest"}}}},"responses":{"202":{"description":"Assistant message accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAssistantMessageResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/assistants/{assistantId}/actions/{actionId}":{"post":{"tags":["Assistant"],"operationId":"actOnAssistantAction","x-fern-audiences":["rest"],"summary":"Act on an assistant action","description":"Acts on an actionable widget the assistant offered on a prior turn. Reference the action by its `actionId` from a prior assistant message. `APPROVE` (the default) completes the action; `REJECT` records the rejection. Two kinds are actionable via the API: accepting a workflow suggestion (`APPROVE` applies the suggested workflow and immediately starts generating; the returned assistant message carries the workflow run in `generation`), and applying an assistant edit (an `APPLY_EDIT` action with `requiresApp` false, which applies the edit to the project). Actions with `requiresApp` set to true (plans, tools, and other app-only widgets) can only be completed in the web app: open the assistant's `projectUrl` instead. Asynchronous: the response contains the `messageId` of the resulting assistant message. Poll `GET /v1/assistant-messages/{messageId}` for its terminal state.","parameters":[{"$ref":"#/components/parameters/AssistantIdPath"},{"name":"actionId","in":"path","required":true,"schema":{"type":"string"},"description":"The `actionId` of the action to act on, from a prior assistant message."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActOnAssistantActionRequest"}}}},"responses":{"202":{"description":"Assistant action accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActOnAssistantActionResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/assistant-messages/{messageId}":{"get":{"tags":["Assistant"],"operationId":"getAssistantMessage","x-fern-audiences":["rest"],"summary":"Get an assistant message","description":"Returns a single assistant chat message by id. Poll after a POST that returned `messageId` until `status` is `succeeded`, `failed`, or `cancelled`. Also supported for `USER` messages (which reach terminal state as soon as they're accepted).","parameters":[{"$ref":"#/components/parameters/MessageIdPath"}],"responses":{"200":{"description":"The assistant chat message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantMessage"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/text/generate":{"post":{"tags":["Text"],"operationId":"generateText","x-fern-audiences":["rest"],"summary":"Generate text","description":"Generate text from a prompt using a general-purpose language model. Choose a quality tier with `quality` (`LOW`, `STANDARD`, `HIGH`, or `MAX`). Synchronous: the response includes the generated text. Useful for drafting scripts, titles, descriptions, and other short copy before generating a video.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateTextRequest"}}}},"responses":{"200":{"description":"Generated text.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateTextResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/resources/avatar-presenters":{"get":{"tags":["Resources"],"operationId":"listAvatarPresenters","x-fern-audiences":["rest"],"summary":"List avatar presenters","description":"List available avatar presenters. Pass an `avatarPresenterId` from the response to the avatar video endpoint or to a script/slideshow workflow. Pass a reference `voiceId` to return presenters sorted by best match for that voice. Cursor-paginated; see the [Pagination](/pagination) guide.","parameters":[{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"},{"$ref":"#/components/parameters/AvatarPresenterReferenceVoiceIdQuery"}],"responses":{"200":{"description":"List of avatar presenters. Pass an `avatarPresenterId` to `POST /v1/tools/generate-avatar`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarPresenterListResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/resources/tts-voices":{"get":{"tags":["Resources"],"operationId":"listTtsVoices","x-fern-audiences":["rest"],"summary":"List TTS voices","description":"List available text-to-speech voices. Pass a `voiceId` from the response to the text-to-speech endpoint. Cursor-paginated; see the [Pagination](/pagination) guide.","parameters":[{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"},{"$ref":"#/components/parameters/IncludeDeprecatedVoicesQuery"}],"responses":{"200":{"description":"List of TTS voices. Pass a `voiceId` to `POST /v1/tools/text-to-speech`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsVoiceListResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/resources/languages":{"get":{"tags":["Resources"],"operationId":"listLanguages","x-fern-audiences":["rest"],"summary":"List supported languages","description":"List the languages a project can be translated into. Pass a `languageCode` from the response to the `TRANSLATE_PROJECT` remix action. Returns the full catalogue in a single response (not paginated).","responses":{"200":{"description":"List of supported languages. Pass a `languageCode` to a `TRANSLATE_PROJECT` remix action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LanguageListResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/webhooks/endpoints":{"get":{"tags":["Webhooks"],"operationId":"listWebhookEndpoints","x-fern-audiences":["rest"],"summary":"List webhooks","description":"List configured webhook endpoints for your account. Cursor-paginated; see the [Pagination](/pagination) guide.","parameters":[{"$ref":"#/components/parameters/PaginationLimit"},{"$ref":"#/components/parameters/PaginationCursor"}],"responses":{"200":{"description":"Configured endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointListResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Webhooks"],"operationId":"createWebhookEndpoint","x-fern-audiences":["rest"],"summary":"Create webhook","description":"Register a new webhook endpoint to receive `tool_execution.*`, `workflow_run.*`, and `file.*` events. The signing secret is only returned in this response. Store it securely.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointRequest"}}}},"responses":{"201":{"description":"Created; `signingSecret` is only returned in this response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/webhooks/endpoints/{endpointId}":{"delete":{"tags":["Webhooks"],"operationId":"deleteWebhookEndpoint","x-fern-audiences":["rest"],"summary":"Delete webhook","description":"Remove a webhook endpoint. It will stop receiving events immediately.","parameters":[{"$ref":"#/components/parameters/WebhookEndpointIdPath"}],"responses":{"204":{"description":"Removed"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/me":{"get":{"tags":["Account"],"operationId":"getMe","x-fern-audiences":["rest"],"summary":"Get current account","description":"Return the account and team behind the API key making the request. Takes no parameters. Call it as a connection test to confirm a key is valid and to discover the `teamId` and account `email` a key belongs to.","responses":{"200":{"description":"The account and team for the authenticated API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"webhooks":{"tool_execution.succeeded":{"post":{"tags":["Webhook events"],"operationId":"toolExecutionSucceeded","x-fern-audiences":["webhook-events"],"summary":"tool_execution.succeeded","description":"Delivered when a tool execution completes successfully.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolExecutionWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"tool_execution.failed":{"post":{"tags":["Webhook events"],"operationId":"toolExecutionFailed","x-fern-audiences":["webhook-events"],"summary":"tool_execution.failed","description":"Delivered when a tool execution fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolExecutionWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"tool_execution.cancelled":{"post":{"tags":["Webhook events"],"operationId":"toolExecutionCancelled","x-fern-audiences":["webhook-events"],"summary":"tool_execution.cancelled","description":"Delivered when a tool execution is cancelled.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolExecutionWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"workflow_run.succeeded":{"post":{"tags":["Webhook events"],"operationId":"workflowRunSucceeded","x-fern-audiences":["webhook-events"],"summary":"workflow_run.succeeded","description":"Delivered when a workflow run completes successfully.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRunWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"workflow_run.failed":{"post":{"tags":["Webhook events"],"operationId":"workflowRunFailed","x-fern-audiences":["webhook-events"],"summary":"workflow_run.failed","description":"Delivered when a workflow run fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRunWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"workflow_run.cancelled":{"post":{"tags":["Webhook events"],"operationId":"workflowRunCancelled","x-fern-audiences":["webhook-events"],"summary":"workflow_run.cancelled","description":"Delivered when a workflow run is cancelled.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRunWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"file.upload.completed":{"post":{"tags":["Webhook events"],"operationId":"fileUploadCompleted","x-fern-audiences":["webhook-events"],"summary":"file.upload.completed","description":"Delivered when a file upload finishes and the file is stored. Only fired for files uploaded via the API.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"file.upload.failed":{"post":{"tags":["Webhook events"],"operationId":"fileUploadFailed","x-fern-audiences":["webhook-events"],"summary":"file.upload.failed","description":"Delivered when a file upload fails. Only fired for files uploaded via the API.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"file.playback_ready":{"post":{"tags":["Webhook events"],"operationId":"filePlaybackReady","x-fern-audiences":["webhook-events"],"summary":"file.playback_ready","description":"Delivered when a file is ready for streaming playback. Only fired for files uploaded via the API.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"file.download_ready":{"post":{"tags":["Webhook events"],"operationId":"fileDownloadReady","x-fern-audiences":["webhook-events"],"summary":"file.download_ready","description":"Delivered when a file is ready for download. Only fired for files uploaded via the API.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"file.analysis_completed":{"post":{"tags":["Webhook events"],"operationId":"fileAnalysisCompleted","x-fern-audiences":["webhook-events"],"summary":"file.analysis_completed","description":"Delivered when file analysis (description, transcript, embedding) completes. Only fired for files uploaded via the API.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"file.analysis_failed":{"post":{"tags":["Webhook events"],"operationId":"fileAnalysisFailed","x-fern-audiences":["webhook-events"],"summary":"file.analysis_failed","description":"Delivered when file analysis fails. Only fired for files uploaded via the API.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"assistant_message.succeeded":{"post":{"tags":["Webhook events"],"operationId":"assistantMessageSucceeded","x-fern-audiences":["webhook-events"],"summary":"assistant_message.succeeded","description":"Delivered when an assistant message completes successfully.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantMessageWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"assistant_message.failed":{"post":{"tags":["Webhook events"],"operationId":"assistantMessageFailed","x-fern-audiences":["webhook-events"],"summary":"assistant_message.failed","description":"Delivered when an assistant message fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantMessageWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}},"assistant_message.cancelled":{"post":{"tags":["Webhook events"],"operationId":"assistantMessageCancelled","x-fern-audiences":["webhook-events"],"summary":"assistant_message.cancelled","description":"Delivered when an assistant message is cancelled.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantMessageWebhookPayload"}}}},"responses":{"200":{"description":"Acknowledge receipt"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"API key from [app.videogen.io/developers](https://app.videogen.io/developers). The full key is only shown once when you create it."}},"parameters":{"PaginationLimit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum number of items to return in the page. Defaults to 50; capped at 200. See [Pagination](/pagination)."},"PaginationCursor":{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor returned as `nextCursor` by the previous page. Omit on the first request. Cursors are tied to the endpoint that produced them and must be passed unmodified. See [Pagination](/pagination)."},"SelfOnlyQuery":{"name":"selfOnly","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, returns only items created by the API key's owner. When false (default), returns all items accessible to the team."},"IncludeUiProjectsQuery":{"name":"includeUiProjects","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, includes dashboard-created projects in addition to API-created projects. When false (default), returns only API-created projects."},"IncludeExportFilesQuery":{"name":"includeExportFiles","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, includes export files — the raw output files of your exports (the rendered MP4 you download from an export). When false (default), they are omitted. Requires the Production API add-on; returns an error if you set it to true without it."},"IncludeProjectFilesQuery":{"name":"includeProjectFiles","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, includes project files — the generative files created within a project (e.g. each AI image and text-to-speech file produced inside a script-to-video workflow output). When false (default), they are omitted. Requires the Production API add-on; returns an error if you set it to true without it."},"IncludeDeprecatedVoicesQuery":{"name":"includeDeprecatedVoices","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true, includes voices that are deprecated but still callable. Defaults to false."},"AvatarPresenterReferenceVoiceIdQuery":{"name":"voiceId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional reference voice id from `GET /v1/resources/tts-voices` (e.g. `vg_voic_...`). When provided, avatar presenters are returned sorted by best match for that voice (best first). Omit to return presenters in the default catalogue order."},"ProjectIdPath":{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"The project id (e.g. `vg_proj_...`)."},"AssistantIdPath":{"name":"assistantId","in":"path","required":true,"schema":{"type":"string"},"description":"The assistant chat id (e.g. `vg_asst_...`). Every API project has one assistant chat; find it on `ProjectResponse.assistantId`."},"MessageIdPath":{"name":"messageId","in":"path","required":true,"schema":{"type":"string"},"description":"The assistant message id (e.g. `vg_mesg_...`) returned by an assistant POST."},"ExportIdPath":{"name":"exportId","in":"path","required":true,"schema":{"type":"string"},"description":"The export id (e.g. `vg_expo_...`) returned by `POST /v1/projects/{projectId}/export`."},"InterchangeJobIdPath":{"name":"interchangeJobId","in":"path","required":true,"schema":{"type":"string"},"description":"The timeline interchange job id (e.g. `vg_inte_...`) returned by `POST /v1/projects/{projectId}/timeline-interchange`."},"FileIdPath":{"name":"fileId","in":"path","required":true,"schema":{"type":"string"},"description":"The file id (e.g. `vg_file_...`)."},"EntityIdPath":{"name":"entityId","in":"path","required":true,"schema":{"type":"string"},"description":"The entity id (e.g. `vg_enti_...`)."},"EntityTypeQuery":{"name":"entityType","in":"query","required":false,"schema":{"type":"string","enum":["ACTOR","PRODUCT","VISUAL_STYLE"]},"description":"When provided, returns only entities of this type. Omit to return all entities."},"WorkflowRunIdPath":{"name":"workflowRunId","in":"path","required":true,"schema":{"type":"string"},"description":"The workflow run id returned when the workflow was started."},"ToolExecutionIdPath":{"name":"toolExecutionId","in":"path","required":true,"schema":{"type":"string"},"description":"The tool execution id returned when the tool was started."},"WebhookEndpointIdPath":{"name":"endpointId","in":"path","required":true,"schema":{"type":"string"},"description":"The webhook endpoint id (e.g. `ep_...`) returned by `POST /v1/webhooks/endpoints`."}},"schemas":{"FileType":{"type":"string","enum":["IMAGE","VIDEO","AUDIO","PDF","SLIDESHOW","TEXT","LOTTIE"],"description":"File type. `TEXT` covers plain-text and editor-interchange documents; `LOTTIE` is a JSON animation."},"FileInfo":{"type":"object","description":"Metadata for a generated file. Obtain ids from tool results or `GET /v1/files`.","required":["fileId","scope"],"properties":{"fileId":{"type":"string","description":"File id (e.g. `vg_file_...`)."},"type":{"description":"File type. Null when the file is still being processed and the type has not yet been determined.","anyOf":[{"$ref":"#/components/schemas/FileType"},{"type":"null"}]},"scope":{"type":"string","enum":["GLOBAL","PROJECT","EXPORT","TEMPORARY","ENTITY"],"description":"File scope.\n\n- `GLOBAL`: user-uploaded or standalone generated files that persist indefinitely.\n- `PROJECT`: project-specific files (e.g. text-to-speech clips in a generated project).\n- `EXPORT`: project exports.\n- `TEMPORARY`: short-lived files guaranteed to be available for 24 hours, after which they may be archived at any time. Not analyzed (no description, transcript, or embedding).\n- `ENTITY`: files attached to a reusable entity (e.g. a voice sample for an actor), shared across your team.\n"},"displayName":{"type":"string","description":"Display name for the file."},"description":{"type":["string","null"]},"durationSeconds":{"type":["number","null"],"description":"Duration in seconds for video and audio files. Null for images."},"transcript":{"description":"Timed transcript for video and audio files, when available, as a `Transcript` object with timed `words`. Null for images or when no transcript has been generated. For plain transcript text, use `transcriptText`.","anyOf":[{"$ref":"#/components/schemas/Transcript"},{"type":"null"}]},"transcriptText":{"type":["string","null"],"description":"Plain transcript text for video and audio files, when available. Null for images or when no transcript has been generated."},"downloadUrl":{"type":["string","null"],"format":"uri","description":"Private signed URL for the highest-quality downloadable rendition, provided at the top level for convenience. Valid for 24 hours from when it was signed. `null` when the rendition is still processing or the URL has not been signed yet. See `downloadUrlExpiresAt` for the exact expiry and `downloadSource` for the full rendition metadata; call `POST /v1/files/{fileId}/hydrate` to refresh it."},"downloadUrlExpiresAt":{"type":["integer","null"],"description":"Seconds since epoch (Unix timestamp) when `downloadUrl` expires. `null` when `downloadUrl` is null."},"thumbnailUrl":{"type":["string","null"],"format":"uri","description":"Private signed URL for the thumbnail rendition, provided at the top level for convenience. Valid for 24 hours from when it was signed. `null` for file types that have no thumbnail (e.g. audio) or when it has not been signed yet. See `thumbnailSource` for the full rendition metadata."},"thumbnailUrlExpiresAt":{"type":["integer","null"],"description":"Seconds since epoch (Unix timestamp) when `thumbnailUrl` expires. `null` when `thumbnailUrl` is null."},"thumbnailSource":{"description":"Thumbnail image source. Populated after hydration.","anyOf":[{"$ref":"#/components/schemas/FileSource"},{"type":"null"}]},"previewSource":{"description":"Preview rendition source (720p for video, resized for images). Populated after hydration.","anyOf":[{"$ref":"#/components/schemas/FileSource"},{"type":"null"}]},"downloadSource":{"description":"Highest-quality downloadable rendition. Populated after hydration.","anyOf":[{"$ref":"#/components/schemas/FileSource"},{"type":"null"}]},"hlsSource":{"description":"Private HLS streaming source. Populated for video and audio files once streaming renditions are ready. Uses a signed token; treat like other signed sources.","anyOf":[{"$ref":"#/components/schemas/FileSource"},{"type":"null"}]},"isPublicPreviewEnabled":{"type":"boolean","description":"Whether public preview is enabled for this file. When true, `staticPublicPreviewSource` is populated for all file types. For video and audio, `publicHlsUrl` and `publicPlaybackId` are also populated once embed streaming is ready."},"staticPublicPreviewSource":{"description":"Permanent public URL for the file's highest-quality rendition. Populated when `isPublicPreviewEnabled` is true. Does not expire (`expiresAt` is null). Use for direct links to images, downloads, or any file type. For embedded video or audio players, prefer `publicPlaybackId`.","anyOf":[{"$ref":"#/components/schemas/FileSource"},{"type":"null"}]},"publicHlsUrl":{"type":["string","null"],"description":"Public HLS streaming URL for video and audio. Only present when `isPublicPreviewEnabled` is true and embed streaming is ready. Prefer `publicPlaybackId` with `@videogen/player` for embeds."},"publicPlaybackId":{"type":["string","null"],"description":"Encoded public playback id (e.g. `vg_play_...`) for video and audio embeds. Pass this to `@videogen/player` or `@videogen/player-react`. Only present when `isPublicPreviewEnabled` is true and embed streaming is ready. For a permanent direct file URL (any type), use `staticPublicPreviewSource` instead."},"sourceToolType":{"type":"string","description":"Tool type that generated this file (e.g. `GENERATE_IMAGE`, `TEXT_TO_SPEECH`). Only present when the file was created by a tool execution."},"sourceToolExecutionId":{"type":"string","description":"Execution id of the tool call that generated this file (e.g. `vg_tool_...`). Only present when the file was created by a tool execution."},"fileAnalysisMetadata":{"description":"Background analysis state for the file (used to populate `description`, `transcript`, `durationSeconds`, and the search embedding). Omitted when the file was returned via a path that does not check analysis progress (e.g. tool-result inline files and webhook payloads).","$ref":"#/components/schemas/FileAnalysisMetadata"}}},"FileSource":{"type":"object","description":"A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.","required":["status"],"properties":{"status":{"type":"string","enum":["pending","ready","failed","skipped"],"description":"`pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio)."},"url":{"type":["string","null"],"description":"Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint."},"expiresAt":{"type":["integer","null"],"description":"Seconds since epoch (Unix timestamp) when the signed URL expires."},"width":{"type":["integer","null"],"description":"Rendition width in pixels, when known."},"height":{"type":["integer","null"],"description":"Rendition height in pixels, when known."},"fileBytes":{"type":["integer","null"],"description":"File size in bytes, when known."}}},"FileAnalysisMetadata":{"type":"object","description":"Background analysis state for a file. Background analysis populates `description`, `transcript`, `durationSeconds`, and the search embedding after a file is uploaded or generated; this object lets you render a progress indicator while it runs (and skip rendering once it's done).\n","required":["analysisLoadingState","analysisProgressPercentage"],"properties":{"analysisLoadingState":{"type":"string","enum":["UNATTEMPTED","LOADING","FULFILLED","REJECTED"],"description":"Coarse-grained analysis state.\n\n- `UNATTEMPTED`: analysis has not started yet.\n- `LOADING`: analysis is in progress.\n- `FULFILLED`: analysis completed successfully. `description`, `transcript`, and `durationSeconds` are now populated where applicable for the file's type.\n- `REJECTED`: analysis failed permanently and will not be retried.\n"},"analysisProgressPercentage":{"type":"number","description":"Progress in `[0, 100]`. Always `100` when `analysisLoadingState` is `FULFILLED`. Otherwise the most recent in-flight progress reported by the analysis task (or `0` if no progress has been reported yet)."},"analysisAttemptIndex":{"type":"integer","description":"Zero-based index of the current analysis task attempt. Only present while analysis is still loading (`UNATTEMPTED` or `LOADING`); omitted once analysis reaches a terminal state."}}},"SearchFilesRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Natural-language search query. The text is embedded and compared against file description vectors using cosine similarity."},"numResults":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results to return (1-100). Defaults to 10."},"selfOnly":{"type":"boolean","default":false,"description":"When true, only files created by the calling API key's user are returned. When false (default), all files accessible to the team are included."}}},"SearchFilesResponse":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchFilesResult"}}}},"SearchFilesResult":{"type":"object","required":["similarity","file"],"properties":{"similarity":{"type":"number","minimum":0,"maximum":1,"example":0.82,"description":"Cosine similarity between the query embedding and the file description embedding. Ranges from 0 (no match) to 1 (identical). Values above 0.7 typically indicate strong relevance."},"file":{"$ref":"#/components/schemas/FileInfo"}}},"CreateFileUploadRequest":{"type":"object","required":["displayName"],"properties":{"type":{"$ref":"#/components/schemas/FileType","description":"The type of file to upload. Optional; when omitted, the type is inferred after upload processing completes."},"displayName":{"type":"string","description":"Display name for the uploaded file."},"isTemporary":{"type":"boolean","default":false,"description":"When true, the file is temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false."},"transcript":{"description":"Optional pre-computed transcript for an audio or video upload, as timed `words`. When provided, transcription is skipped and caption timing matches your transcript. Ignored for non-audio/video files.","anyOf":[{"$ref":"#/components/schemas/Transcript"},{"type":"null"}]}}},"FileUploadResponse":{"type":"object","required":["fileId","uploadUrl"],"properties":{"fileId":{"type":"string","description":"The file id to use in subsequent API calls (e.g. `vg_file_...`)."},"uploadUrl":{"type":"string","description":"Pre-signed URL. PUT the raw file bytes to this URL to complete the upload."}}},"GetFilesResponse":{"type":"object","required":["files","hasMore","nextCursor"],"properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/FileInfo"}},"hasMore":{"type":"boolean","description":"When true, there are more files available. Pass `nextCursor` as the `cursor` query param to fetch the next page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` when `hasMore` is false."}}},"EntityReference":{"type":"object","description":"A file attached to an entity as a reference image.","required":["fileId","description","isDefault"],"properties":{"fileId":{"type":"string","description":"The reference image file id (e.g. `vg_file_...`). Hydrate it via `GET /v1/files/{fileId}` to fetch a viewable URL."},"description":{"type":"string","description":"Optional description of the reference. Empty string when not set."},"isDefault":{"type":"boolean","description":"When true, this is the entity's primary reference (used for its thumbnail)."}}},"EntityActorConfig":{"type":"object","description":"Read-only voice and presenter summary for an ACTOR entity. Always null for VISUAL_STYLE entities.","required":["hasVoice","hasAvatarPresenter"],"properties":{"voiceDisplayName":{"type":["string","null"],"description":"Display name of the actor's voice when one is configured. Null otherwise."},"hasVoice":{"type":"boolean","description":"True when the actor has a configured voice."},"hasAvatarPresenter":{"type":"boolean","description":"True when the actor has a configured avatar presenter."}}},"Entity":{"type":"object","description":"A reusable actor or visual style. Attach its reference images to workflows for consistent characters and looks.","required":["entityId","entityType","name","description","references","createdAt","updatedAt"],"properties":{"entityId":{"type":"string","description":"The entity id (e.g. `vg_enti_...`)."},"entityType":{"type":"string","enum":["ACTOR","PRODUCT","VISUAL_STYLE"],"description":"ACTOR features a consistent character; PRODUCT features a consistent product or object; VISUAL_STYLE guides the look of generated images."},"name":{"type":"string","description":"Display name."},"description":{"type":"string","description":"Optional description. Empty string when not set."},"actorConfig":{"anyOf":[{"$ref":"#/components/schemas/EntityActorConfig"},{"type":"null"}],"description":"Voice and presenter summary for ACTOR entities. Null for VISUAL_STYLE entities."},"references":{"type":"array","items":{"$ref":"#/components/schemas/EntityReference"},"description":"Reference images attached to the entity."},"createdAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) when the entity was created."},"updatedAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) when the entity was last updated."}}},"ListEntitiesResponse":{"type":"object","required":["entities","hasMore","nextCursor"],"properties":{"entities":{"type":"array","items":{"$ref":"#/components/schemas/Entity"}},"hasMore":{"type":"boolean","description":"When true, there are more entities available. Pass `nextCursor` as the `cursor` query param to fetch the next page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` when `hasMore` is false."}}},"CreateEntityRequest":{"type":"object","required":["entityType","name"],"properties":{"entityType":{"type":"string","enum":["ACTOR","PRODUCT","VISUAL_STYLE"],"description":"ACTOR features a consistent character; PRODUCT features a consistent product or object; VISUAL_STYLE guides the look of generated images."},"name":{"type":"string","description":"Display name."},"description":{"type":"string","description":"Optional description."}}},"UpdateEntityRequest":{"type":"object","description":"At least one field must be provided.","properties":{"name":{"type":["string","null"],"description":"New display name. Omit to leave unchanged."},"description":{"type":["string","null"],"description":"New description. Omit to leave unchanged."}}},"EntityArchiveResponse":{"type":"object","required":["entityId","archived"],"properties":{"entityId":{"type":"string","description":"The id of the archived entity."},"archived":{"type":"boolean","description":"Always true on success."}}},"AddEntityReferenceRequest":{"type":"object","required":["fileId"],"properties":{"fileId":{"type":"string","description":"The file id (e.g. `vg_file_...`) of an image to attach as a reference."},"description":{"type":"string","description":"Optional description of the reference."},"isDefault":{"type":"boolean","default":false,"description":"When true, make this the entity's primary reference (used for its thumbnail)."}}},"RemoveEntityReferenceRequest":{"type":"object","required":["fileId"],"properties":{"fileId":{"type":"string","description":"The file id (e.g. `vg_file_...`) of the reference to remove."}}},"AvatarPresenter":{"type":"object","description":"An avatar presenter available for video generation.","required":["avatarPresenterId","displayableGender","imageUrl","thumbnailUrl","previewVideoUrl"],"properties":{"avatarPresenterId":{"type":"string","description":"Presenter id (e.g. `vg_pres_...`). Pass as `avatarPresenterId` to `POST /v1/tools/generate-avatar`."},"displayableGender":{"type":"string","enum":["MALE","FEMALE","NEUTRAL"],"description":"Presenter gender."},"imageUrl":{"type":"string","format":"uri","description":"Still image of the presenter."},"thumbnailUrl":{"type":"string","format":"uri","description":"Thumbnail image of the presenter."},"previewVideoUrl":{"type":"string","format":"uri","description":"Short preview clip of the presenter speaking."}}},"AvatarPresenterListResponse":{"type":"object","required":["avatarPresenters","hasMore","nextCursor"],"properties":{"avatarPresenters":{"type":"array","items":{"$ref":"#/components/schemas/AvatarPresenter"}},"hasMore":{"type":"boolean","description":"When true, there are more avatar presenters available. Pass `nextCursor` as the `cursor` query param to fetch the next page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` when `hasMore` is false."}}},"TtsVoice":{"type":"object","description":"A text-to-speech voice.","required":["voiceId","languageCode","displayName","displayGender","supportsDirectToolExecution","supportsAllLanguages","isDeprecated"],"properties":{"voiceId":{"type":"string","description":"Voice id (e.g. `vg_voic_...`). Pass as `voiceId` to `POST /v1/tools/text-to-speech`."},"languageCode":{"type":"string","description":"Locale tag for the voice (e.g. `en-US`, `es-ES`)."},"displayName":{"type":"string","description":"Human-readable voice name."},"displayGender":{"type":"string","enum":["MALE","FEMALE","NEUTRAL"],"description":"Voice gender."},"accent":{"type":["string","null"],"description":"Accent (e.g. `american`, `british`)."},"description":{"type":["string","null"],"description":"Description of the voice."},"supportsDirectToolExecution":{"type":"boolean","description":"When false, this voice cannot be used directly with `POST /v1/tools/text-to-speech`. All voices, regardless of this field, can be used in full video generation workflows such as script-to-video."},"supportsAllLanguages":{"type":"boolean","description":"When true, this voice can synthesize text in any language regardless of its `languageCode`. When false, the voice only supports its listed language."},"isDeprecated":{"type":"boolean","description":"When true, this voice is deprecated and may be removed in a future API version. Prefer non-deprecated voices for new integrations."}}},"MeResponse":{"type":"object","required":["apiKeyId","apiKeyNickname","email","displayName","teamId"],"properties":{"apiKeyId":{"type":"string","description":"The id of the API key used to authenticate this request."},"apiKeyNickname":{"type":"string","description":"The nickname given to the API key when it was created."},"email":{"type":"string","description":"The email address of the account the API key belongs to."},"displayName":{"type":["string","null"],"description":"The display name of the account the API key belongs to. `null` if the account has not set one."},"teamId":{"type":"string","description":"The id of the team the API key belongs to."}}},"TtsVoiceListResponse":{"type":"object","required":["ttsVoices","hasMore","nextCursor"],"properties":{"ttsVoices":{"type":"array","items":{"$ref":"#/components/schemas/TtsVoice"}},"hasMore":{"type":"boolean","description":"When true, there are more voices available. Pass `nextCursor` as the `cursor` query param to fetch the next page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` when `hasMore` is false."}}},"Language":{"type":"object","required":["languageCode","name"],"description":"A language a project can be translated into.","properties":{"languageCode":{"type":"string","description":"The language code to pass to a `TRANSLATE_PROJECT` remix action (e.g. `es`, `fr`, `ja`)."},"name":{"type":"string","description":"Human-readable English name of the language (e.g. `Spanish`)."}}},"LanguageListResponse":{"type":"object","required":["languages"],"properties":{"languages":{"type":"array","items":{"$ref":"#/components/schemas/Language"}}}},"WatermarkMode":{"type":"string","enum":["NONE","VIDEO_GEN","AUTO"],"default":"AUTO","description":"Controls whether the VideoGen watermark is applied to the output. `AUTO` applies the watermark unless you have the Production API add-on. `VIDEO_GEN` always applies it. `NONE` removes the watermark (requires the Production API add-on; returns an error if you don't have it)."},"EndScreenMode":{"type":"string","enum":["NONE","VIDEO_GEN","AUTO"],"default":"AUTO","description":"Controls whether a short 'Made with VideoGen' end screen is appended to the output. `AUTO` appends it unless you have the Production API add-on. `VIDEO_GEN` always appends it. `NONE` removes it (requires the Production API add-on; returns an error if you don't have it)."},"AspectRatio":{"type":"object","required":["width","height"],"description":"Aspect ratio as a width:height pair (e.g. 16 and 9 for 16:9). Not pixel dimensions.","properties":{"width":{"type":"integer","minimum":1},"height":{"type":"integer","minimum":1}}},"GenerateTextRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","example":"Write a 30-second upbeat video script about why the sky is blue.","description":"The instruction or content to generate text from."},"system":{"type":["string","null"],"description":"Optional system instructions that steer the model's role, tone, and constraints."},"quality":{"$ref":"#/components/schemas/ModelQuality","description":"Text generation quality tier. Optional; when omitted, your workspace's Default AI quality for text is used (change it at https://app.videogen.io/settings/account)."},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"Sampling temperature. Higher values produce more varied output. Defaults to the model's default."},"maxOutputTokens":{"type":"integer","minimum":1,"maximum":2000,"default":512,"description":"Maximum number of tokens to generate. Defaults to 512."}}},"GenerateTextResponse":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"The generated text."}}},"StartAssistantChatRequest":{"type":"object","required":["message"],"properties":{"message":{"type":"string","example":"A 30-second explainer about our new pricing tiers","description":"The first message to send to the assistant, exactly as a person would type it into the assistant on a new project."},"forceWorkflowSuggestion":{"type":"boolean","default":false,"description":"When true, the assistant must respond with at least one workflow suggestion. If it doesn't, the assistant message is settled to `failed` with a `no_workflow_suggestion` error."},"autoGenerate":{"type":"boolean","default":false,"description":"When true, the assistant picks the best workflow for the message and immediately starts generating, skipping the suggestion step. When the assistant message reaches `succeeded`, its `generation` carries the workflow run to poll."}}},"SendAssistantMessageRequest":{"type":"object","required":["message"],"properties":{"message":{"type":"string","example":"Make it more upbeat and add captions","description":"The message to send to the assistant in this project chat."}}},"ActOnAssistantActionRequest":{"type":"object","properties":{"decision":{"type":"string","enum":["APPROVE","REJECT"],"default":"APPROVE","description":"Whether to approve (apply) or reject the action. Defaults to `APPROVE`."}}},"StartAssistantChatResponse":{"type":"object","description":"Returned when a `POST /v1/assistants` call is accepted. Poll `messageId` for the pending assistant reply; keep `assistantId` / `projectId` to continue the chat and address the project.","required":["messageId","assistantId","projectId","projectUrl"],"properties":{"messageId":{"type":"string","description":"Opaque assistant message id for the pending assistant reply (e.g. `vg_mesg_...`). Poll `GET /v1/assistant-messages/{messageId}`."},"assistantId":{"type":"string","description":"Opaque assistant chat id (e.g. `vg_asst_...`). Pass to `GET /v1/assistants/{assistantId}` and follow-up message/action calls."},"projectId":{"type":"string","description":"Opaque project id for the new chat (e.g. `vg_proj_...`)."},"projectUrl":{"type":"string","format":"uri","description":"Deep link to open this project in the VideoGen web app."}}},"SendAssistantMessageResponse":{"type":"object","description":"Returned when a `POST /v1/assistants/{assistantId}/messages` call is accepted. Use `messageId` to poll the pending assistant reply.","required":["messageId"],"properties":{"messageId":{"type":"string","description":"Opaque assistant message id for the pending assistant reply (e.g. `vg_mesg_...`). Poll `GET /v1/assistant-messages/{messageId}`."}}},"ActOnAssistantActionResponse":{"type":"object","description":"Returned when a `POST /v1/assistants/{assistantId}/actions/{actionId}` call is accepted. Use `messageId` to poll the resulting assistant message.","required":["messageId"],"properties":{"messageId":{"type":"string","description":"Opaque assistant message id for the assistant reply produced by acting on the action (e.g. `vg_mesg_...`). Poll `GET /v1/assistant-messages/{messageId}`."}}},"AssistantMessageStatus":{"type":"string","description":"Lifecycle status of an assistant chat message. `pending` and `running` are in-progress; `succeeded`, `failed`, and `cancelled` are terminal.","enum":["pending","running","succeeded","failed","cancelled"]},"AssistantActionKind":{"type":"string","description":"Normalized category of an actionable widget the assistant offered. `APPROVE_PLAN` accepts a proposed generation plan; `APPLY_EDIT` applies a proposed edit (e.g. a rewritten script); `RUN_TOOL` runs an inline tool; `GENERATE` starts building the video; `OPEN_IN_APP` requires the full web app — open the assistant's `projectUrl` instead of acting via the API.","enum":["APPROVE_PLAN","APPLY_EDIT","RUN_TOOL","GENERATE","OPEN_IN_APP"]},"AssistantWorkflowSuggestion":{"type":"object","description":"A starting-point workflow the assistant suggests for the conversation. Act on it with `POST /v1/assistants/{assistantId}/actions/{actionId}` to select the workflow and continue.","required":["actionId","workflowType","title","description"],"properties":{"actionId":{"type":"string","description":"Opaque id to pass to the act-on-action endpoint to select this workflow."},"workflowType":{"$ref":"#/components/schemas/WorkflowType","description":"Identifier of the suggested workflow."},"title":{"type":"string","description":"Short human-readable name of the suggested workflow."},"description":{"type":"string","description":"One-line explanation of what this workflow will do."}}},"AssistantActionDetail":{"type":"object","description":"Extra data for rendering this action inline (in a chat surface or integration) without opening the web app. Fields are populated only when relevant to the action's kind; all are optional.","properties":{"summary":{"type":["string","null"],"description":"Human-readable summary of the proposed plan or edit (for `APPROVE_PLAN` and `APPLY_EDIT` actions)."},"creditsRemaining":{"type":["integer","null"],"description":"Credits currently remaining on your team (for the usage/credits widget). A whole number of credits."},"estimatedCredits":{"type":["integer","null"],"description":"Estimated credit cost of the current workflow (for the cost-estimate widget). A whole number of credits."}}},"AssistantAction":{"type":"object","description":"An actionable widget the assistant offered on this turn. Act on it with `POST /v1/assistants/{assistantId}/actions/{actionId}` unless `requiresApp` is true.","required":["actionId","kind","label","requiresApp"],"properties":{"actionId":{"type":"string","description":"Opaque id to pass to the act-on-action endpoint."},"kind":{"$ref":"#/components/schemas/AssistantActionKind"},"label":{"type":"string","description":"Human-readable label describing what acting on this will do."},"requiresApp":{"type":"boolean","description":"When true, this action can only be completed in the web app; open the assistant's `projectUrl` instead of calling the API."},"detail":{"$ref":"#/components/schemas/AssistantActionDetail","description":"Optional extra data for rendering this action inline without opening the app."}}},"AssistantMessageAttachment":{"type":"object","description":"A file linked to an assistant chat message.","required":["displayName"],"properties":{"fileId":{"type":["string","null"],"description":"File id (e.g. `vg_file_...`) when the attachment is a storage file. `null` for attachments that are not resolvable storage files."},"displayName":{"type":"string","description":"Human-readable name of the attachment."}}},"AssistantInputMessage":{"type":"object","description":"A user-authored message in an assistant chat.","required":["messageId","role","status","content","attachments","createdAt"],"properties":{"messageId":{"type":"string","description":"Opaque assistant message id (e.g. `vg_mesg_...`)."},"role":{"type":"string","enum":["user"],"description":"Always `user`."},"status":{"$ref":"#/components/schemas/AssistantMessageStatus"},"content":{"type":"string","description":"The user's message text."},"attachments":{"type":"array","description":"Files attached to this message.","items":{"$ref":"#/components/schemas/AssistantMessageAttachment"}},"createdAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) when the message was created."}}},"AssistantOutputMessage":{"type":"object","description":"An assistant-authored message in an assistant chat, including any suggestions or actions it offered.","required":["messageId","role","status","content","attachments","workflowSuggestions","actions","generation","error","createdAt"],"properties":{"messageId":{"type":"string","description":"Opaque assistant message id (e.g. `vg_mesg_...`)."},"role":{"type":"string","enum":["assistant"],"description":"Always `assistant`."},"status":{"$ref":"#/components/schemas/AssistantMessageStatus"},"content":{"type":["string","null"],"description":"The assistant's text reply. `null` while `status` is `pending` or `running`; may be empty when the assistant only offered widgets."},"attachments":{"type":"array","description":"Files attached to this message.","items":{"$ref":"#/components/schemas/AssistantMessageAttachment"}},"workflowSuggestions":{"type":"array","description":"Workflow starting points the assistant suggested on this message. Empty when none were offered.","items":{"$ref":"#/components/schemas/AssistantWorkflowSuggestion"}},"actions":{"type":"array","description":"Actionable widgets the assistant offered on this message (plans, edits, tools, generate). Empty when none were offered.","items":{"$ref":"#/components/schemas/AssistantAction"}},"generation":{"description":"Present when this message kicked off a workflow run (via `autoGenerate` on start, or acting on a workflow suggestion): the workflow run to poll via `GET /v1/workflows/runs/{workflowRunId}`.","anyOf":[{"$ref":"#/components/schemas/StartWorkflowRunResponse"},{"type":"null"}]},"error":{"description":"Error details. `null` unless `status` is `failed`.","anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]},"createdAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) when the message was created."}}},"AssistantMessage":{"description":"A single message in an assistant chat. Discriminated by `role`.","oneOf":[{"$ref":"#/components/schemas/AssistantInputMessage"},{"$ref":"#/components/schemas/AssistantOutputMessage"}],"discriminator":{"propertyName":"role","mapping":{"user":"#/components/schemas/AssistantInputMessage","assistant":"#/components/schemas/AssistantOutputMessage"}}},"GetAssistantResponse":{"type":"object","description":"An assistant chat and every message it currently contains.","required":["assistantId","projectId","projectUrl","messages"],"properties":{"assistantId":{"type":"string","description":"Opaque assistant chat id (e.g. `vg_asst_...`)."},"projectId":{"type":"string","description":"Opaque project id of the project this chat belongs to (e.g. `vg_proj_...`)."},"projectUrl":{"type":"string","format":"uri","description":"Deep link to open this chat's project in the VideoGen web app. Visible only to members of your team and project collaborators."},"messages":{"type":"array","description":"Every message in the chat in chronological order (oldest first).","items":{"$ref":"#/components/schemas/AssistantMessage"}}}},"GenerateImageRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","example":"A serene Japanese garden with cherry blossoms at golden hour","description":"Text prompt describing the image to generate. When reference images are provided, the prompt describes the desired transformation."},"imageFileIds":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Optional file ids of reference images (e.g. `[\"vg_file_...\"]`). Upload files first via `POST /v1/files/upload`, then pass the returned ids here. Maximum 4 images. When provided, the model uses these as guidance for generation."},"aspectRatio":{"$ref":"#/components/schemas/AspectRatio","description":"Aspect ratio for the generated image. Defaults to 16:9 when omitted."},"quality":{"$ref":"#/components/schemas/ModelQuality","description":"Image generation quality tier. Optional; when omitted, your workspace's Default AI quality for images is used (change it at https://app.videogen.io/settings/account)."},"watermarkMode":{"$ref":"#/components/schemas/WatermarkMode"},"numResults":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of output results to generate. Defaults to 1."},"isOutputTemporary":{"type":"boolean","default":false,"description":"When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false."}}},"GenerateVideoClipRequest":{"type":"object","description":"At least one of `prompt`, `imageFileIds`, `videoFileIds`, or `audioFileIds` must be provided.","properties":{"prompt":{"type":"string","example":"A golden retriever running through a sunlit meadow in slow motion, cinematic","description":"Text prompt describing the video to generate. Optional when reference media is provided. Describe the video in plain language; any reference media you provide is incorporated automatically."},"imageFileIds":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Optional file ids of reference images (e.g. `[\"vg_file_...\"]`). Upload files first via `POST /v1/files/upload`, then pass the returned ids here. When provided, the images are animated or used as visual guidance for the generated video."},"videoFileIds":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Optional file ids of reference videos (e.g. `[\"vg_file_...\"]`). Upload files first via `POST /v1/files/upload`, then pass the returned ids here. They are used as motion or style guidance for the generated video."},"audioFileIds":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Optional file ids of reference audio clips (e.g. `[\"vg_file_...\"]`) used for native lip-sync and soundtrack. Upload files first via `POST /v1/files/upload`, then pass the returned ids here."},"generateAudio":{"type":"boolean","default":false,"description":"When true, the generated video is guaranteed to include audio. When false, audio may still be present. Defaults to false."},"durationSeconds":{"type":["integer","null"],"minimum":1,"maximum":15,"description":"Desired clip length in seconds. A whole number between 1 and 15. Defaults to 6 when omitted. This endpoint produces a single short clip. For longer, multi-scene, professionally edited videos, use a video workflow such as `POST /v1/workflows/script-to-video`."},"aspectRatio":{"$ref":"#/components/schemas/AspectRatio","description":"Aspect ratio for the generated video. Defaults to 16:9 when omitted."},"quality":{"$ref":"#/components/schemas/ModelQuality","description":"Video generation quality tier. Optional; when omitted, your workspace's Default AI quality for video is used (change it at https://app.videogen.io/settings/account). `LOW` is not supported for video clip generation and is rejected."},"watermarkMode":{"$ref":"#/components/schemas/WatermarkMode"},"numResults":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of output results to generate. Defaults to 1."},"isOutputTemporary":{"type":"boolean","default":false,"description":"When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false."}}},"GenerateMotionGraphicRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","example":"A dark terminal window that types out the command `npm run build` character by character, then shows a green success checkmark","description":"Text prompt describing the animated motion graphic to generate. Describe the on-screen elements, any text and how it should animate, and the overall motion in plain language."},"fileIds":{"type":"array","items":{"type":"string"},"maxItems":8,"description":"Optional file ids of uploaded reference media (images, videos, or audio) the motion graphic may display or animate (e.g. `[\"vg_file_...\"]`). Upload files first via `POST /v1/files/upload`, then pass the returned ids here."},"durationSeconds":{"type":["integer","null"],"minimum":1,"maximum":300,"description":"Desired length of the motion graphic in seconds, a whole number between 1 and 300. When omitted, the duration is chosen automatically to fit the prompt (recommended)."},"aspectRatio":{"$ref":"#/components/schemas/AspectRatio","description":"Aspect ratio for the generated motion graphic. Defaults to 16:9 when omitted."},"numResults":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of output results to generate. Defaults to 1."},"isOutputTemporary":{"type":"boolean","default":false,"description":"When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false."}}},"PronunciationReplacement":{"type":"object","required":["original","replacement"],"properties":{"original":{"type":"string"},"replacement":{"type":"string"}}},"TextToSpeechRequest":{"type":"object","required":["ttsText","voiceId"],"properties":{"ttsText":{"type":"string"},"voiceId":{"type":"string","description":"Voice id from `GET /v1/resources/tts-voices`. Only voices with `supportsDirectToolExecution` set to true are accepted."},"speechLanguageCode":{"type":["string","null"],"description":"ISO-639-1 language hint for pronunciation (e.g. `en`, `es`, `zh`)."},"pronunciationReplacements":{"type":"array","items":{"$ref":"#/components/schemas/PronunciationReplacement"}},"autoExpandPronunciationReplacements":{"type":"boolean","description":"When true, automatically expands numbers, symbols, acronyms, and other non-word tokens into their spoken forms before synthesis so the voice pronounces them correctly (e.g. `$100` → `one hundred dollars`, `NASA` → `nasa`, `3rd` → `third`). Defaults to false when omitted."},"voiceSpeed":{"type":"number","minimum":0.5,"maximum":2,"description":"Speech rate multiplier, between 0.5 (half speed) and 2 (double speed). Defaults to the voice's default speed."},"numResults":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of output results to generate. Defaults to 1."},"isOutputTemporary":{"type":"boolean","default":false,"description":"When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false."}}},"GenerateSoundEffectRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"A text description of the sound effect to generate."},"durationSeconds":{"type":["number","null"],"minimum":1,"maximum":30,"description":"Desired length of the sound effect in seconds, between 1 and 30. Defaults to about 10 seconds when omitted."},"promptInfluence":{"type":["number","null"],"minimum":0,"maximum":1,"description":"How closely the generated sound effect follows the prompt, between 0 (more creative, more variation) and 1 (more literal, less variation). Defaults to a balanced value when omitted."},"numResults":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of output results to generate. Defaults to 1."},"isOutputTemporary":{"type":"boolean","default":false,"description":"When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false."}}},"GenerateMusicRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"A text description of the music to generate. Include genre, mood, instrumentation, and tempo for best results."},"numResults":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of output results to generate. Defaults to 1."},"isOutputTemporary":{"type":"boolean","default":false,"description":"When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false."}}},"GenerateAvatarRequest":{"type":"object","required":["avatarPresenterId","audioFileId"],"properties":{"avatarPresenterId":{"type":"string","description":"Presenter id from `GET /v1/resources/avatar-presenters`."},"audioFileId":{"type":"string","description":"File id of an AUDIO file (e.g. `vg_file_...`), typically from a prior text-to-speech result. Upload a file first via `POST /v1/files/upload` or generate one with `POST /v1/tools/text-to-speech`, then pass the returned id here."},"watermarkMode":{"$ref":"#/components/schemas/WatermarkMode"},"numResults":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of output results to generate. Defaults to 1."},"isOutputTemporary":{"type":"boolean","default":false,"description":"When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false."}}},"ImageAssetRequest":{"type":"object","required":["imageFileId"],"properties":{"imageFileId":{"type":"string","description":"File id of the source image (e.g. `vg_file_...`). Upload a file first via `POST /v1/files/upload`, then pass the returned id here."},"watermarkMode":{"$ref":"#/components/schemas/WatermarkMode"},"numResults":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of output results to generate. Defaults to 1."},"isOutputTemporary":{"type":"boolean","default":false,"description":"When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false."}}},"ModelQuality":{"type":"string","enum":["LOW","STANDARD","HIGH","MAX"],"description":"AI generation quality tier, shared across every generative feature (image, video, text, and so on). `LOW` is fastest and cheapest, `STANDARD` balances quality and cost, `HIGH` is higher quality, and `MAX` is the highest quality.\n\nWhen a request omits the quality field, VideoGen falls back to your workspace's **Default AI quality** for that feature, which you can change at [Account settings](https://app.videogen.io/settings/account). Not every feature supports every tier; unsupported tiers are rejected with an error (see each field's description).\n"},"VideoAssetRequest":{"type":"object","required":["videoFileId"],"properties":{"videoFileId":{"type":"string","description":"File id of the source video (e.g. `vg_file_...`). Upload a file first via `POST /v1/files/upload`, then pass the returned id here."},"watermarkMode":{"$ref":"#/components/schemas/WatermarkMode"},"numResults":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of output results to generate. Defaults to 1."},"isOutputTemporary":{"type":"boolean","default":false,"description":"When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false."}}},"StartToolExecutionResponse":{"type":"object","description":"Returned when a tool execution is started. Use `toolExecutionId` to poll for results or cancel.","required":["toolExecutionId"],"properties":{"toolExecutionId":{"type":"string","description":"Execution id (e.g. `vg_tool_...`)."}}},"JobStatus":{"type":"string","description":"Lifecycle status shared by every asynchronous job (tool executions, workflow runs, remix actions, project exports, and timeline interchange jobs). `pending` and `running` are in-progress; `succeeded`, `failed`, and `cancelled` are terminal.","enum":["pending","running","succeeded","failed","cancelled"]},"ToolSuccessResult":{"type":"object","description":"Result for a single generated file. Only appears inside a succeeded execution's `results`, so every field below is always present.","required":["fileId","type","downloadUrl","downloadUrlExpiresAt","thumbnailUrl","thumbnailUrlExpiresAt","file"],"properties":{"fileId":{"type":"string","description":"File id for the generated asset."},"type":{"$ref":"#/components/schemas/FileType","description":"File type."},"downloadUrl":{"type":["string","null"],"format":"uri","description":"Private signed download URL for the generated file, valid for 24 hours from when it was signed. Provided at the top level for convenience so you don't have to read it out of `file`. When you GET a single execution it is automatically re-signed if within an hour of expiring; list endpoints do not re-sign, so there it may be expired (check `downloadUrlExpiresAt`). See `downloadUrlExpiresAt` for the exact expiry. Null only in the rare case that the highest-quality rendition is still finalizing."},"downloadUrlExpiresAt":{"type":["integer","null"],"description":"Seconds since epoch (Unix timestamp) when `downloadUrl` expires. Null only when `downloadUrl` is null."},"thumbnailUrl":{"type":["string","null"],"format":"uri","description":"Private signed thumbnail URL for the generated file, valid for 24 hours from when it was signed. Provided at the top level for convenience so you don't have to read it out of `file`. Re-signed on the same terms as `downloadUrl` (single-execution GET re-signs when near expiry; list endpoints do not). Null for file types that have no thumbnail (e.g. audio)."},"thumbnailUrlExpiresAt":{"type":["integer","null"],"description":"Seconds since epoch (Unix timestamp) when `thumbnailUrl` expires. Null when there is no thumbnail URL."},"file":{"description":"Hydrated file metadata with signed download URLs (always present and hydrated for a succeeded result). Its signed URLs follow the same 24-hour validity and automatic re-signing as `downloadUrl`.","$ref":"#/components/schemas/FileInfo"}}},"ErrorRequirement":{"type":"object","description":"What is needed to resolve an error, when it can be fixed by fulfilling a specific requirement (e.g. purchasing an add-on or upgrading the plan).","required":["type"],"properties":{"type":{"type":"string","description":"Machine-readable requirement type in snake_case (e.g. `purchase_add_on`, `upgrade_plan`)."},"details":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value pairs with requirement-specific context (e.g. the add-on id to purchase)."}}},"ApiError":{"type":"object","description":"Standard error body returned with every non-2xx response (the `default` response of every operation). The HTTP status code conveys the error class; this body carries the details:\n\n- `400` invalid request, `401` missing or invalid API key, `403` not permitted (e.g. plan or add-on required, see `requirement`), `404` not found, `409` conflict, `429` rate limited or out of credits, `5xx` server error.\n\nCommon `code` values include `invalid_request`, `invalid_api_key`, `not_authorized`, `not_found`, `insufficient_credits`, and `rate_limited`. Always branch on `code` (and `requirement.type` when present) rather than parsing `message`.\n","required":["message"],"properties":{"message":{"type":"string","description":"Human-readable error description. For display and logging only; do not branch on its exact text."},"code":{"type":["string","null"],"description":"Machine-readable error code in snake_case (e.g. `invalid_api_key`, `insufficient_credits`). `null` when no specific code applies."},"requirement":{"description":"What is needed to resolve the error. Present when the error can be fixed by fulfilling a specific requirement (e.g. purchasing an add-on); `null` otherwise.","anyOf":[{"$ref":"#/components/schemas/ErrorRequirement"},{"type":"null"}]},"internalErrorCode":{"type":["string","null"],"description":"Opaque internal error code for debugging. Include this when contacting support. `null` when not applicable."}}},"ExecutedTool":{"type":"object","required":["toolExecutionId","status","toolType","progressPercentage","attemptIndex","results","error"],"properties":{"toolExecutionId":{"type":"string","description":"Execution id matching the original request."},"status":{"$ref":"#/components/schemas/JobStatus"},"toolType":{"type":"string","description":"Tool name (e.g. `GENERATE_IMAGE`, `TEXT_TO_SPEECH`)."},"progressPercentage":{"type":"number","minimum":0,"maximum":100,"description":"Completion progress for the current attempt (0-100). Always `100` when `status` is `succeeded`."},"attemptIndex":{"type":"integer","minimum":0,"description":"Zero-based index of the current or most recent execution attempt."},"results":{"type":"array","description":"One entry per generated result. Always present; empty until `status` is `succeeded`, then one entry per generated file (each with signed URLs and a hydrated `file`).","items":{"$ref":"#/components/schemas/ToolSuccessResult"}},"error":{"description":"Error details. Always present; `null` unless `status` is `failed`.","anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]}}},"ToolExecutionListResponse":{"type":"object","description":"Paginated list of API-started tool executions, most recently created first.","required":["toolExecutions","hasMore","nextCursor"],"properties":{"toolExecutions":{"type":"array","items":{"$ref":"#/components/schemas/ExecutedTool"}},"hasMore":{"type":"boolean","description":"When true, there are more executions available. Pass `nextCursor` as the `cursor` query param to fetch the next page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` when `hasMore` is false."}}},"ToolExecutionWebhookEventName":{"type":"string","description":"Webhook event types for tool execution lifecycle.","enum":["tool_execution.succeeded","tool_execution.failed","tool_execution.cancelled"]},"WorkflowRunWebhookEventName":{"type":"string","description":"Lifecycle events emitted for workflow runs started via the developer API.","enum":["workflow_run.succeeded","workflow_run.failed","workflow_run.cancelled"]},"FileWebhookEventName":{"type":"string","description":"Webhook event types for the file lifecycle (upload, analysis, playback, and download readiness). Only fired for files uploaded via the API (not the VideoGen UI).","enum":["file.upload.completed","file.upload.failed","file.playback_ready","file.download_ready","file.analysis_completed","file.analysis_failed"]},"AssistantMessageWebhookEventName":{"type":"string","description":"Lifecycle events for assistant messages started via the developer API.","enum":["assistant_message.succeeded","assistant_message.failed","assistant_message.cancelled"]},"WebhookEventName":{"type":"string","description":"All webhook event types. Use when creating or listing webhook endpoints.","enum":["tool_execution.succeeded","tool_execution.failed","tool_execution.cancelled","workflow_run.succeeded","workflow_run.failed","workflow_run.cancelled","assistant_message.succeeded","assistant_message.failed","assistant_message.cancelled","file.upload.completed","file.upload.failed","file.playback_ready","file.download_ready","file.analysis_completed","file.analysis_failed"]},"WorkflowType":{"type":"string","description":"Workflow type identifier.","enum":["SCRIPT_TO_VIDEO","VOICEOVER_TO_VIDEO","SLIDESHOW_TO_VIDEO","STORYBOARD_TO_VIDEO","PROMPT_TO_VIDEO_CLIP","CONTENT_OUTLINE_TO_VIDEO"]},"VisualPacing":{"type":"string","enum":["FAST","MEDIUM","SLOW"],"default":"MEDIUM","description":"How quickly visuals change. FAST shows more, shorter shots; SLOW holds each visual longer. Defaults to MEDIUM."},"WorkflowVisualStyle":{"type":"object","required":["type"],"description":"Visual style for the generated b-roll.","properties":{"type":{"type":"string","enum":["STOCK","AI_IMAGE","ENTITY"],"description":"STOCK pulls stock footage and images. AI_IMAGE generates a styled image for each section. ENTITY generates images that match a visual-style entity's reference images for a consistent look."},"aiStyle":{"type":"string","description":"Only applies when type is AI_IMAGE. A free-form description of the look applied to every generated image (e.g. `vintage 1970s film photography, warm grain`). See the AI styles reference for example descriptions of the app's default styles. Required when type is AI_IMAGE."},"entityId":{"type":"string","description":"Only applies when type is ENTITY. The id of a VISUAL_STYLE entity (e.g. `vg_enti_...`) whose reference images guide every generated image. Required when type is ENTITY."},"restyleFeaturedBRollWithAiStyle":{"type":"boolean","default":true,"description":"Only applies when type is AI_IMAGE. When true, featured b-roll images you provide are re-rendered in the chosen style so they match the generated look (no effect on featured b-roll videos). Defaults to true."}}},"WorkflowRgbColor":{"type":"object","required":["red","green","blue"],"description":"An RGB color. Each channel is an integer from 0 to 255.","properties":{"red":{"type":"integer","minimum":0,"maximum":255},"green":{"type":"integer","minimum":0,"maximum":255},"blue":{"type":"integer","minimum":0,"maximum":255}}},"WorkflowCaptionBackgroundStyle":{"type":"object","required":["type","backgroundColor"],"description":"Background drawn behind caption text.","properties":{"type":{"type":"string","enum":["RECT","WRAPPED","WORD_BY_WORD"],"description":"RECT draws one rectangle behind the whole line; WRAPPED hugs the text; WORD_BY_WORD draws a box per word."},"backgroundColor":{"$ref":"#/components/schemas/WorkflowRgbColor"},"borderRadiusProportion":{"type":"number","minimum":0,"maximum":1,"description":"Corner rounding as a proportion of the background height, between 0 (square corners) and 1 (fully rounded)."},"opacityProportion":{"type":"number","minimum":0,"maximum":1,"description":"Background opacity from 0 (transparent) to 1 (opaque)."}}},"WorkflowCaptionStyle":{"type":"object","description":"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.","properties":{"fontName":{"type":"string","description":"Font family name."},"fontSize":{"type":"number","minimum":1,"description":"Font size in pixels at 1080p. Must be greater than 0."},"fontWeight":{"type":"integer","enum":[100,200,300,400,500,600,700,800,900],"description":"Numeric font weight (400 = regular, 700 = bold)."},"textColor":{"$ref":"#/components/schemas/WorkflowRgbColor"},"textJustification":{"type":"string","enum":["LEFT","CENTER","RIGHT"]},"verticalAlignment":{"type":"string","enum":["TOP","MIDDLE","BOTTOM"],"description":"Vertical position of the caption block in the frame."},"strokeColor":{"description":"Outline color around glyphs, or null for no outline.","anyOf":[{"$ref":"#/components/schemas/WorkflowRgbColor"},{"type":"null"}]},"strokeWeight":{"type":"number","minimum":0,"description":"Outline thickness in pixels. 0 disables the outline."},"backgroundStyle":{"description":"Background drawn behind the text, or null for no background.","anyOf":[{"$ref":"#/components/schemas/WorkflowCaptionBackgroundStyle"},{"type":"null"}]},"spokenTextColor":{"description":"Color applied to the currently spoken word for karaoke-style highlighting, or null to keep the base text color.","anyOf":[{"$ref":"#/components/schemas/WorkflowRgbColor"},{"type":"null"}]},"spokenTextStrokeColor":{"description":"Outline color applied to the currently spoken word, or null.","anyOf":[{"$ref":"#/components/schemas/WorkflowRgbColor"},{"type":"null"}]},"persistSpokenTextColor":{"type":"boolean","description":"When true, a word keeps the spoken-text color after it has been spoken instead of reverting."}}},"RemixActionType":{"type":"string","description":"The kind of edit a remix action applies.","enum":["SET_BACKGROUND_MUSIC","SET_LOGO","ENABLE_CAPTIONS","DISABLE_CAPTIONS","ADD_TRANSITIONS","RESIZE_PROJECT","CLEAN_UP_TRANSCRIPT","CONVERT_IMAGES_TO_VIDEOS","REGENERATE_IMAGES","UPSCALE_ASSETS","CHANGE_NARRATOR","SHUFFLE_STOCK_VISUALS","GENERATE_MUSIC","TRANSLATE_PROJECT"]},"RemixTransitionStyle":{"type":"string","description":"A transition applied at a boundary. `DYNAMIC` auto-varies the style across boundaries; `NONE` removes transitions; the rest apply that fixed style everywhere.","enum":["DYNAMIC","NONE","FADE","RISE","PAN","POP","WIPE"]},"RemixActionSetBackgroundMusic":{"type":"object","required":["type"],"description":"Set, replace, or remove the project's background music track.","properties":{"type":{"type":"string","enum":["SET_BACKGROUND_MUSIC"]},"fileId":{"type":["string","null"],"description":"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":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Music volume from 0 (silent) to 1 (full). Omit or pass `null` to keep the current volume."}}},"RemixActionSetLogo":{"type":"object","required":["type"],"description":"Set, replace, or remove the logo overlay.","properties":{"type":{"type":"string","enum":["SET_LOGO"]},"fileId":{"type":["string","null"],"description":"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":{"type":["string","null"],"enum":["TOP_LEFT","TOP_CENTER","TOP_RIGHT","BOTTOM_LEFT","BOTTOM_CENTER","BOTTOM_RIGHT",null],"description":"Position the logo is anchored to. Omit or pass `null` to keep the current position."},"sizePercent":{"type":["number","null"],"description":"Logo width as a percentage of the video width. Omit or pass `null` to keep the current size."}}},"RemixActionEnableCaptions":{"type":"object","required":["type"],"description":"Show captions on every captionable section. Optionally override the project caption style.","properties":{"type":{"type":"string","enum":["ENABLE_CAPTIONS"]},"captionStyle":{"description":"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.","anyOf":[{"$ref":"#/components/schemas/WorkflowCaptionStyle"},{"type":"null"}]}}},"RemixActionDisableCaptions":{"type":"object","required":["type"],"description":"Hide captions on every captionable section.","properties":{"type":{"type":"string","enum":["DISABLE_CAPTIONS"]}}},"RemixActionAddTransitions":{"type":"object","required":["type"],"description":"Stamp transitions across the project. Not per-boundary: each field you set is applied uniformly to every boundary in that scope, replacing any transition already there. Set the transition between sections, between base-layer assets, or both; omit or pass `null` for a scope to leave its transitions untouched.","properties":{"type":{"type":"string","enum":["ADD_TRANSITIONS"]},"sectionTransition":{"description":"Transition applied at every boundary between sections, replacing any existing section transitions. Omit or pass `null` to leave section transitions untouched.","anyOf":[{"$ref":"#/components/schemas/RemixTransitionStyle"},{"type":"null"}]},"assetTransition":{"description":"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.","anyOf":[{"$ref":"#/components/schemas/RemixTransitionStyle"},{"type":"null"}]}}},"RemixActionResizeProject":{"type":"object","required":["type","aspectRatio"],"description":"Change the project's output aspect ratio (e.g. to a vertical 9:16 social format). The video is re-flowed to the new ratio.","properties":{"type":{"type":"string","enum":["RESIZE_PROJECT"]},"aspectRatio":{"$ref":"#/components/schemas/AspectRatio"}}},"RemixActionCleanUpTranscript":{"type":"object","required":["type"],"description":"Tighten every transcript in the project by removing silent pauses and/or filler words. Useful for polishing narration captured from raw recordings.","properties":{"type":{"type":"string","enum":["CLEAN_UP_TRANSCRIPT"]},"removeFillers":{"type":["boolean","null"],"description":"Remove filler words (\"um\", \"uh\", …). Defaults to `true`."},"removePauses":{"type":["boolean","null"],"description":"Remove silent pauses longer than `minPauseSeconds`. Defaults to `true`."},"fillerWords":{"type":["array","null"],"items":{"type":"string"},"description":"Override the filler-word list to remove. Omit or pass `null` to use the built-in defaults."},"minPauseSeconds":{"type":["number","null"],"minimum":0,"description":"Shortest pause (in seconds) to remove; pauses below this stay. Omit or pass `null` to use the default threshold."}}},"RemixActionConvertImagesToVideos":{"type":"object","required":["type"],"description":"Animate every eligible still image in the project into a short AI video clip (image-to-video), replacing each image in place. Eligible images are non-SVG image assets backed by an uploaded or stock file. Runs asynchronously: one clip is generated per image. If the project has no eligible images, the action is skipped and completes successfully without changing anything (for example, a project whose timeline is already all video clips).","properties":{"type":{"type":"string","enum":["CONVERT_IMAGES_TO_VIDEOS"]},"motionPrompt":{"type":["string","null"],"description":"Describe the motion to apply to every image (e.g. \"slow cinematic push-in\"). Omit or pass `null` for automatic motion."},"muteOutputVideos":{"type":["boolean","null"],"description":"Mute the generated clips and suppress generated background music. Recommended when the clips sit behind a voiceover. Defaults to `true`."},"quality":{"$ref":"#/components/schemas/ModelQuality","description":"Video generation quality tier for the image-to-video conversions. Optional; when omitted, your workspace's Default AI quality for video is used (change it at https://app.videogen.io/settings/account). `LOW` is not supported for video and is rejected."}}},"RemixActionRegenerateImages":{"type":"object","required":["type","stylePrompt"],"description":"Restyle every eligible still image in the project to a new look (image-to-image), replacing each image in place. Eligible images are non-SVG image assets backed by an uploaded or generated file. Runs asynchronously: one restyled image is generated per eligible image. If the project has no eligible images, the action is skipped and completes successfully without changing anything.","properties":{"type":{"type":"string","enum":["REGENERATE_IMAGES"]},"stylePrompt":{"type":"string","description":"Describe the visual style to apply to every image (e.g. \"watercolor painting\", \"cinematic film still\")."},"quality":{"$ref":"#/components/schemas/ModelQuality","description":"Image generation quality tier for the restyled images. Optional; when omitted, your workspace's Default AI quality for images is used (change it at https://app.videogen.io/settings/account)."}}},"RemixActionUpscaleAssets":{"type":"object","required":["type"],"description":"Sharpen every eligible asset in the project up to 4K, replacing each in place. Runs asynchronously: one upscaled asset is generated per eligible asset. If the project has no eligible assets, the action is skipped and completes successfully without changing anything.","properties":{"type":{"type":"string","enum":["UPSCALE_ASSETS"]},"includeVideos":{"type":["boolean","null"],"description":"Also upscale video assets (billed per output second). Defaults to `true`."},"includeStockContent":{"type":["boolean","null"],"description":"Also upscale stock (library) assets, not just uploaded or generated ones. Defaults to `true`."}}},"RemixActionChangeNarrator":{"type":"object","required":["type","voiceId"],"description":"Re-narrate every AI-voiceover asset in the project with a new voice (and optionally a presenter avatar), replacing each narration in place. Runs asynchronously: text-to-speech is re-fired per asset with the original narration text. If the project has no AI-narrated assets, the action is skipped and completes successfully without changing anything.","properties":{"type":{"type":"string","enum":["CHANGE_NARRATOR"]},"voiceId":{"type":"string","description":"Voice id from `GET /v1/resources/tts-voices` (e.g. `vg_voic_...`) to re-narrate with."},"avatarPresenterId":{"type":["string","null"],"description":"Optional avatar presenter id from `GET /v1/resources/avatar-presenters` (e.g. `vg_pres_...`). When set, the narration is delivered by a talking-head presenter avatar. Pass your `voiceId` to that endpoint to list presenters sorted by best match for the voice. Omit or pass `null` for a standard voiceover with no presenter."},"voiceSpeed":{"type":["number","null"],"minimum":0.5,"maximum":2,"description":"Speech rate multiplier, between 0.5 (half speed) and 2 (double speed). Omit or pass `null` to keep each asset's current speed."}}},"RemixActionShuffleStockVisuals":{"type":"object","required":["type"],"description":"Replace every stock (library) visual in the project with a fresh alternative from the same search, replacing each in place. Runs asynchronously: each stock asset's original search is re-run, excluding the currently-shown result. If the project has no shuffleable stock visuals, the action is skipped and completes successfully without changing anything.","properties":{"type":{"type":"string","enum":["SHUFFLE_STOCK_VISUALS"]}}},"RemixActionGenerateMusic":{"type":"object","required":["type","prompt"],"description":"Generate a background music track from a text prompt and set it as the project's background music, replacing any existing track. Runs asynchronously.","properties":{"type":{"type":"string","enum":["GENERATE_MUSIC"]},"prompt":{"type":"string","description":"Describe the music to generate (e.g. \"upbeat corporate background music with a driving beat\")."}}},"RemixActionTranslateProject":{"type":"object","required":["type","languageCode"],"description":"Translate the whole project into another language: every piece of text (title, section names, on-screen text overlays, transcripts, and narration scripts) is translated, and — unless disabled — each AI voiceover is re-narrated in the new language. Runs asynchronously. Requires a Pro subscription. Retrieve the list of supported language codes from `GET /v1/resources/languages`.","properties":{"type":{"type":"string","enum":["TRANSLATE_PROJECT"]},"languageCode":{"type":"string","description":"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":{"type":["boolean","null"],"description":"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":{"type":["boolean","null"],"description":"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`."}}},"RemixAction":{"description":"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.","oneOf":[{"$ref":"#/components/schemas/RemixActionSetBackgroundMusic"},{"$ref":"#/components/schemas/RemixActionSetLogo"},{"$ref":"#/components/schemas/RemixActionEnableCaptions"},{"$ref":"#/components/schemas/RemixActionDisableCaptions"},{"$ref":"#/components/schemas/RemixActionAddTransitions"},{"$ref":"#/components/schemas/RemixActionResizeProject"},{"$ref":"#/components/schemas/RemixActionCleanUpTranscript"},{"$ref":"#/components/schemas/RemixActionConvertImagesToVideos"},{"$ref":"#/components/schemas/RemixActionRegenerateImages"},{"$ref":"#/components/schemas/RemixActionUpscaleAssets"},{"$ref":"#/components/schemas/RemixActionChangeNarrator"},{"$ref":"#/components/schemas/RemixActionShuffleStockVisuals"},{"$ref":"#/components/schemas/RemixActionGenerateMusic"},{"$ref":"#/components/schemas/RemixActionTranslateProject"}],"discriminator":{"propertyName":"type","mapping":{"SET_BACKGROUND_MUSIC":"#/components/schemas/RemixActionSetBackgroundMusic","SET_LOGO":"#/components/schemas/RemixActionSetLogo","ENABLE_CAPTIONS":"#/components/schemas/RemixActionEnableCaptions","DISABLE_CAPTIONS":"#/components/schemas/RemixActionDisableCaptions","ADD_TRANSITIONS":"#/components/schemas/RemixActionAddTransitions","RESIZE_PROJECT":"#/components/schemas/RemixActionResizeProject","CLEAN_UP_TRANSCRIPT":"#/components/schemas/RemixActionCleanUpTranscript","CONVERT_IMAGES_TO_VIDEOS":"#/components/schemas/RemixActionConvertImagesToVideos","REGENERATE_IMAGES":"#/components/schemas/RemixActionRegenerateImages","UPSCALE_ASSETS":"#/components/schemas/RemixActionUpscaleAssets","CHANGE_NARRATOR":"#/components/schemas/RemixActionChangeNarrator","SHUFFLE_STOCK_VISUALS":"#/components/schemas/RemixActionShuffleStockVisuals","GENERATE_MUSIC":"#/components/schemas/RemixActionGenerateMusic","TRANSLATE_PROJECT":"#/components/schemas/RemixActionTranslateProject"}}},"RemixProjectRequest":{"type":"object","required":["remixActions"],"properties":{"remixActions":{"type":"array","items":{"$ref":"#/components/schemas/RemixAction"},"description":"Ordered list of edits to apply. Each runs asynchronously as its own remix action. Must contain at least one action."},"saveAsNewProject":{"type":"boolean","description":"When true, the project is duplicated first and the edits are applied to the copy, leaving the original untouched. The response's `projectId` is the copy. Defaults to false (edits the project in place)."}}},"RemixProjectResponse":{"type":"object","description":"Returned when remix actions are accepted. Poll `GET /v1/projects/{projectId}/remix-actions` for status.","required":["projectId","projectUrl","remixActionIds"],"properties":{"projectId":{"type":"string","description":"Id of the edited project (e.g. `vg_proj_...`; the duplicate when `saveAsNewProject` was true)."},"projectUrl":{"type":"string","format":"uri","description":"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":{"type":"array","items":{"type":"string"},"description":"Opaque remix action ids (e.g. `vg_rmix_...`), one per requested action in order."}}},"RemixActionRun":{"type":"object","required":["remixActionId","type","status","projectId","projectUrl","progressPercentage","attemptIndex","error"],"properties":{"remixActionId":{"type":"string","description":"Opaque remix action id (e.g. `vg_rmix_...`)."},"type":{"$ref":"#/components/schemas/RemixActionType"},"status":{"$ref":"#/components/schemas/JobStatus"},"projectId":{"type":"string","description":"Id of the project this remix action edits (e.g. `vg_proj_...`)."},"projectUrl":{"type":"string","format":"uri","description":"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."},"progressPercentage":{"type":"number","minimum":0,"maximum":100,"description":"Completion progress for the current attempt (0-100). Always `100` when `status` is `succeeded`."},"attemptIndex":{"type":"integer","minimum":0,"description":"Zero-based index of the current or most recent execution attempt."},"error":{"description":"Error details. Always present as a field; `null` unless `status` is `failed`.","anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]}}},"ListRemixActionsResponse":{"type":"object","required":["remixActions","hasMore","nextCursor"],"properties":{"remixActions":{"type":"array","items":{"$ref":"#/components/schemas/RemixActionRun"},"description":"Remix actions for the project, most recent first."},"hasMore":{"type":"boolean","description":"When true, there are more remix actions available. Pass `nextCursor` as the `cursor` query param to fetch the next page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` when `hasMore` is false."}}},"ScriptToVideoRequest":{"type":"object","required":["script","visualStyle"],"properties":{"script":{"type":"string","description":"The narration script, used verbatim. This exact text is narrated and turned into a video — it is not rewritten or expanded."},"aspectRatio":{"$ref":"#/components/schemas/AspectRatio"},"visualStyle":{"$ref":"#/components/schemas/WorkflowVisualStyle"},"visualPacing":{"$ref":"#/components/schemas/VisualPacing"},"quality":{"$ref":"#/components/schemas/ModelQuality","description":"Image generation quality tier for AI-generated visuals. Optional; when omitted, your workspace's Default AI quality for images is used (change it at https://app.videogen.io/settings/account). Only applies when `visualStyle.type` is AI_IMAGE or ENTITY; STOCK pulls existing footage and is unaffected."},"language":{"type":"string","description":"Output language as a BCP-47 code (e.g. `en`, `es`, `fr`). Defaults to English."},"voiceId":{"type":["string","null"],"description":"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":{"type":"number","minimum":0.5,"maximum":2,"description":"Speech rate multiplier, between 0.5 (half speed) and 2 (double speed). Defaults to the voice's default speed."},"avatarPresenterId":{"type":["string","null"],"description":"Optional avatar presenter id from `GET /v1/resources/avatar-presenters` (e.g. `vg_pres_...`). When set, the narration is delivered by a talking-head presenter avatar. Pass your `voiceId` to that endpoint to list presenters sorted by best match for the voice. Omit for a standard voiceover with no presenter."},"featuredBRollFileIds":{"type":"array","items":{"type":"string"},"description":"Optional file ids of images or videos to feature as b-roll (e.g. `[\"vg_file_...\"]`). Upload files first via `POST /v1/files/upload`. Only image and video files are accepted."},"workflowAgentContext":{"type":"string","description":"Optional production notes for the AI that builds the video — visual direction that should not appear in the spoken narration (e.g. on-screen code or text to display, specific b-roll to feature, or scene-by-scene staging). Never spoken; keep the narration itself in `script`."},"scenes":{"type":"array","items":{"$ref":"#/components/schemas/SceneDescriptionRange"},"description":"Optional timed scene descriptions guiding what to show on screen during each absolute time range of the video. Ranges must be sorted by `startSeconds` and non-overlapping. Omit to let the workflow choose visuals automatically."},"remixActions":{"type":"array","items":{"$ref":"#/components/schemas/RemixAction"},"description":"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. Recommended for script-to-video: `ENABLE_CAPTIONS` to show and style captions, `CONVERT_IMAGES_TO_VIDEOS` to animate still images into clips, `ADD_TRANSITIONS` to stamp transitions between sections, and `SET_LOGO` to overlay a logo (this workflow has no native caption-style or logo fields). See the [Remix actions](/remix-actions) guide."},"isOutputTemporary":{"type":"boolean","default":false,"description":"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."}}},"TranscriptWord":{"type":"object","required":["startSeconds","endSeconds","word"],"description":"A single timed word of a transcript.","properties":{"startSeconds":{"type":"number","minimum":0,"description":"Start time of the word in seconds from the beginning of the audio."},"endSeconds":{"type":"number","description":"End time of the word in seconds from the beginning of the audio. Must be greater than `startSeconds`."},"word":{"type":"string","description":"The spoken word, used verbatim for narration timing and captions."}}},"Transcript":{"type":"object","required":["words"],"description":"A transcript of an audio file, as timed words in order.","properties":{"languageCode":{"type":["string","null"],"description":"Optional BCP-47 language code of the spoken audio (e.g. `en`, `es`). Used to tag the transcript's language; omit if unknown."},"words":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptWord"},"description":"The transcript words, sorted by `startSeconds` and non-overlapping. Must contain at least one word."}}},"SceneDescriptionRange":{"type":"object","required":["startSeconds","endSeconds","description"],"description":"A description of the visuals to show during an absolute time range of the finished video.","properties":{"startSeconds":{"type":"number","minimum":0,"description":"Start time of the range in seconds from the beginning of the video."},"endSeconds":{"type":"number","description":"End time of the range in seconds from the beginning of the video. Must be greater than `startSeconds`."},"description":{"type":"string","description":"What should be shown on screen during this range (e.g. the b-roll subject, on-screen text, or staging)."}}},"VoiceoverToVideoRequest":{"type":"object","required":["fileId","visualStyle"],"properties":{"fileId":{"type":"string","description":"Opaque file id of an uploaded voiceover audio file (e.g. `vg_file_...`). Upload the file first via `POST /v1/files/upload`. Attach a pre-computed transcript at upload time (via the `transcript` field on `POST /v1/files/upload`) to skip re-transcription."},"scenes":{"type":"array","items":{"$ref":"#/components/schemas/SceneDescriptionRange"},"description":"Optional timed scene descriptions guiding what to show on screen during each absolute time range of the video. Ranges must be sorted by `startSeconds` and non-overlapping. Omit to let the workflow choose visuals automatically."},"aspectRatio":{"$ref":"#/components/schemas/AspectRatio"},"visualStyle":{"$ref":"#/components/schemas/WorkflowVisualStyle"},"visualPacing":{"$ref":"#/components/schemas/VisualPacing"},"quality":{"$ref":"#/components/schemas/ModelQuality","description":"Image generation quality tier for AI-generated visuals. Optional; when omitted, your workspace's Default AI quality for images is used (change it at https://app.videogen.io/settings/account). Only applies when `visualStyle.type` is AI_IMAGE or ENTITY; STOCK pulls existing footage and is unaffected."},"language":{"type":"string","description":"Output language as a BCP-47 code (e.g. `en`, `es`, `fr`). Defaults to English."},"captionStyle":{"description":"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.","anyOf":[{"$ref":"#/components/schemas/WorkflowCaptionStyle"},{"type":"null"}]},"logoFileId":{"type":["string","null"],"description":"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."},"workflowAgentContext":{"type":"string","description":"Optional production notes for the AI that builds the video — visual direction for how to illustrate the voiceover (e.g. on-screen code or text to display, specific b-roll to feature, or scene-by-scene staging). Never spoken; does not change the uploaded voiceover audio or its transcript."},"remixActions":{"type":"array","items":{"$ref":"#/components/schemas/RemixAction"},"description":"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":{"type":"boolean","default":false,"description":"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."}}},"SlideshowToVideoRequest":{"type":"object","required":["fileId"],"properties":{"fileId":{"type":"string","description":"Opaque file id of an uploaded PDF or PowerPoint file (e.g. `vg_file_...`). Upload the file first via `POST /v1/files/upload`."},"slideScripts":{"type":"array","items":{"type":"string"},"description":"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":{"$ref":"#/components/schemas/AspectRatio"},"language":{"type":"string","description":"Output language as a BCP-47 code (e.g. `en`, `es`, `fr`). Defaults to English."},"voiceId":{"type":["string","null"],"description":"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":{"type":"number","minimum":0.5,"maximum":2,"description":"Speech rate multiplier, between 0.5 (half speed) and 2 (double speed). Defaults to the voice's default speed."},"avatarPresenterId":{"type":["string","null"],"description":"Optional avatar presenter id from `GET /v1/resources/avatar-presenters` (e.g. `vg_pres_...`). When set, the narration is delivered by a talking-head presenter avatar. Pass your `voiceId` to that endpoint to list presenters sorted by best match for the voice. Omit for a standard voiceover with no presenter."},"captionStyle":{"description":"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.","anyOf":[{"$ref":"#/components/schemas/WorkflowCaptionStyle"},{"type":"null"}]},"logoFileId":{"type":["string","null"],"description":"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":{"type":"array","items":{"$ref":"#/components/schemas/RemixAction"},"description":"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":{"type":"boolean","default":false,"description":"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."}}},"SceneGeneration":{"type":"object","description":"Optional look for a storyboard scene. Full builds always produce a video clip per scene (stills are intermediate first frames).","properties":{"aiStyle":{"type":["string","null"],"description":"A free-form description of the look, appended to the scene prompt (e.g. `loose watercolor illustration with visible brushstrokes`). See the AI styles reference for example descriptions of the app's default styles. No extra style is applied when omitted."},"type":{"type":"string","enum":["AI_IMAGE","AI_VIDEO"],"deprecated":true,"description":"Deprecated. Ignored. Full builds always produce video clips. Kept so older clients that still send `type` are accepted."}}},"GenerateStoryboardScene":{"type":"object","required":["prompt"],"description":"A single scene in the storyboard. Becomes one section in the final video.","properties":{"prompt":{"type":"string","description":"What to generate for this scene. May optionally embed entity mention tokens of the form `@[entity:<id>|ACTOR|<name>]` (or `PRODUCT` / `VISUAL_STYLE`) so the model can bind names in the prompt to labeled entity reference images. Prefer the structured `actorEntityIds` / `productEntityIds` / `visualStyleEntityId` fields as the primary attachment contract; mention tokens are optional sugar that generation also unions."},"title":{"type":"string","description":"Optional section name for this scene. Defaults to a numbered name."},"generation":{"description":"Optional per-scene look override. Falls back to the request-level `defaultGeneration` when omitted.","anyOf":[{"$ref":"#/components/schemas/SceneGeneration"},{"type":"null"}]},"durationSeconds":{"type":["integer","null"],"minimum":1,"maximum":15,"description":"Optional per-scene duration in seconds. Falls back to `defaultDurationSeconds` when omitted. Must be a whole number between 1 and 15 when the scene is animated to video."},"actorEntityIds":{"type":"array","items":{"type":"string"},"description":"Optional ids of ACTOR entities (e.g. `vg_enti_...`) to feature in this scene. Each entity's reference images are added so the same characters appear in the generated image or video. A scene can feature multiple actors."},"productEntityIds":{"type":"array","items":{"type":"string"},"description":"Optional ids of PRODUCT entities (e.g. `vg_enti_...`) to feature in this scene. Each entity's reference images are added so the same products appear in the generated image or video. A scene can feature multiple products."},"visualStyleEntityId":{"type":["string","null"],"description":"Optional id of a VISUAL_STYLE entity (e.g. `vg_enti_...`) whose reference images guide the look of this scene."},"voiceoverScript":{"type":["string","null"],"description":"Optional spoken script for this scene. When provided, the generative video clip speaks this exact text natively (lip-synced). Keep it short enough to speak in one clip (at most about 10 seconds). May optionally embed the same `@[entity:<id>|ACTOR|<name>]` (or `PRODUCT` / `VISUAL_STYLE`) mention tokens as `prompt` so named entities match attached reference identity. Prefer structured entity id fields for attachments; mention tokens are optional."}}},"StoryboardToVideoRequest":{"type":"object","required":["scenes"],"properties":{"scenes":{"type":"array","items":{"$ref":"#/components/schemas/GenerateStoryboardScene"},"description":"Ordered list of scenes. Each scene becomes one section in the final video, in this order. Must contain at least one scene."},"actorEntityIds":{"type":"array","items":{"type":"string"},"description":"Optional project-level ids of ACTOR entities (e.g. `vg_enti_...`) to register on the storyboard. These stay attached to the project even when no scene references them (e.g. after a scene is removed). Actors referenced by a scene are registered automatically."},"productEntityIds":{"type":"array","items":{"type":"string"},"description":"Optional project-level ids of PRODUCT entities (e.g. `vg_enti_...`) to register on the storyboard. These stay attached to the project even when no scene references them (e.g. after a scene is removed). Products referenced by a scene are registered automatically."},"defaultGeneration":{"description":"Default look applied to scenes that don't set their own `generation`. Defaults to no extra style.","anyOf":[{"$ref":"#/components/schemas/SceneGeneration"},{"type":"null"}]},"defaultDurationSeconds":{"type":"integer","minimum":1,"maximum":15,"description":"Default per-scene duration in seconds for scenes that don't set their own `durationSeconds`. Defaults to 5. Must be a whole number between 1 and 15."},"quality":{"$ref":"#/components/schemas/ModelQuality","description":"Generation quality tier for every scene. Optional; when omitted, your workspace's Default AI quality for video is used (change it at https://app.videogen.io/settings/account). `LOW` is not supported for storyboard video clips and is rejected."},"aspectRatio":{"$ref":"#/components/schemas/AspectRatio"},"workflowAgentContext":{"type":"string","description":"Optional storyboard-wide production notes for the AI that builds the video (e.g. recurring characters or props, a consistent setting, or overall staging guidance). Applies across every scene; per-scene direction goes in each scene's `prompt`."},"remixActions":{"type":"array","items":{"$ref":"#/components/schemas/RemixAction"},"description":"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. `ENABLE_CAPTIONS` shows and styles captions, `SET_BACKGROUND_MUSIC` sets a music track, `ADD_TRANSITIONS` stamps transitions between scenes, and `SET_LOGO` overlays a logo. See the [Remix actions](/remix-actions) guide."},"isOutputTemporary":{"type":"boolean","default":false,"description":"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."}}},"PromptToVideoClipRequest":{"type":"object","required":["prompt"],"description":"Creates a project from a text prompt and generates one short AI video clip. VideoGen generates an opening frame from the prompt (optionally guided by reference images), then animates that frame into a video inside an editable project. This workflow does not accept `remixActions`. For a standalone clip without a project, use `POST /v1/tools/generate-video-clip`. For longer narrated multi-scene videos, use `POST /v1/workflows/script-to-video`.","properties":{"prompt":{"type":"string","description":"Text prompt describing the video to generate (e.g. `A golden retriever running through a sunlit meadow in slow motion, cinematic`)."},"imageFileIds":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Optional ids of previously uploaded reference images (e.g. `vg_file_...`) that guide the opening frame. Upload files via `POST /v1/files/upload` first."},"durationSeconds":{"type":"integer","minimum":1,"maximum":15,"description":"Desired clip length in whole seconds (1 to 15). Defaults to 10."},"aspectRatio":{"$ref":"#/components/schemas/AspectRatio","description":"Aspect ratio for the generated video. Defaults to 16:9 when omitted."},"quality":{"$ref":"#/components/schemas/ModelQuality","description":"Video generation quality tier. Also used for the opening-frame image. Optional; when omitted, your workspace's Default AI quality for video is used (change it at https://app.videogen.io/settings/account). `LOW` is not supported for video and is rejected."},"isOutputTemporary":{"type":"boolean","default":false,"description":"When true, the generated OUTPUT files (the opening-frame image and the video clip) are created as temporary: guaranteed available for 24 hours, after which they may be archived and later deleted. 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."}}},"ContentOutlineToVideoRequest":{"type":"object","required":["outlineMarkdown"],"description":"Creates a project from a content outline and generates a full video from it. This is an experimental, fully-agentic workflow: an AI agent reads the outline (a Markdown brief describing the sections, beats, and key points the video should cover), plans the video, and builds it section by section — generating any narration, visuals, and media it needs. Provide a well-structured outline; the richer the brief, the closer the result. Returns immediately with a workflow run id; poll or subscribe to webhooks for completion.","properties":{"outlineMarkdown":{"type":"string","description":"The content outline as Markdown — a brief describing what the video should cover. Use headings, bullet lists, and short prose to lay out the sections, beats, and key facts in order (e.g. `# Solar panels explained\\n## How they work\\n- Photons knock electrons loose...`). The agent grounds the video in this brief."},"aspectRatio":{"$ref":"#/components/schemas/AspectRatio"},"inputFileIds":{"type":"array","items":{"type":"string"},"description":"Optional ids of previously uploaded image or video files (e.g. `vg_file_...`) to make available to the video. The agent decides whether and where to use them. Upload files via `POST /v1/files/upload` first."}}},"StartWorkflowRunResponse":{"type":"object","description":"Returned when a workflow run is accepted. Poll `GET /v1/workflows/runs/{workflowRunId}` or subscribe to webhooks for completion.","required":["workflowRunId","projectId","projectUrl","remixActionIds"],"properties":{"workflowRunId":{"type":"string","description":"Opaque workflow run id (e.g. `vg_work_...`)."},"projectId":{"type":"string","description":"Id of the project created for this workflow run (e.g. `vg_proj_...`)."},"projectUrl":{"type":"string","format":"uri","description":"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":{"type":"array","items":{"type":"string"},"description":"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`."}}},"WorkflowRun":{"type":"object","required":["workflowRunId","status","workflowType","projectId","projectUrl","progressPercentage","attemptIndex","error"],"properties":{"workflowRunId":{"type":"string","description":"Opaque workflow run id."},"status":{"$ref":"#/components/schemas/JobStatus"},"workflowType":{"$ref":"#/components/schemas/WorkflowType"},"progressPercentage":{"type":"number","minimum":0,"maximum":100,"description":"Completion progress for the current attempt (0-100). Always `100` when `status` is `succeeded`."},"attemptIndex":{"type":"integer","minimum":0,"description":"Zero-based index of the current or most recent execution attempt."},"projectId":{"type":"string","description":"Id of the project created for this workflow run (e.g. `vg_proj_...`)."},"projectUrl":{"type":"string","format":"uri","description":"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."},"error":{"description":"Error details. Always present as a field; `null` unless `status` is `failed`.","anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]}}},"WorkflowRunListResponse":{"type":"object","description":"Paginated list of API-started workflow runs, most recently created first.","required":["workflowRuns","hasMore","nextCursor"],"properties":{"workflowRuns":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRun"}},"hasMore":{"type":"boolean","description":"When true, there are more runs available. Pass `nextCursor` as the `cursor` query param to fetch the next page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` when `hasMore` is false."}}},"AssistantMessageWebhookPayload":{"type":"object","description":"Body POSTed to a registered webhook endpoint when an assistant message reaches a terminal state. Mirrors the `AssistantMessage` GET response.","required":["event","messageId","occurredAt","message"],"properties":{"event":{"$ref":"#/components/schemas/AssistantMessageWebhookEventName"},"messageId":{"type":"string","description":"Opaque assistant message id (e.g. `vg_mesg_...`)."},"occurredAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) when the message reached a terminal state."},"message":{"$ref":"#/components/schemas/AssistantMessage","description":"The full assistant message with its terminal `status`."}}},"WorkflowRunWebhookPayload":{"type":"object","description":"Body POSTed to a registered webhook endpoint when a workflow run reaches a terminal state.","required":["event","workflowRunId","occurredAt","workflowType","projectId","projectUrl"],"properties":{"event":{"$ref":"#/components/schemas/WorkflowRunWebhookEventName"},"workflowRunId":{"type":"string","description":"Opaque workflow run id matching the original request."},"occurredAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) at which VideoGen observed the terminal state."},"workflowType":{"$ref":"#/components/schemas/WorkflowType"},"projectId":{"type":"string","description":"Id of the project created for this workflow run (e.g. `vg_proj_...`)."},"projectUrl":{"type":"string","format":"uri","description":"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."},"error":{"description":"Error details. Present (non-null) only on `workflow_run.failed`; `null` otherwise.","anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]}}},"ProjectResponse":{"type":"object","description":"Simplified project metadata.","required":["projectId","assistantId","title","aspectRatio","status","createdAt","updatedAt","projectUrl"],"properties":{"projectId":{"type":"string","description":"Opaque project id (e.g. `vg_proj_...`)."},"assistantId":{"type":["string","null"],"description":"Opaque id of this project's assistant conversation (e.g. `vg_asst_...`). Use with the Assistant API to send follow-up messages or list the assistant's prior messages for this project. `null` for older projects created before assistant chats were attached at creation time."},"title":{"type":"string"},"aspectRatio":{"$ref":"#/components/schemas/AspectRatio"},"status":{"type":"string","description":"High-level project status.","enum":["generating","ready"]},"createdAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) when the project was created."},"updatedAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) when the project was last updated."},"projectUrl":{"type":"string","format":"uri","description":"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."}}},"ListProjectsResponse":{"type":"object","description":"Paginated list of projects, most recently updated first. By default only API-created projects are included; pass `includeUiProjects=true` on the request to also include dashboard-created projects.","required":["projects","hasMore","nextCursor"],"properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/ProjectResponse"}},"hasMore":{"type":"boolean","description":"When true, there are more projects available. Pass `nextCursor` as the `cursor` query param to fetch the next page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` when `hasMore` is false."}}},"ExportProjectQuality":{"type":"string","description":"Vertical resolution tier for the rendered MP4.","enum":["STANDARD","HIGH","FULL_HIGH","ULTRA_HIGH"]},"ExportProjectRequest":{"type":"object","properties":{"quality":{"$ref":"#/components/schemas/ExportProjectQuality"},"watermarkMode":{"$ref":"#/components/schemas/WatermarkMode"},"endScreenMode":{"$ref":"#/components/schemas/EndScreenMode"},"deliveryDestinations":{"type":"array","description":"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.","items":{"$ref":"#/components/schemas/ExportDeliveryDestination"}}}},"ExportDeliveryDestination":{"type":"object","required":["integrationConnectionId","type"],"properties":{"integrationConnectionId":{"type":"string","description":"Id of the connected integration that will receive this export."},"type":{"type":"string","description":"Where to deliver the export within the connected integration.","enum":["SLACK_CHANNEL","GOOGLE_DRIVE_FOLDER"]},"slackChannelId":{"type":["string","null"],"description":"Target channel id. Required when `type` is `SLACK_CHANNEL`."},"googleDriveFolderId":{"type":["string","null"],"description":"Target folder id. Required when `type` is `GOOGLE_DRIVE_FOLDER`."}}},"ExportProjectResponse":{"type":"object","required":["exportId"],"properties":{"exportId":{"type":"string","description":"Opaque export id (e.g. `vg_expo_...`). Poll `GET /v1/projects/{projectId}/exports/{exportId}` or subscribe to webhooks for completion."}}},"ProjectExport":{"type":"object","required":["exportId","projectId","status","progressPercentage","attemptIndex","downloadUrl","downloadUrlExpiresAt","thumbnailUrl","thumbnailUrlExpiresAt","exportFileId","file","error"],"properties":{"exportId":{"type":"string","description":"Opaque export id (e.g. `vg_expo_...`) matching the original request."},"projectId":{"type":"string","description":"Id of the exported project (e.g. `vg_proj_...`)."},"status":{"$ref":"#/components/schemas/JobStatus"},"progressPercentage":{"type":"number","minimum":0,"maximum":100,"description":"Completion progress for the current attempt (0-100). Always `100` when `status` is `succeeded`."},"attemptIndex":{"type":"integer","minimum":0,"description":"Zero-based index of the current or most recent export attempt."},"downloadUrl":{"type":["string","null"],"format":"uri","description":"Private signed MP4 download URL, valid for 24 hours from when it was signed. Always present as a field; `null` until `status` is `succeeded`. This endpoint automatically re-signs the URL when it is within an hour of expiring, so a fresh call to get the export always returns a URL valid long enough to use. See `downloadUrlExpiresAt` for the exact expiry. To fetch a fresh URL directly from the underlying file at any time, use `exportFileId` with the hydrate-file endpoint."},"downloadUrlExpiresAt":{"type":["integer","null"],"description":"Seconds since epoch (Unix timestamp) when `downloadUrl` expires. `null` while `downloadUrl` is null."},"thumbnailUrl":{"type":["string","null"],"format":"uri","description":"Private signed thumbnail URL, valid for 24 hours from when it was signed. Always present as a field; `null` until `status` is `succeeded` (and when no thumbnail is available). Re-signed automatically on the same terms as `downloadUrl`."},"thumbnailUrlExpiresAt":{"type":["integer","null"],"description":"Seconds since epoch (Unix timestamp) when `thumbnailUrl` expires. `null` while `thumbnailUrl` is null."},"exportFileId":{"type":["string","null"],"description":"File id (e.g. `vg_file_...`) of the exported MP4. Always present as a field; `null` until `status` is `succeeded`. Pass it to `POST /v1/files/{fileId}/hydrate` to fetch fresh signed URLs directly from the file at any time, which is useful once the 24-hour URLs above have expired."},"file":{"description":"Hydrated export file metadata with signed download URLs. Always present as a field; `null` until `status` is `succeeded`. Its signed URLs follow the same 24-hour validity and automatic re-signing as `downloadUrl`.","anyOf":[{"$ref":"#/components/schemas/FileInfo"},{"type":"null"}]},"error":{"description":"Error details. Always present as a field; `null` unless `status` is `failed`.","anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]}}},"ListProjectExportsResponse":{"type":"object","required":["exports","hasMore","nextCursor"],"properties":{"exports":{"type":"array","items":{"$ref":"#/components/schemas/ProjectExport"},"description":"Fully hydrated exports for this project, newest first. Each includes status, signed download/thumbnail URLs, and the embedded `file`."},"hasMore":{"type":"boolean","description":"When true, there are more exports available. Pass `nextCursor` as the `cursor` query param to fetch the next page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` when `hasMore` is false."}}},"TimelineInterchangeFormat":{"type":"string","description":"Editor interchange document format. `FCPXML` is Final Cut Pro (also imported by DaVinci Resolve and others). `PREMIERE_XML` is the Final Cut 7 `xmeml` XML that Adobe Premiere Pro imports natively. `OTIO` is OpenTimelineIO, the vendor-neutral format. `SRT` is a SubRip caption sidecar.","enum":["FCPXML","PREMIERE_XML","OTIO","SRT"]},"TimelineInterchangeMediaDelivery":{"type":"string","description":"How the interchange document references media. `REMOTE_URLS` produces a single document that links to signed media URLs. `BUNDLE` produces a zip containing the document plus every referenced media file, referenced by relative path, for durable offline relinking.","enum":["REMOTE_URLS","BUNDLE"]},"CreateTimelineInterchangeRequest":{"type":"object","properties":{"format":{"$ref":"#/components/schemas/TimelineInterchangeFormat"},"mediaDelivery":{"$ref":"#/components/schemas/TimelineInterchangeMediaDelivery"}}},"CreateTimelineInterchangeResponse":{"type":"object","required":["interchangeJobId"],"properties":{"interchangeJobId":{"type":"string","description":"Opaque timeline interchange job id (e.g. `vg_inte_...`). Poll `GET /v1/timeline-interchange/{interchangeJobId}` for completion."}}},"TimelineInterchange":{"type":"object","required":["interchangeJobId","projectId","format","mediaDelivery","status","progressPercentage","attemptIndex","downloadUrl","downloadUrlExpiresAt","interchangeFileId","file","error"],"properties":{"interchangeJobId":{"type":"string","description":"Opaque timeline interchange job id (e.g. `vg_inte_...`) matching the original request."},"projectId":{"type":"string","description":"Id of the source project (e.g. `vg_proj_...`)."},"format":{"$ref":"#/components/schemas/TimelineInterchangeFormat"},"mediaDelivery":{"$ref":"#/components/schemas/TimelineInterchangeMediaDelivery"},"status":{"$ref":"#/components/schemas/JobStatus"},"progressPercentage":{"type":"number","minimum":0,"maximum":100,"description":"Completion progress for the current attempt (0-100). Always `100` when `status` is `succeeded`."},"attemptIndex":{"type":"integer","minimum":0,"description":"Zero-based index of the current or most recent job attempt."},"downloadUrl":{"type":["string","null"],"format":"uri","description":"Private signed download URL for the interchange document (or the media bundle zip when `mediaDelivery` is `BUNDLE`), valid for 24 hours from when it was signed. Always present as a field; `null` until `status` is `succeeded`. This endpoint automatically re-signs the URL when it is within an hour of expiring. To fetch a fresh URL directly from the underlying file at any time, use `interchangeFileId` with the hydrate-file endpoint."},"downloadUrlExpiresAt":{"type":["integer","null"],"description":"Seconds since epoch (Unix timestamp) when `downloadUrl` expires. `null` while `downloadUrl` is null."},"interchangeFileId":{"type":["string","null"],"description":"File id (e.g. `vg_file_...`) of the interchange document or bundle zip. Always present as a field; `null` until `status` is `succeeded`. Pass it to `POST /v1/files/{fileId}/hydrate` to fetch fresh signed URLs directly from the file at any time."},"file":{"description":"Hydrated interchange file metadata with a signed download URL. Always present as a field; `null` until `status` is `succeeded`. Its signed URL follows the same 24-hour validity and automatic re-signing as `downloadUrl`.","anyOf":[{"$ref":"#/components/schemas/FileInfo"},{"type":"null"}]},"error":{"description":"Error details. Always present as a field; `null` unless `status` is `failed`.","anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]}}},"CreateWebhookEndpointRequest":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL that will receive webhook POST requests."},"description":{"type":["string","null"]},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventName"},"description":"Webhook event names to subscribe to. Must contain at least one event."}}},"ToolExecutionWebhookPayload":{"type":"object","description":"Delivered to your webhook endpoint when a tool execution reaches a terminal state. The shape mirrors the `ExecutedTool` response with the addition of `event` and `occurredAt`.","required":["event","toolExecutionId","occurredAt","toolType"],"properties":{"event":{"$ref":"#/components/schemas/ToolExecutionWebhookEventName"},"toolExecutionId":{"type":"string","description":"Execution id matching the original request."},"occurredAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) when the execution reached a terminal state."},"toolType":{"type":"string","description":"Tool name (e.g. `GENERATE_IMAGE`, `TEXT_TO_SPEECH`)."},"results":{"type":"array","description":"One entry per generated result, each with a hydrated `file`. Present only on `tool_execution.succeeded`.","items":{"$ref":"#/components/schemas/ToolSuccessResult"}},"error":{"description":"Present only on `tool_execution.failed`.","anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]}}},"FileWebhookPayload":{"type":"object","description":"Delivered to your webhook endpoint during the file lifecycle (upload, analysis, playback, and download readiness). Only sent for files uploaded via the API. The payload always includes a hydrated `file` object with the latest state.","required":["event","fileId","occurredAt","file"],"properties":{"event":{"$ref":"#/components/schemas/FileWebhookEventName"},"fileId":{"type":"string","description":"File id (e.g. `vg_file_...`)."},"occurredAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) when the event occurred."},"file":{"$ref":"#/components/schemas/FileInfo","description":"Hydrated file object with the latest state at the time of the event."},"error":{"description":"Error details. Present only on `file.upload.failed` and `file.analysis_failed`.","anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]}}},"WebhookEndpoint":{"type":"object","required":["endpointId","url","events","createdAt"],"properties":{"endpointId":{"type":"string","description":"Webhook endpoint id (e.g. `ep_...`)."},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventName"}},"description":{"type":["string","null"]},"createdAt":{"type":"integer","description":"Seconds since epoch (Unix timestamp) when the endpoint was created."},"signingSecret":{"type":"string","description":"HMAC secret for verifying [Standard Webhooks](https://www.standardwebhooks.com/) signatures. Only returned once on create; store it securely."},"signingSecretLast4":{"type":"string","description":"Last four characters of the signing secret, for display purposes."}}},"WebhookEndpointListResponse":{"type":"object","required":["endpoints","hasMore","nextCursor"],"properties":{"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"hasMore":{"type":"boolean","description":"When true, there are more endpoints available. Pass `nextCursor` as the `cursor` query param to fetch the next page."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor to fetch the next page. `null` when `hasMore` is false."}}}}}}