Kameo AI - Talking Head Video Generation

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

Quick Start

```bash

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

```

**Example:**

```bash

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

```

What It Does

Authentication

Set your Kameo API key:

```bash

export KAMEO_API_KEY="kam_I3rdx43IymFNbfBw1c0ZbSc7o3aUfQgz8cljZA6T7fs"

```

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

```json

{

"api_key": "kam_I3rdx43IymFNbfBw1c0ZbSc7o3aUfQgz8cljZA6T7fs"

}

```

**Getting an API Key:**

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: `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:**

Prompt Enhancement Workflow

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

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:** `https://api.kameo.chat/api/public`

Generate Video

```bash

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:**

**Response:**

```json

{

"job_id": "uuid",

"status": "completed",

"video_url": "https://cdn.kameo.chat/videos/{uuid}.mp4",

"duration_seconds": 5,

"processing_time_ms": 15000

}

```

Check Credits

```bash

curl -H "X-API-Key: kam_..." \

https://api.kameo.chat/api/public/credits

```

**Response:**

```json

{

"permanent_credits": 294,

"subscription_credits": 0,

"total_available": 294

}

```

Pricing

```bash

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

```

**Cost:** 3 credits per video

Performance

Best Practices

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

```bash

ffmpeg -i large.jpg -vf scale=720:-1 optimized.jpg

```

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

3. **Choose aspect ratio wisely**

- 9:16: Mobile/social media (TikTok, Instagram Stories)

- 16:9: Desktop/YouTube

- 1:1: Profile pictures, square posts

4. **Monitor credits** - Check balance with `scripts/check_credits.sh`

Limitations

Troubleshooting

**"401 Unauthorized"**

**"402 Insufficient credits"**

**"Timeout errors"**

**"403 when downloading video"**

Use Cases