Source Code

Kameo AI - Talking Head Video Generation

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

Quick Start

scripts/generate_video.sh <image_path> <prompt> [output_file]

Example:

scripts/generate_video.sh avatar.jpg "Hello, I am an AI assistant" output.mp4

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:

export KAMEO_API_KEY="kam_I3rdx43IymFNbfBw1c0ZbSc7o3aUfQgz8cljZA6T7fs"

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

{
  "api_key": "kam_I3rdx43IymFNbfBw1c0ZbSc7o3aUfQgz8cljZA6T7fs"
}

Getting an API Key:

Register at kameo.chat (requires email verification)
Login to get JWT token
Create API key via /api/public/keys endpoint
Or use the registration helper: scripts/register.sh

Prompt Engineering

Basic Prompts (Simple)

Just the dialogue:

"Hello, I'm here to help you today"
"こんにちは、私はガッキーです。愛してます。"

Works but results are generic.

Enhanced Prompts (Recommended)

Format:

[Detailed scene/environment], [person's complete appearance and expression], speaking in [tone], "[DIALOGUE]". [Camera and lighting details].

Example:

In a bright outdoor winter setting with soft, overcast daylight, a young woman with long dark hair wearing a white knitted winter hat with ear flaps and a colorful patterned sweater stands centered in frame. She looks directly into the camera with a warm, genuine smile, her eyes crinkling with joy, speaking in a cheerful, affectionate tone, "こんにちは、私はガッキーです。愛してます。" The scene is captured in a medium close-up shot, framed at eye level. The lighting is natural and diffused from above, creating soft, even illumination.

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:

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

See: scripts/enhance_prompt.sh for automated enhancement.

API Details

Base URL: https://api.kameo.chat/api/public

Generate Video

curl -X POST https://api.kameo.chat/api/public/generate \
  -H "X-API-Key: kam_I3rdx43IymFNbfBw1c0ZbSc7o3aUfQgz8cljZA6T7fs" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "<base64_encoded_image>",
    "prompt": "Your detailed prompt here",
    "seconds": 5,
    "aspect_ratio": "9:16"
  }'

Parameters:

image_base64 (required): Base64-encoded JPEG/PNG
prompt (required): Dialogue and/or scene description
seconds (optional): 5 (default) or 10
aspect_ratio (optional): "9:16" (default), "16:9", or "1:1"

Response:

{
  "job_id": "uuid",
  "status": "completed",
  "video_url": "https://cdn.kameo.chat/videos/{uuid}.mp4",
  "duration_seconds": 5,
  "processing_time_ms": 15000
}

Check Credits

curl -H "X-API-Key: kam_..." \
  https://api.kameo.chat/api/public/credits

Response:

{
  "permanent_credits": 294,
  "subscription_credits": 0,
  "total_available": 294
}

Pricing

curl https://api.kameo.chat/api/public/pricing

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

Optimize image size - Resize large images before encoding (saves bandwidth, faster upload)
```
ffmpeg -i large.jpg -vf scale=720:-1 optimized.jpg
```
Use descriptive prompts - Enhanced prompts = better results
Choose aspect ratio wisely
- 9:16: Mobile/social media (TikTok, Instagram Stories)
- 16:9: Desktop/YouTube
- 1:1: Profile pictures, square posts
Monitor credits - Check balance with scripts/check_credits.sh

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: scripts/check_credits.sh
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