API Reference

Avatar Projects API

Create talking-head videos where your character speaks directly to camera with voice-controlled lip-sync. Perfect for presentations, announcements, and personalized messages.

Avatar videos use Kling AI for video generation with voice-controlled lip synchronization. The character maintains natural expressions and movements while speaking.

Generate Avatar Video

POST/avatar/generate

Generate a talking-head avatar video

Request Body

Name	Type	Description
`person_id`required	`integer`	Person with photo and voice
`script`required	`string`	Text for the avatar to speak (10-5000 chars)
`start_image_url`	`string`	Custom starting image URL
`image_prompt`	`string`	Prompt to generate start image

bash

curl -X POST https://api.twin.actor/api/v1/avatar/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_id": 1,
    "script": "Hello everyone! I am excited to announce our new product launch. This revolutionary technology will change how you work and create."
  }'

Response:

json

{
  "success": true,
  "project_id": 15,
  "public_id": "avatar_xyz789",
  "segment_count": 2,
  "estimated_duration_seconds": 18,
  "message": "Avatar generation started",
  "poll_url": "/api/v1/avatar/15/status"
}

Check Status

GET/avatar/{id}/status

Get generation progress and results

bash

curl https://api.twin.actor/api/v1/avatar/15/status \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (in progress):

json

{
  "project": {
    "id": 15,
    "public_id": "avatar_xyz789",
    "status": "generating",
    "current_segment": 1,
    "segment_count": 2,
    "segments": [
      { "order": 1, "status": "completed", "video_url": "..." },
      { "order": 2, "status": "generating", "video_url": null }
    ]
  },
  "progress_percent": 50,
  "is_complete": false
}

Response (completed):

json

{
  "project": {
    "id": 15,
    "public_id": "avatar_xyz789",
    "status": "completed",
    "final_video_url": "https://storage.twin.actor/avatar/avatar_xyz789_final.mp4",
    "total_duration_seconds": 18
  },
  "progress_percent": 100,
  "is_complete": true
}

List Projects

GET/avatar

List all avatar projects

bash

curl https://api.twin.actor/api/v1/avatar \
  -H "Authorization: Bearer YOUR_TOKEN"

How Segments Work

Long scripts are automatically split into ~10 second segments for optimal video quality. Each segment is generated separately, then stitched together into the final video.

Scripts are split at natural sentence boundaries
Each segment targets ~25 words (10 seconds at 2.5 words/sec)
The first segment's ending frame becomes the next segment's starting frame
This creates seamless transitions between segments