VideoGen API

Install

$ pip install videogen

Create a client

1 from videogen import VideoGen
2 
3 vg = VideoGen(api_key="sk_videogen_live_...")

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

Async client

1 from videogen import AsyncVideoGen
2 
3 vg = AsyncVideoGen(api_key="sk_videogen_live_...")

Generate a video from a script

Workflows turn a script into a finished video asynchronously. Prefer script_to_video_and_wait when you can block:

1 from videogen import VideoGen
2 
3 vg = VideoGen(api_key="sk_videogen_live_...")
4 
5 run = vg.workflows.script_to_video_and_wait(
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         {
19             "type": "CONVERT_IMAGES_TO_VIDEOS",
20             "motion_prompt": "slow cinematic push-in",
21             "mute_output_videos": True,
22             "quality": "HIGH",
23         },
24     ],
25 )
26 
27 print(run["status"], run.get("project_id"))

Use project_id for export, remix, and other API calls. project_url (also on the response) is optional: a link to open the project in the VideoGen editor for manual review (team members and project collaborators only).

Request kwargs use snake_case (and nested dict keys); the client serializes body/query keys to camelCase for the API. Responses are plain dicts with snake_case keys.

For start-then-poll yourself, call script_to_video then poll_workflow_run(vg, workflow_run_id). For the async client, use script_to_video_and_wait on AsyncVideoGen (or async_poll_workflow_run):

1 from videogen import AsyncVideoGen
2 
3 vg = AsyncVideoGen(api_key="sk_videogen_live_...")
4 
5 run = await vg.workflows.script_to_video_and_wait(
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         {
15             "type": "CONVERT_IMAGES_TO_VIDEOS",
16             "motion_prompt": "slow cinematic push-in",
17             "mute_output_videos": True,
18             "quality": "HIGH",
19         },
20     ],
21 )

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`	(none)	Cancel sync polling early (`PollCancelledError`).

For the async client, pass asyncio.Event as cancel_event to *_and_wait methods and async poll helpers (async_poll_workflow_run, async_poll_executed_tool, async_poll_project_export, async_poll_public_preview).

Run a standalone tool

All tool endpoints are asynchronous. Prefer generate_image_and_wait (and the other tool *_and_wait methods). Use create_public_preview when you need a shareable preview URL:

1 from videogen import VideoGen, create_public_preview
2 
3 vg = VideoGen(api_key="sk_videogen_live_...")
4 
5 execution = vg.tools.generate_image_and_wait(
6     prompt="A sunset over a calm ocean, cinematic lighting",
7 )
8 
9 print(execution["status"])  # "succeeded"
10 file_id = execution["results"][0]["file_id"]
11 preview = create_public_preview(vg, file_id)

Upload a file

1 from videogen import VideoGen, upload_file
2 
3 vg = VideoGen(api_key="sk_videogen_live_...")
4 
5 with open("input.mp4", "rb") as f:
6     file = upload_file(vg, f, display_name="input.mp4", type="VIDEO")
7 
8 print(file["file_id"])  # "vg_file_..."

Download a file

1 from videogen import VideoGen, download_file
2 
3 vg = VideoGen(api_key="sk_videogen_live_...")
4 
5 download_file(vg, "vg_file_...", output_path="output.mp4")

Verify a webhook

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

Python