VideoGen Python SDK

Official Python client for the VideoGen API.

Package: videogen (PyPI). Generate full videos from scripts, voiceovers, or slideshows, run media tools, manage files and projects, chat with the AI assistant, and verify webhooks.

Install

pip install videogen

Default base URL: https://api.videogen.io.

Quick start

import os
from videogen import VideoGen

vg = VideoGen(api_key=os.environ["VIDEOGEN_API_KEY"])

me = vg.account.get_me()
print(me["email"])

run = vg.workflows.script_to_video_and_wait(
    script="Stay hydrated for better focus and energy.",
    visual_style={
        "type": "AI_IMAGE",
        "ai_style": "Loose watercolor illustration, visible brushstrokes, soft color bleeds, paper texture, muted palette. A clear uncluttered subject centered in the frame, occupying only the middle half of the image, with generous empty margins on all four sides, no background clutter.",
    },
    quality="HIGH",
    auto_export=True,
    remix_actions=[
        {"type": "ENABLE_CAPTIONS"},
        {
            "type": "CONVERT_IMAGES_TO_VIDEOS",
            "motion_prompt": "slow cinematic push-in",
            "mute_output_videos": True,
            "quality": "HIGH",
        },
    ],
)
print(run.download_url)

Omit api_key to read VIDEOGEN_API_KEY from the environment.

Async client

import os
from videogen import AsyncVideoGen

vg = AsyncVideoGen(api_key=os.environ["VIDEOGEN_API_KEY"])

run = await vg.workflows.script_to_video_and_wait(
    script="Stay hydrated for better focus and energy.",
    visual_style={
        "type": "AI_IMAGE",
        "ai_style": "Loose watercolor illustration, visible brushstrokes, soft color bleeds, paper texture, muted palette. A clear uncluttered subject centered in the frame, occupying only the middle half of the image, with generous empty margins on all four sides, no background clutter.",
    },
    quality="HIGH",
    auto_export=True,
    remix_actions=[
        {"type": "ENABLE_CAPTIONS"},
        {
            "type": "CONVERT_IMAGES_TO_VIDEOS",
            "motion_prompt": "slow cinematic push-in",
            "mute_output_videos": True,
            "quality": "HIGH",
        },
    ],
)
print(run.download_url)

What you can do

Prefer *_and_wait (or the matching poll_* / async_poll_* helper) for anything asynchronous. Thin REST methods match OpenAPI operationIds (snake_case).

Naming and JSON

• Methods: snake_case (script_to_video, get_tool_execution_info).
• Requests: pass snake_case kwargs (and nested dict keys). The client serializes body/query keys to camelCase for the wire.
• Responses: JSON objects are converted recursively to snake_case keys (tool_execution_id, workflow_run_id, has_more).

Workflows

Script to video (above) is the usual path. Prompt to video clip builds a single clip from a prompt:

import os
from videogen import VideoGen

vg = VideoGen(api_key=os.environ["VIDEOGEN_API_KEY"])

run = vg.workflows.prompt_to_video_clip_and_wait(
    prompt="A glass of water catching morning light on a kitchen counter, slow push-in",
    quality="HIGH",
)
print(run.download_url)

Other workflow starters: voiceover_to_video_and_wait (uploaded audio file_id), slideshow_to_video_and_wait (deck file_id), video_to_video_and_wait (restyles an uploaded video_file_id or a public video_url from a prompt).

Tools

import os
from videogen import VideoGen

vg = VideoGen(api_key=os.environ["VIDEOGEN_API_KEY"])

execution = vg.tools.generate_image_and_wait(
    prompt="A sunset over a calm ocean, cinematic lighting",
    quality="HIGH",
)

results = execution.get("results") or []
file_id = results[0]["file_id"] if results else None
if file_id is None:
    raise RuntimeError("Expected a generated file id")

preview = vg.create_public_preview(file_id)
print(execution["status"], preview)

The same *_and_wait pattern exists for video clips, motion graphics, TTS, music, sound effects, avatar, upscale, background removal, and more under vg.tools.

For avatar video, call generate_avatar_and_wait with audio_file_id and an ACTOR entity as actor_entity_id. You may set avatar_quality to LOW, STANDARD, HIGH, or MAX. Script-to-video, voiceover-to-video, slideshow-to-video, and CHANGE_NARRATOR accept the same optional actor fields.

Files

import os
from videogen import VideoGen

vg = VideoGen(api_key=os.environ["VIDEOGEN_API_KEY"])

with open("input.mp4", "rb") as f:
    uploaded = vg.upload_file(f, display_name="input.mp4", type="VIDEO")

print(uploaded["file_id"])

vg.download_file(uploaded["file_id"], output_path="output.mp4")

Projects

Export a finished workflow project, or apply remix actions later:

import os
from videogen import VideoGen

vg = VideoGen(api_key=os.environ["VIDEOGEN_API_KEY"])

project_id = "vg_proj_..."

exported = vg.projects.export_and_wait(project_id=project_id, quality="HIGH")
print(exported["status"], exported.get("export_file_id"))

remix = vg.projects.remix_and_wait(
    project_id=project_id,
    remix_actions=[
        {"type": "ENABLE_CAPTIONS"},
        {"type": "ADD_TRANSITIONS"},
    ],
)
print(remix)

Assistant

import os
from videogen import VideoGen

vg = VideoGen(api_key=os.environ["VIDEOGEN_API_KEY"])

started = vg.assistant.start_assistant_chat(
    message="Draft a 20-second script about morning hydration.",
)
message = vg.poll_assistant_message(started["message_id"])

print(message["status"], started.get("assistant_id"), started.get("project_id"))

Or use start_assistant_chat_and_wait when you only need the terminal message. Continue with send_assistant_message_and_wait / act_on_assistant_action_and_wait on the same assistant_id.

Entities

Reusable actors, products, and visual styles for consistent generation:

import os
from videogen import VideoGen

vg = VideoGen(api_key=os.environ["VIDEOGEN_API_KEY"])

entity = vg.entities.create_entity(
    entity_type="ACTOR",
    name="Alex",
    description="Friendly narrator in casual clothes",
)
print(entity["entity_id"])

Attach reference images with add_entity_reference, then pass entity ids into workflows.

Text

import os
from videogen import VideoGen

vg = VideoGen(api_key=os.environ["VIDEOGEN_API_KEY"])

result = vg.text.generate_text(
    prompt="Write a one-sentence hook for a hydration tip video.",
)
print(result["text"])

Webhooks

import os
from videogen import verify_webhook_signature

event = verify_webhook_signature(
    raw_body="...",  # raw request body string
    headers={
        "webhook-id": "...",
        "webhook-timestamp": "...",
        "webhook-signature": "...",
    },
    secret=os.environ.get("VIDEOGEN_WEBHOOK_SECRET", ""),
)
print(event)

Register endpoints with vg.webhooks.create_webhook_endpoint. Signatures follow the Standard Webhooks scheme.

Helpers

Exported as module functions and bound on the client:

Workflow and tool pollers, including their *_and_wait wrappers, return awaiting_approval unchanged without throwing, even with the default throw_on_failure=True. This status means the result needs approval; it does not mean the operation succeeded. Check status before using the result as a completed operation.

Cancellation: pass cancel_event=threading.Event() (sync) or asyncio.Event() (async) to poll helpers and thin request methods. Setting the event raises PollCancelledError.

Errors

VideoGenError exposes status, body, and request_id (from x-request-id when present).

Docs

• API documentation
• PyPI: videogen
• GitHub