Handling async tasks

Tool and workflow requests return immediately. You choose how to get the result.

End-to-end video workflows and standalone media generation (images, video, audio) take anywhere from a few seconds to several minutes. Rather than holding a connection open for that entire time, the VideoGen API returns a response instantly with a run or execution id. You then choose how to receive the result: poll for it, or let us push it to you via a webhook.

Workflow runs

POST /v1/workflows/script-to-video  →  { "workflowRunId": "vg_work_...", "projectId": "vg_proj_...", "projectUrl": "..." }

Every POST /v1/workflows/* endpoint returns 202 Accepted with { workflowRunId, projectId, projectUrl }. The run progresses through these statuses:

Status	Meaning
`pending`	Queued, waiting to start
`running`	Generation in progress
`succeeded`	Done, the video is ready
`failed`	Something went wrong
`cancelled`	Cancelled by you

succeeded, failed, and cancelled are terminal statuses. The run won’t change after reaching one of these. Poll GET /v1/workflows/runs/{workflowRunId} until terminal, or subscribe to workflow_run.* webhooks.

See Workflows for available pipelines and SDK helpers (pollWorkflowRun / poll_workflow_run).

Cancel an in-progress workflow run:

$ POST /v1/workflows/runs/{workflowRunId}/cancel

Tool executions

POST /v1/tools/generate-image  →  { "toolExecutionId": "vg_tool_..." }

Standalone media tools work the same way. Every POST /v1/tools/... endpoint returns 202 Accepted with a toolExecutionId and the same set of statuses (pending, running, succeeded, failed, cancelled).

Cancel an in-progress tool execution:

$ POST /v1/tools/executions/{toolExecutionId}/cancel

Getting the result

There are two ways to know when async work finishes:

Method	Best for
Polling	Scripts, CLI tools, or any situation where you can block and wait.
Webhooks	Production backends, serverless functions, and anywhere you don’t want to hold a connection open.