tavus-engineering Tavus Video Generation Skill
Generate personalized AI videos with replicas speaking your script.
Quick Start
curl -X POST https://tavusapi.com/v2/videos \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"replica_id": "rfe12d8b9597",
"script": "Hey there! Welcome to our product demo."
}'
Response:
{
"video_id": "1e30440cf9",
"status": "queued"
}
Full API Options
curl -X POST https://tavusapi.com/v2/videos \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"replica_id": "rfe12d8b9597",
"script": "Your script text here",
"video_name": "Product Demo v1",
"callback_url": "https://your-webhook.com/video-ready",
"background_url": "https://example.com/landing-page",
"background_source_url": "https://s3.../background.mp4",
"watermark_url": "https://s3.../logo.png",
"fast": false,
"transparent_background": false
}'
Parameters
| Param | Description |
|---|---|
replica_id |
Required. Stock or custom replica ID |
script |
Text for replica to speak (use this OR audio_url) |
audio_url |
Pre-recorded audio (.wav/.mp3) for replica to lip-sync |
video_name |
Display name |
callback_url |
Webhook for completion/error |
background_url |
Website URL to record as background |
background_source_url |
Video file URL for background |
watermark_url |
PNG/JPEG logo overlay |
fast |
Quick render (disables some features) |
transparent_background |
WebM with alpha (requires fast: true) |
Using Audio Instead of Script
{
"replica_id": "rfe12d8b9597",
"audio_url": "https://s3.../narration.mp3"
}
Supported formats: .wav, .mp3
Background Options
Website Background
Records a scrolling website as the background:
{
"background_url": "https://example.com/landing-page"
}
Video Background
Uses a video file:
{
"background_source_url": "https://s3.../promo-bg.mp4"
}
Transparent Background
For compositing in video editors:
{
"fast": true,
"transparent_background": true
}
Outputs .webm with alpha channel.
Check Video Status
curl https://tavusapi.com/v2/videos/{video_id} \
-H "x-api-key: YOUR_API_KEY"
Status values: queued, generating, ready, error, deleted
When ready:
{
"status": "ready",
"hosted_url": "https://videos.tavus.io/video/xxx",
"download_url": "https://stream.mux.com/.../high.mp4",
"stream_url": "https://stream.mux.com/xxx.m3u8"
}
Webhook Callback
On completion:
{
"video_id": "1e30440cf9",
"status": "ready",
"hosted_url": "https://videos.tavus.io/video/1e30440cf9",
"download_url": "...",
"stream_url": "..."
}
On error:
{
"video_id": "xxx",
"status": "error",
"status_details": "Error message here"
}
Scripting Best Practices
- Keep under 5 minutes for quality/engagement
- Write conversationally (speak out loud to test)
- Use punctuation to indicate pauses
- Clear structure: intro → body → CTA
- Break long content into multiple videos
List & Delete Videos
# List all videos
curl https://tavusapi.com/v2/videos -H "x-api-key: YOUR_API_KEY"
# Delete video
curl -X DELETE https://tavusapi.com/v2/videos/{video_id} \
-H "x-api-key: YOUR_API_KEY"