VideoGen API

Install

pip install videogen

Create a client

from videogen import VideoGen
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

from videogen import AsyncVideoGen
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:

from videogen import VideoGen
vg = VideoGen(api_key="sk_videogen_live_...")
run = vg.workflows.script_to_video_and_wait(
    script=(
        "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."
    ),
    visual_style={
        "type": "AI_IMAGE",
        "ai_style": "loose watercolor illustration with visible brushstrokes and soft color bleeds",
    },
    quality="HIGH",
    remix_actions=[
        {"type": "ENABLE_CAPTIONS"},
        {
            "type": "CONVERT_IMAGES_TO_VIDEOS",
            "motion_prompt": "slow cinematic push-in",
            "mute_output_videos": True,
            "quality": "HIGH",
        },
    ],
)
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):

from videogen import AsyncVideoGen
vg = AsyncVideoGen(api_key="sk_videogen_live_...")
run = await vg.workflows.script_to_video_and_wait(
    script="Staying hydrated keeps your body and mind running at their best.",
    visual_style={
        "type": "AI_IMAGE",
        "ai_style": "loose watercolor illustration with visible brushstrokes and soft color bleeds",
    },
    quality="HIGH",
    remix_actions=[
        {"type": "ENABLE_CAPTIONS"},
        {
            "type": "CONVERT_IMAGES_TO_VIDEOS",
            "motion_prompt": "slow cinematic push-in",
            "mute_output_videos": True,
            "quality": "HIGH",
        },
    ],
)

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:

from videogen import VideoGen, create_public_preview
vg = VideoGen(api_key="sk_videogen_live_...")
execution = vg.tools.generate_image_and_wait(
    prompt="A sunset over a calm ocean, cinematic lighting",
)
print(execution["status"])  # "succeeded"
file_id = execution["results"][0]["file_id"]
preview = create_public_preview(vg, file_id)

Upload a file

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

Download a file

from videogen import VideoGen, download_file
vg = VideoGen(api_key="sk_videogen_live_...")
download_file(vg, "vg_file_...", output_path="output.mp4")

Verify a webhook

from videogen import verify_webhook_signature
payload = verify_webhook_signature(
    raw_body=raw_body,
    headers=headers,
    secret=signing_secret,
)
if payload["event"] == "tool_execution.succeeded":
    print(payload["results"])

Python