# SadTalker - Core.Today AI API

> Talking-head video from a single photo and an audio track — animates the face with natural head motion and eye blinks, with optional GFPGAN face enhancement.

- **Provider**: SadTalker
- **Model ID**: cjwbw/sadtalker
- **Category**: Video Generation
- **Credits**: 91 per run (runtime grows with audio length)
- **Speed**: Slow
- **Quality**: High

## Features
- One photo + audio → talking-head video
- Natural head motion and eye blinks
- Still mode for subtle motion
- Optional GFPGAN face enhancement
- Pose style and expression scale controls

## Use Cases
- Virtual presenters from a single photo
- Personalized video messages
- Educational avatar narration
- Historical photo animation

## API Endpoint

Base URL: https://api.core.today/v1
Create Prediction: POST /predictions
Get Status: GET /predictions/{job_id}

## Authentication
Header: X-API-Key: YOUR_API_KEY

## Input Parameters

### Required
- **source_image**: string - Source face image (png/jpg, or a video)
- **driven_audio**: string - Driving audio (.wav or .mp4)

### Optional
- **use_enhancer**: boolean (default: false) - Use GFPGAN as face enhancer
- **pose_style**: integer (default: 0) - Pose style
- **expression_scale**: number (default: 1) - Larger values make expression motion stronger
- **use_eyeblink**: boolean (default: true) - Add natural eye blinks
- **preprocess**: string (default: crop) - How to preprocess the image (crop/resize/full/extcrop/extfull)
  Options: crop, resize, full, extcrop, extfull
- **size_of_image**: integer (default: 256) - Face model resolution
  Options: 256, 512
- **facerender**: string (default: facevid2vid) - Choose face render
  Options: facevid2vid, pirender
- **still_mode**: boolean (default: true) - Fewer head motions (works with preprocess 'full')

## Examples

### Photo Avatar Narration
Animate a portrait to speak a voiceover
```json
{
  "model": "cjwbw/sadtalker",
  "input": {
    "source_image": "https://example.com/portrait.jpg",
    "driven_audio": "https://example.com/narration.wav",
    "preprocess": "full",
    "still_mode": true,
    "use_enhancer": true
  }
}
```

## Response Format
```json
{
  "job_id": "abc123",
  "status": "pending | processing | completed | failed",
  "result": "URL or data (when completed)"
}
```

## Usage Flow
1. POST /predictions with model and input -> receive job_id
2. GET /predictions/{job_id} -> poll until status is completed or failed
3. Result contains output URL(s)

## Tips
- preprocess 'full' + still_mode keeps the whole photo with subtle motion — most natural for portraits
- Enable use_enhancer for sharper faces (adds processing time)
- Pair with a TTS model to build photo-to-presenter pipelines
- Only animate photos of people who have consented

## Documentation
https://replicate.com/cjwbw/sadtalker