Kameo AI - Talking Head Video Generation

Transform static images into expressive talking-head videos with realistic motion and lip-sync.

Quick Start

CODEBLOCK0

Example:
CODEBLOCK1

What It Does

• - Takes a static image (portrait/avatar)
• Adds realistic facial motion, expressions, and lip-sync based on your prompt
• Generates 5-second video in 9:16, 16:9, or 1:1 aspect ratio
• Returns CDN URL instantly (processing ~10-30 seconds)

Authentication

Set your Kameo API key:
CODEBLOCK2

Or store in ~/.config/kameo/credentials.json:
CODEBLOCK3

Getting an API Key:

1. 1. Register at kameo.chat (requires email verification)
2. Login to get JWT token
3. Create API key via /api/public/keys endpoint
4. Or use the registration helper: INLINECODE2

Prompt Engineering

Basic Prompts (Simple)

Just the dialogue:
CODEBLOCK4

Works but results are generic.

Enhanced Prompts (Recommended)

Format:
CODEBLOCK5

Example:
CODEBLOCK6

Why Enhanced Prompts Matter:

• - Better facial expressions matching the scene context
• More natural motion and gestures
• Improved lip-sync quality
• Contextual emotional delivery

Prompt Enhancement Workflow

For best results, use vision AI to analyze the image first:

1. 1. Feed the image to a vision model (Gemini, GPT-4V, Claude)
2. Ask it to describe the scene in cinematic detail
3. Insert your dialogue into the description
4. Use the enhanced prompt for Kameo

See: scripts/enhance_prompt.sh for automated enhancement.

API Details

Base URL: INLINECODE4

Generate Video

CODEBLOCK7

Parameters:

• - image_base64 (required): Base64-encoded JPEG/PNG
• INLINECODE6 (required): Dialogue and/or scene description
• INLINECODE7 (optional): 5 (default) or 10
• INLINECODE8 (optional): "9:16" (default), "16:9", or "1:1"

Response:
CODEBLOCK8

Check Credits

CODEBLOCK9

Response:
CODEBLOCK10

Pricing

CODEBLOCK11

Cost: 3 credits per video

Performance

• - Processing time: 8-35 seconds (depends on aspect ratio and queue)
• 9:16 (portrait): ~30-35s
• 16:9 (landscape): ~15-20s
• 1:1 (square): ~10-15s

Best Practices

1. 1. Optimize image size - Resize large images before encoding (saves bandwidth, faster upload)

1. 2. Use descriptive prompts - Enhanced prompts = better results

1. 3. Choose aspect ratio wisely

1. 4. Monitor credits - Check balance with INLINECODE9

Limitations

• - CDN access: Video URLs may have time-limited access or require authentication
• Download: Videos may return 403 when downloaded via curl (use browser or authenticated session)
• Rate limits: 10 generations per minute

Troubleshooting

"401 Unauthorized"

• - Check your API key is set correctly
• Verify key hasn't been revoked

"402 Insufficient credits"

• - Check credit balance: INLINECODE10
• Need to add credits at kameo.chat

"Timeout errors"

• - 9:16 videos take longer (~30s)
• Increase timeout in scripts
• Retry if server is busy

"403 when downloading video"

• - CDN URLs may be time-limited
• Try accessing in browser immediately after generation
• Or save the base64 response if available

Use Cases

• - AI character videos - Bring bot avatars to life
• Social media content - Dynamic profile videos
• Demos and presentations - Talking product demos
• Educational content - Video tutorials with AI presenters
• Multilingual content - Same avatar speaking different languages