Name: SadTalker API: Talking Face Video from Photo and Audio
Brand: magicapi
SKU: api-magicapi-audio-driven-talking-face-animation-cjwbw-sadtalker
Availability: InStock
Author: API Market

Shashank Agarwal

# 🗣️ Talking Face Animation API (OpenTalker SadTalker)

## Overview
SadTalker is a model for stylized, audio-driven talking face animation from a single image.

Send a `source_image` with a face and a `driven_audio` clip. The model animates the face so it speaks the audio, with head pose, expression and eye blinks. Each request returns the URL of one mp4 video.

## Features
- **Single image input**: one face image in `source_image` is enough. The field also accepts an mp4 video.
- **Audio-driven motion**: lip and face motion follow `driven_audio` (wav or mp4; the example uses an mp3 file).
- **Pose style**: `pose_style` picks one of 46 head pose styles (0 to 45).
- **Expression strength**: a larger `expression_scale` makes expression motion stronger (default 1).
- **Eye blinks**: `use_eyeblink` (default `true`).
- **Still mode**: `still_mode` (default `true`) reduces head motion; it works with `preprocess` `full`.
- **Preprocessing**: `crop` (default), `resize`, `full`, `extcrop` or `extfull`.
- **Face model resolution**: `size_of_image` `256` (default) or `512`.
- **Renderer**: `facerender` `facevid2vid` (default) or `pirender`.
- **Face enhancer**: `use_enhancer` runs the GFPGAN face enhancer on the result.

## Use Cases
1. **Talking avatars**: a presenter video from a single portrait and a recorded or generated voice track.
2. **Narrated explainers and lessons**: put a face to e-learning or product narration.
3. **Voice-over previews**: check how a script sounds and looks with a character before filming.
4. **Social content**: animated portraits that speak a short audio clip.

