VideoGen API

Install

$ pip install videogen

Create a client

1 from videogen import VideoGenApi
2 
3 client = VideoGenApi(token="YOUR_API_KEY")

The client reads from the VIDEOGEN_API_KEY environment variable when no token is provided.

Async client

1 from videogen import AsyncVideoGenApi
2 
3 client = AsyncVideoGenApi(token="YOUR_API_KEY")

Generate a video from a script

Workflows turn a script into a finished video asynchronously. Use poll_workflow_run to wait for the run:

1 from videogen import VideoGenApi, poll_workflow_run
2 
3 client = VideoGenApi(token="YOUR_API_KEY")
4 
5 response = client.workflows.add_visuals_narrations_and_captions_to_script(
6     script=(
7         "Staying hydrated keeps your body and mind running at their best. "
8         "Drinking enough water boosts your energy, focus, and mood. "
9         "Keep a water bottle nearby and sip throughout the day."
10     ),
11     visual_style={
12         "type": "AI_IMAGE",
13         "ai_style": "loose watercolor illustration with visible brushstrokes and soft color bleeds",
14     },
15     quality="HIGH",
16     remix_actions=[
17         {"type": "ENABLE_CAPTIONS"},
18         {"type": "SET_BACKGROUND_MUSIC", "file_id": "vg_file_...", "volume": 0.25},
19     ],
20 )
21 
22 run = poll_workflow_run(client, response.workflow_run_id)
23 print(run.status, run.project_url)  # "succeeded", project URL

For the async client, use async_poll_workflow_run:

1 from videogen import AsyncVideoGenApi, async_poll_workflow_run
2 
3 client = AsyncVideoGenApi(token="YOUR_API_KEY")
4 
5 response = await client.workflows.add_visuals_narrations_and_captions_to_script(
6     script="Staying hydrated keeps your body and mind running at their best.",
7     visual_style={
8         "type": "AI_IMAGE",
9         "ai_style": "loose watercolor illustration with visible brushstrokes and soft color bleeds",
10     },
11     quality="HIGH",
12     remix_actions=[
13         {"type": "ENABLE_CAPTIONS"},
14         {"type": "SET_BACKGROUND_MUSIC", "file_id": "vg_file_...", "volume": 0.25},
15     ],
16 )
17 
18 run = await async_poll_workflow_run(client, response.workflow_run_id)

Options

Option	Type	Default	Description
`poll_interval_ms`	`int`	`1500`	Milliseconds between polls.
`timeout_ms`	`int`	`3600000`	Maximum wait time before raising.
`cancel_event`	`threading.Event`	—	Cancel sync polling early (`PollCancelledError`).

For the async client, pass asyncio.Event as cancel_event to async_poll_workflow_run, async_poll_executed_tool, async_poll_project_export, and async_poll_public_preview.

Run a standalone tool

All tool endpoints are asynchronous. Use poll_executed_tool to wait for the result:

1 from videogen import VideoGenApi, poll_executed_tool
2 
3 client = VideoGenApi(token="YOUR_API_KEY")
4 
5 response = client.tools.generate_video_clip(
6     prompt="A sunset over a calm ocean, cinematic lighting",
7 )
8 
9 result = poll_executed_tool(client, response.tool_execution_id)
10 print(result.status)   # "succeeded"
11 print(result.results)  # generated files

Upload a file

1 from videogen import VideoGenApi, upload_file
2 
3 client = VideoGenApi(token="YOUR_API_KEY")
4 
5 with open("input.mp4", "rb") as f:
6     file = upload_file(client, f.read(), display_name="input.mp4", type="VIDEO")
7 
8 print(file.file_id)  # "vg_file_..."

Download a file

1 from videogen import VideoGenApi, download_file
2 
3 client = VideoGenApi(token="YOUR_API_KEY")
4 
5 download_file(client, "vg_file_...", output_path="output.mp4")

Verify a webhook

1 from videogen import verify_webhook_signature
2 
3 payload = verify_webhook_signature(raw_body, headers, signing_secret)
4 
5 if payload["event"] == "tool_execution.succeeded":
6     print(payload["results"])

Python