Reference

`videos`

Base path: /api/v1/videos

The videos module covers video asset CRUD, integration with HeyGen-style avatar generation, and stitching for webinar replays and short-form social clips. It tracks the source script, generated avatar render, B-roll overlays, and final stitched output. Resources include video assets, render jobs, avatar profiles, and clip variants. Schemas live in app/modules/videos/schemas.py.

What you can do with the videos API

Generate a talking-head video from a script and avatar profile
Upload an existing video for use in webinar replays
Stitch a webinar (slides, host avatar, optional B-roll) into a single MP4
Cut a long video into short-form social clips
Track render-job progress through the worker pipeline

Common operations

List videos in your workspace by status (rendering, ready, failed)
Get a single video with preview, download URL, and duration
Trigger a render job from a script
Poll a render job until it completes
Delete a video and its derived clips
Re-render with a different avatar voice or aspect ratio

Authentication & scoping

Workspace-scoped via API key in the Authorization: Bearer tnx_... header. Render jobs are billed against workspace credits.

Pagination & filtering

List endpoints paginate cursor-style with filters by status, source (uploaded vs generated), and date. See Pagination.

How video rendering works end to end

You submit a script and avatar profile. The worker hits the avatar provider, polls until the render lands, downloads the MP4, runs optional stitching with slides and B-roll, and stores the final output in S3. The resulting asset is referenced by ID from the webinars and marketing modules.

MCP equivalents

MCP prompt

generate_avatar_video({ script, avatar_id, aspect_ratio: "16:9" })