> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adskull.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Talking Avatars

> Lip-sync a still avatar image to a script or to an existing audio file.

The talking-avatar endpoint produces a video of a still portrait speaking
either a generated script (TTS) or an existing audio clip. Optional
product placement fuses a product image into the same shot.

## Endpoints

| Method | Endpoint                       | Purpose                          |
| ------ | ------------------------------ | -------------------------------- |
| `POST` | `/v1/talking-avatars`          | Create a talking-avatar job.     |
| `GET`  | `/v1/talking-avatars`          | List recent talking-avatar jobs. |
| `GET`  | `/v1/talking-avatars/{job_id}` | Get one talking-avatar job.      |

## Modes

| Mode                 | What it does                                       | Required fields                 |
| -------------------- | -------------------------------------------------- | ------------------------------- |
| `script` *(default)* | Generate speech from text and lip-sync the avatar. | `avatar_image_url`, `script`    |
| `audio`              | Lip-sync the avatar to an existing audio file.     | `avatar_image_url`, `audio_url` |

## Create Parameters

| Field               | Type    | Required                   | Notes                                                                                                               |
| ------------------- | ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `avatar_image_url`  | string  | **Yes**                    | Hosted portrait image URL — `png`/`jpg`/`jpeg`/`webp`, up to 50 MB. Upload local files via `POST /v1/assets` first. |
| `mode`              | string  | No                         | `script` (default) or `audio`. Anything else is rejected.                                                           |
| `script`            | string  | **Yes when `mode=script`** | Minimum **100 characters**, max 8192. Duration estimate = `len(script) / 10` seconds.                               |
| `audio_url`         | string  | **Yes when `mode=audio`**  | Hosted audio URL — `mp3`/`wav`/`m4a`, up to 50 MB.                                                                  |
| `voice_id`          | string  | No                         | Library or custom voice ID. If omitted in script mode, the first voice in your library catalog is used.             |
| `product_placement` | boolean | No                         | Set `true` AND pass `product_image_url` to fuse a product into the shot. Adds **5 credits**.                        |
| `product_image_url` | string  | No                         | Hosted product image URL. Used only when `product_placement=true`.                                                  |
| `background_url`    | string  | No                         | Optional hosted background image URL.                                                                               |

<Note>
  `Idempotency-Key` is **required** on every `POST /v1/talking-avatars`.

  The 100-character minimum for `script` is enforced server-side — shorter
  scripts are rejected with `invalid_request`.

  `script` and `audio_url` cannot both be supplied. If `mode=script` but you
  only pass `audio_url`, the request is auto-promoted to `mode=audio`.
</Note>

## Pricing

* **3 credits per second**, minimum 5 seconds (so 15 credits floor).
* **+ 5 credits** when `product_placement=true`.

## Example: script mode

```bash theme={"theme":"github-dark"}
# 1) Upload the avatar portrait
curl https://api.adskull.io/v1/assets \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -F asset_type=image \
  -F file=@./host.png

# 2) Generate the talking avatar
curl https://api.adskull.io/v1/talking-avatars \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-script-001" \
  -d '{
    "avatar_image_url": "https://cdn.adskull.io/uploads/host.png",
    "mode": "script",
    "voice_id": "ahmed",
    "script": "Welcome to AdSkull. In the next thirty seconds, I will show you how a single prompt can produce a finished, full-audio ad ready for TikTok, Reels, and YouTube Shorts."
  }'
```

## Example: audio mode

```bash theme={"theme":"github-dark"}
curl https://api.adskull.io/v1/talking-avatars \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-audio-001" \
  -d '{
    "avatar_image_url": "https://cdn.adskull.io/uploads/host.png",
    "mode": "audio",
    "audio_url": "https://cdn.adskull.io/uploads/voiceover.mp3"
  }'
```

## Example: with product placement

```bash theme={"theme":"github-dark"}
curl https://api.adskull.io/v1/talking-avatars \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-product-001" \
  -d '{
    "avatar_image_url": "https://cdn.adskull.io/uploads/host.png",
    "mode": "script",
    "voice_id": "ahmed",
    "script": "Meet the new AdSkull One — it produces a complete ad in under sixty seconds from a single prompt. Here is how it transforms your campaign workflow today.",
    "product_placement": true,
    "product_image_url": "https://cdn.adskull.io/uploads/product.png"
  }'
```

## Completed Response

```json theme={"theme":"github-dark"}
{
  "id": "job_01HXAV...",
  "object": "talking_avatar_job",
  "status": "completed",
  "credits_reserved": 45,
  "credits_used": 45,
  "completed_at": "2026-05-17T12:04:00Z",
  "assets": [
    {
      "id": "asset_01HX...",
      "type": "video",
      "url": "https://cdn.adskull.io/generated/avatar.mp4",
      "mime_type": "video/mp4",
      "duration_seconds": 15,
      "width": 1080,
      "height": 1920,
      "expires_at": "2026-05-18T12:04:00Z"
    }
  ]
}
```

## Possible Errors

| HTTP | Code                       | When it happens                                                                          |
| ---: | -------------------------- | ---------------------------------------------------------------------------------------- |
|  400 | `invalid_request`          | Script shorter than 100 chars, missing required field for mode, unsupported file format. |
|  401 | `unauthorized`             | API key missing or invalid.                                                              |
|  402 | `insufficient_credits`     | Not enough credits.                                                                      |
|  413 | `payload_too_large`        | Avatar / audio / product file > 25 MB.                                                   |
|  422 | `content_policy_violation` | Image, audio, or script not allowed.                                                     |
|  429 | `rate_limited`             | Too many requests.                                                                       |
|  503 | `temporarily_unavailable`  | Provider capacity temporarily unavailable.                                               |