Polling

Poll for tool executions, workflow runs, and project exports.

The VideoGen API exposes poll endpoints for each async surface. Both SDKs ship helpers that loop until a terminal status is reached.

Workflow runs

After POST /v1/workflows/*, poll GET /v1/workflows/runs/{workflowRunId} until status is succeeded, failed, or cancelled, or use pollWorkflowRun / poll_workflow_run:

1import { VideoGenClient, pollWorkflowRun } from "@videogen/sdk";
2
3const client = new VideoGenClient({ token: process.env.VIDEOGEN_API_KEY });
4
5const { workflowRunId } = await client.workflows.scriptToVideo({
6 script:
7 "Staying hydrated keeps your body and mind running at their best. Drinking enough water boosts your energy, focus, and mood. Keep a water bottle nearby and sip throughout the day.",
8 visualStyle: {
9 type: "AI_IMAGE",
10 aiStyle: "loose watercolor illustration with visible brushstrokes and soft color bleeds",
11 },
12 quality: "HIGH",
13 remixActions: [
14 { type: "ENABLE_CAPTIONS" },
15 { type: "SET_BACKGROUND_MUSIC", fileId: "vg_file_...", volume: 0.25 },
16 ],
17});
18
19const run = await pollWorkflowRun(client, workflowRunId);
20console.log(run.status, run.projectUrl);

Tool executions

Poll GET /v1/tools/executions/{toolExecutionId} until the status is succeeded, failed, or cancelled, or use pollExecutedTool / poll_executed_tool:

1import { pollExecutedTool } from "@videogen/sdk";
2
3const { toolExecutionId } = await client.tools.generateImage({
4 prompt: "A mountain at sunrise",
5});
6
7const response = await pollExecutedTool(client, toolExecutionId);
8
9if (response.status === "succeeded") {
10 console.log("File id:", response.results[0].fileId);
11}

The helper polls every 1.5 seconds (configurable via pollIntervalMs / poll_interval_ms) and returns once a terminal status is reached. Under the hood it’s a simple loop:

1async function pollExecutedTool(
2 client: Pick<VideoGenApiClient, "tools">,
3 toolExecutionId: string,
4 options?: { pollIntervalMs?: number; signal?: AbortSignal },
5): Promise<ExecutedTool> {
6 const pollIntervalMs = options?.pollIntervalMs ?? 1500;
7
8 while (true) {
9 options?.signal?.throwIfAborted();
10 const executed = await client.tools.getToolExecutionInfo({ toolExecutionId });
11
12 if (["succeeded", "failed", "cancelled"].includes(executed.status)) {
13 return executed;
14 }
15
16 await new Promise((r) => setTimeout(r, pollIntervalMs));
17 }
18}

When to use polling: good for scripts, CLI tools, or any situation where you can block and wait. For production systems, consider using webhooks instead.

Public preview

After POST /v1/files/{fileId}/enable-public-preview, poll GET /v1/files/{fileId} until staticPublicPreviewSource.url is ready (and publicPlaybackId for video/audio embeds), or use pollPublicPreview / poll_public_preview:

pollPublicPreview throws if isPublicPreviewEnabled is false — call enablePublicPreview first. Use waitForEmbedPlaybackId: false (or wait_for_embed_playback_id=False) when you only need the permanent direct URL (e.g. images).

Project exports

After POST /v1/projects/{projectId}/export, poll GET /v1/projects/{projectId}/exports/{exportId} until status is succeeded or failed, or use pollProjectExport / poll_project_export.

Each response includes progressPercentage (0-100) for the current attempt, so you can render a live progress bar while the export runs. It is always 100 once status is succeeded.