## Visual Examples
### Example Input
![Example source image for SadTalker](https://blog.api.market/wp-content/uploads/2026/10/sadtalker-input-2-api-market.png)

[Listen to the example input audio](https://blog.api.market/wp-content/uploads/2026/10/sadtalker-input-api-market.mp3)

The example uses `preprocess` `crop`, `still_mode` `true`, the face enhancer and a 256 face model resolution.

```json
{
  "facerender": "facevid2vid",
  "pose_style": 0,
  "preprocess": "crop",
  "still_mode": true,
  "driven_audio": "https://blog.api.market/wp-content/uploads/2026/10/sadtalker-input-api-market.mp3",
  "source_image": "https://blog.api.market/wp-content/uploads/2026/10/sadtalker-input-2-api-market.png",
  "use_enhancer": true,
  "use_eyeblink": true,
  "size_of_image": 256,
  "expression_scale": 1
}
```

### Example Output
[Watch the example output](https://blog.api.market/wp-content/uploads/2026/10/sadtalker-output-0d9x1va3-api-market.mp4)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `source_image` | string (URL) | Yes | none |  | URL of the source face image (png or jpg); an mp4 video is also accepted |
| `driven_audio` | string (URL) | Yes | none |  | URL of the driving audio; accepts wav and mp4 files |
| `use_enhancer` | boolean | No | `false` |  | Use GFPGAN as face enhancer |
| `pose_style` | integer | No | `0` | `0` to `45` | Pose style |
| `expression_scale` | number | No | `1` |  | A larger value makes the expression motion stronger |
| `use_eyeblink` | boolean | No | `true` |  | Use eye blink |
| `preprocess` | string | No | `crop` | `crop`, `resize`, `full`, `extcrop`, `extfull` | How to preprocess the image |
| `size_of_image` | integer | No | `256` | `256`, `512` | Face model resolution |
| `facerender` | string | No | `facevid2vid` | `facevid2vid`, `pirender` | Face renderer |
| `still_mode` | boolean | No | `true` |  | Still mode (less head motion, works with preprocess full) |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.24 per API unit.
- **1 API unit = 1 request with up to 154 seconds of processing time.** A request that takes longer is billed one unit per started 154-second block (for example, 200 seconds of processing is 2 units, $0.48).
- Longer audio clips and the larger 512 face model take longer to process.
- **Example cost**: the example took 46.2 seconds of processing: 1 API unit = **$0.24**.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/audio-driven-talking-face-animation-cjwbw-sadtalker`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 2 seconds and an overall timeout of 900 seconds (15 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/audio-driven-talking-face-animation-cjwbw-sadtalker/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "a519cc0cfebaaeade068b23899165a11ec76aaa1d2b313d40d214f204ec957a3",
    "input": {
      "facerender": "facevid2vid",
      "pose_style": 0,
      "preprocess": "crop",
      "still_mode": true,
      "driven_audio": "https://blog.api.market/wp-content/uploads/2026/10/sadtalker-input-api-market.mp3",
      "source_image": "https://blog.api.market/wp-content/uploads/2026/10/sadtalker-input-2-api-market.png",
      "use_enhancer": true,
      "use_eyeblink": true,
      "size_of_image": 256,
      "expression_scale": 1
    }
  }'
```

Response (201 Created):
```json
{
  "id": "0d9x1va3jxrne0d1c6m8phzptc",
  "version": "a519cc0cfebaaeade068b23899165a11ec76aaa1d2b313d40d214f204ec957a3",
  "status": "starting",
  "created_at": "2026-10-22T03:29:39.913Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/audio-driven-talking-face-animation-cjwbw-sadtalker/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "0d9x1va3jxrne0d1c6m8phzptc",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/sadtalker-output-0d9x1va3-api-market.mp4",
  "error": null,
  "created_at": "2026-10-22T03:29:39.913Z",
  "started_at": "2026-10-22T03:31:59.574Z",
  "completed_at": "2026-10-22T03:32:45.764Z"
}
```

`output` is a single URL string pointing to the generated mp4 video.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `source_image` or `driven_audio`, or a `preprocess` value that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.
## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/audio-driven-talking-face-animation-cjwbw-sadtalker";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "a519cc0cfebaaeade068b23899165a11ec76aaa1d2b313d40d214f204ec957a3", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 900000;
  const pollInterval = 2000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 15 minutes");
}

createAndWaitForPrediction({
    "facerender": "facevid2vid",
    "pose_style": 0,
    "preprocess": "crop",
    "still_mode": true,
    "driven_audio": "https://blog.api.market/wp-content/uploads/2026/10/sadtalker-input-api-market.mp3",
    "source_image": "https://blog.api.market/wp-content/uploads/2026/10/sadtalker-input-2-api-market.png",
    "use_enhancer": true,
    "use_eyeblink": true,
    "size_of_image": 256,
    "expression_scale": 1
  }).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/audio-driven-talking-face-animation-cjwbw-sadtalker"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "a519cc0cfebaaeade068b23899165a11ec76aaa1d2b313d40d214f204ec957a3", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 900
    poll_interval = 2
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 15 minutes")


output = create_and_wait_for_prediction({
    "facerender": "facevid2vid",
    "pose_style": 0,
    "preprocess": "crop",
    "still_mode": True,
    "driven_audio": "https://blog.api.market/wp-content/uploads/2026/10/sadtalker-input-api-market.mp3",
    "source_image": "https://blog.api.market/wp-content/uploads/2026/10/sadtalker-input-2-api-market.png",
    "use_enhancer": True,
    "use_eyeblink": True,
    "size_of_image": 256,
    "expression_scale": 1
})
print(output)
```

## FAQ
- **What inputs do I need?**
  - A face image URL in `source_image` and an audio URL in `driven_audio`. The schema lists wav and mp4 for audio; the example used an mp3 file.
- **How do I reduce head movement?**
  - Keep `still_mode` set to `true` (the default). It works with `preprocess` `full`.
- **How do I get a sharper face?**
  - Set `use_enhancer` to `true` to run the GFPGAN face enhancer, and try `size_of_image` `512`.
- **How much does a request cost?**
  - $0.24 for each started 154 seconds of processing. The example took 46.2 seconds and cost $0.24.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


SadTalker API turns one face photo and an audio clip into a talking head video, with pose, expression and eye blink controls. Pay as you go per request.