Twin.Actor API Documentation

Build AI-powered video applications with our comprehensive API. Generate cinematic videos, clone voices, and create talking-head avatars programmatically.

Quickstart

Get up and running in 5 minutes

Authentication

Learn about API keys and tokens

API Reference

Explore all available endpoints

Webhooks

Real-time event notifications

What is Twin.Actor?

Twin.Actor is an AI-powered video generation platform that enables you to create professional-quality videos programmatically. Our API provides access to:

Scene Projects - Multi-scene cinematic videos with AI-generated imagery and narration
Avatar Projects - Talking-head videos with voice-controlled lip-sync
Voice Cloning - Clone any voice from audio samples using multiple providers
GMB Images - Generate marketing images for Google My Business listings

Base URL

All API requests should be made to:

text

https://api.twin.actor/api/v1

For local development:

text

http://localhost:8000/api/v1

Quick Example

Here's a simple example to create a scene project:

cURL

curl -X POST https://api.twin.actor/api/v1/scene-projects/propose \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_idea": "A tech startup journey from garage to IPO",
    "num_scenes": 5,
    "narrator_voice_id": "voice_abc123"
  }'

Need help?

Check out our Quickstart Guide for a complete walkthrough of creating your first video.

Core Concepts

Scene Projects

Multi-scene cinematic videos. Each scene is 10 seconds with AI-generated imagery, motion, and optional narration. Perfect for marketing videos, product launches, and storytelling.

Voice Cloning

Clone voices from audio samples using ElevenLabs, Hume AI, or Chatterbox. Use cloned voices for narration in your videos or as standalone TTS.

Async Operations

Video generation is asynchronous. Start a job, receive a job ID, then poll for status or configure webhooks for real-time notifications when your video is ready.

Credits System

Twin.Actor uses a credits-based billing system. Operations consume credits based on their resource usage:

Operation	Credits
Video generation	10 credits/second
Image generation	100 credits/image
Voice cloning	500 credits/voice
TTS audio	2 credits/second
Video upscaling	FREE (limited time)

New accounts receive free credits to get started. Check your balance anytime via theGET /auth/credits endpoint.

Rate Limits

API requests are rate-limited based on your subscription tier:

Tier	Requests/min	Concurrent Jobs
Free	20	2
Starter	60	5
Pro	200	20
Business	600	50

Rate limit information is returned in response headers:

http

X-RateLimit-Limit</span>: 60
X-RateLimit-Remaining</span>: 45
X-RateLimit-Reset</span>: 1679529600

Next Steps

Quickstart Guide

Create your first video in 5 minutes

Scene Projects API

Learn about multi-scene video generation

Voice Cloning

Clone voices for your videos