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

# Talking Avatar

> Create talking avatar videos with AI avatars

<Note>
  **Try it out!** Use the API playground on the right to test the Talking Avatar endpoint directly.
</Note>

## Overview

Talking Avatar creates videos with AI avatars that speak naturally using advanced lipsync technology. This format is ideal for:

* Testimonial-style videos
* Social media content
* Personal video messages
* Quick video updates
* Product presentations

<Info>
  Talking Avatar uses AI avatars with voice synthesis and lipsync technology to create realistic videos that feel natural and engaging.
</Info>

***

## Endpoint

```
POST /v1/project/create/talking-avatar
```

***

## Required Fields

<ParamField body="script" type="string" required>
  The script for the avatar to speak (1-10,000 characters). Write naturally as if a real person is speaking.
</ParamField>

<ParamField body="avatarId" type="string" required>
  Avatar ID from `/v1/avatar/list`. Choose an avatar that matches your target audience.
</ParamField>

<ParamField body="voiceId" type="string" required>
  Voice ID from `/v1/voice/list`. The voice used for the avatar's speech.
</ParamField>

***

## Optional Fields

<ParamField body="name" type="string">
  Video name (max 100 characters)
</ParamField>

<ParamField body="lipsyncModel" type="string" default="base">
  Lipsync model quality:

  * `base`: Standard quality, faster processing
  * `pro`: Higher quality, more accurate synchronization
</ParamField>

<ParamField body="musicId" type="string">
  Music ID from `/v1/music/list` for background music.
</ParamField>

<ParamField body="caption" type="object">
  Caption settings for the video

  <Expandable title="Caption Object">
    <ParamField body="preset" type="string" default="tiktok">
      Caption preset style. Available presets: `default`, `beast`, `umi`, `tiktok`, `wrap1`, `wrap2`, `ariel`, `hooked`, `classic`, `active`, `bubble`, `glass`, `comic`, `glow`, `pastel`, `neon`, `retroTV`, `red`, `marker`, `modern`, `blue`, `vivid`.
    </ParamField>

    <ParamField body="alignment" type="string" default="bottom">
      Caption position on the video: `top`, `middle`, or `bottom`
    </ParamField>

    <ParamField body="disabled" type="boolean" default="false">
      Set to `true` to hide captions on the video
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="audio" type="object">
  Voice audio settings

  <Expandable title="Audio Settings Object">
    <ParamField body="speed" type="number" default="1">
      Voice speed multiplier (0.7 to 1.2)
    </ParamField>

    <ParamField body="stability" type="number" default="0.5">
      Voice stability (0 to 1). Higher values produce more consistent speech.
    </ParamField>

    <ParamField body="similarityBoost" type="number" default="0.75">
      Voice similarity boost (0 to 1). Higher values make the voice more similar to the original.
    </ParamField>

    <ParamField body="style" type="number" default="0">
      Voice style exaggeration (0 to 1).
    </ParamField>

    <ParamField body="useSpeakerBoost" type="boolean" default="true">
      Enable speaker boost for clearer audio.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhook" type="string">
  HTTPS URL to receive completion notification (max 500 characters). **Highly recommended** for production use.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata object (max 5KB). Store any additional data you need to associate with this video.

  ```json theme={null}
  {
    "campaignId": "summer2024",
    "customField": "any value"
  }
  ```
</ParamField>

***

## Request Examples

### Basic Talking Avatar

```json theme={null}
{
  "script": "Check out this amazing product! It's super easy to use and I love the results.",
  "avatarId": "2",
  "voiceId": "confident_voice_id"
}
```

### Complete Talking Avatar

```json theme={null}
{
  "name": "Welcome Video",
  "script": "Hey there! Thanks for checking out our channel. We create awesome content every week, so make sure to subscribe and hit that notification bell!",
  "avatarId": "2",
  "voiceId": "confident_voice_id",
  "lipsyncModel": "pro",
  "caption": {
    "preset": "tiktok",
    "alignment": "bottom",
    "disabled": false
  },
  "audio": {
    "speed": 1,
    "stability": 0.5,
    "similarityBoost": 0.75,
    "style": 0,
    "useSpeakerBoost": true
  },
  "musicId": "music_upbeat_01",
  "webhook": "https://yoursite.com/webhook",
  "metadata": {
    "channelId": "my-channel",
    "videoType": "welcome"
  }
}
```

***

## Response

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "data": {
      "videoId": "vid_talking_avatar_abc123xyz",
      "projectId": "proj_ugc_abc123xyz",
      "status": "STARTED"
    },
    "message": "Talking avatar successfully created"
  }
  ```

  ```json Error Response - Validation Error theme={null}
  {
    "success": false,
    "message": "script: Script must be at least 1 character"
  }
  ```

  ```json Error Response - Avatar Not Found theme={null}
  {
    "success": false,
    "message": "avatarId: Avatar \"invalid_id\" not found."
  }
  ```
</ResponseExample>

***

## Webhook Notification

When your video is ready, we'll POST to your webhook URL:

```json Webhook Payload theme={null}
{
  "status": "COMPLETED",
  "data": {
    "videoId": "vid_talking_avatar_abc123xyz",
    "status": "COMPLETED",
    "url": "https://cdn.hooked.so/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.hooked.so/shared/abc123xyz.mp4",
    "metadata": {
      "projectId": "proj_ugc_abc123xyz",
      "channelId": "my-channel"
    }
  },
  "message": "Video completed"
}
```

<Note>
  Your webhook endpoint must return a `200` status code. We'll retry up to 3 times if the request fails.
</Note>

***

## Lipsync Models

| Model  | Description                                           | Processing Time | Best For                                                     |
| ------ | ----------------------------------------------------- | --------------- | ------------------------------------------------------------ |
| `base` | Standard lipsync quality                              | Faster          | Quick videos, testing, lower priority content                |
| `pro`  | Higher quality lipsync, more accurate synchronization | Slower          | Professional content, final productions, high-quality output |

***

## Caption Presets

Available caption presets for the `caption.preset` field:

| Preset    | Description                                              |
| --------- | -------------------------------------------------------- |
| `default` | Default caption style with bold text and shadow effects  |
| `beast`   | Bold uppercase style with Komika font                    |
| `umi`     | Yellow glowing text style                                |
| `tiktok`  | Viral & trendy style, perfect for social media           |
| `wrap1`   | Wrapped style with red background highlight              |
| `wrap2`   | Wrapped style with blue background highlight (uppercase) |
| `ariel`   | Bold uppercase style with purple highlight               |
| `hooked`  | Brand style with purple background                       |
| `classic` | Clean, simple captions with black background             |
| `active`  | Green background with bold text                          |
| `bubble`  | White background bubble style                            |
| `glass`   | Glassmorphic transparency effect                         |
| `comic`   | Comic Sans font with colorful style                      |
| `glow`    | Pink and orange glow effects                             |
| `pastel`  | Soft pastel pink background                              |
| `neon`    | Green neon glow effect                                   |
| `retroTV` | Retro TV style with cyan glow                            |
| `red`     | Red glow effect with white text                          |
| `marker`  | Yellow marker/highlighter style                          |
| `modern`  | Contemporary white background style                      |
| `blue`    | Blue background style                                    |
| `vivid`   | Vibrant pink background with uppercase text              |

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Write Naturally" icon="pen">
    Scripts should sound conversational. Use contractions, pauses, and natural speech patterns.
  </Card>

  <Card title="Choose the Right Model" icon="settings">
    Use `base` for faster processing, `pro` for higher quality lipsync synchronization.
  </Card>

  <Card title="Match Voice to Avatar" icon="user">
    Choose a voice that matches the avatar's appearance for authenticity.
  </Card>

  <Card title="Fine-tune Audio" icon="volume">
    Adjust audio settings like speed and stability to match your content style.
  </Card>

  <Card title="Keep It Concise" icon="clock">
    Shorter videos (15-60 seconds) tend to perform better on social media.
  </Card>

  <Card title="Use Webhooks" icon="webhook">
    Always use webhooks in production instead of polling for video status.
  </Card>
</CardGroup>

***

## Error Handling

| Error                                         | Description             | Solution                                     |
| --------------------------------------------- | ----------------------- | -------------------------------------------- |
| `script: Script must be at least 1 character` | Missing or empty script | Add the `script` field with your content     |
| `avatarId: Avatar not found`                  | Invalid avatar ID       | Use a valid avatar ID from `/v1/avatar/list` |
| `voiceId: Voice not found`                    | Invalid voice ID        | Use a valid voice ID from `/v1/voice/list`   |
| `lipsyncModel: Invalid lipsync model`         | Invalid lipsync model   | Use either `base` or `pro`                   |
| `webhook: Must be a valid HTTPS URL`          | Invalid webhook URL     | Ensure webhook URL starts with `https://`    |
| `Not enough credits`                          | Insufficient credits    | Top up your account credits                  |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="List Avatars" icon="users" href="/api-reference/avatar/list">
    Browse available avatars
  </Card>

  <Card title="List Voices" icon="microphone" href="/api-reference/voice/list">
    Find the perfect voice
  </Card>

  <Card title="List Videos" icon="list" href="/api-reference/video/list">
    View all your created videos
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/guides/webhooks">
    Learn how to handle webhook notifications
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /v1/project/create/talking-avatar
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
security:
  - ApiKeyAuth: []
paths:
  /v1/project/create/talking-avatar:
    post:
      tags:
        - Videos
      summary: Create Talking Avatar
      description: Create talking avatar videos with AI avatars
      operationId: createTalkingAvatar
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - script
                - avatarId
                - voiceId
              properties:
                script:
                  type: string
                  description: The script for the avatar to speak (1-10,000 characters)
                  minLength: 1
                  maxLength: 10000
                name:
                  type: string
                  description: Video name (max 100 characters)
                  maxLength: 100
                avatarId:
                  type: string
                  description: Avatar ID from /v1/avatar/list
                  maxLength: 30
                voiceId:
                  type: string
                  description: Voice ID from /v1/voice/list
                  maxLength: 30
                musicId:
                  type: string
                  description: Music ID from /v1/music/list for background music
                  maxLength: 30
                lipsyncModel:
                  type: string
                  enum:
                    - base
                    - pro
                  description: Lipsync model
                  default: base
                caption:
                  type: object
                  properties:
                    preset:
                      type: string
                      enum:
                        - default
                        - beast
                        - umi
                        - tiktok
                        - wrap1
                        - wrap2
                        - ariel
                        - hooked
                        - classic
                        - active
                        - bubble
                        - glass
                        - comic
                        - glow
                        - pastel
                        - neon
                        - retroTV
                        - red
                        - marker
                        - modern
                        - blue
                        - vivid
                      description: Caption preset style
                      default: tiktok
                    alignment:
                      type: string
                      enum:
                        - top
                        - middle
                        - bottom
                      description: Caption position on video
                      default: bottom
                    disabled:
                      type: boolean
                      description: Set to false to show captions on the video
                      default: false
                audio:
                  type: object
                  description: Voice audio settings
                  properties:
                    speed:
                      type: number
                      description: Voice speed multiplier (0.7 to 1.2)
                      minimum: 0.7
                      maximum: 1.2
                      default: 1
                    stability:
                      type: number
                      description: Voice stability (0 to 1)
                      minimum: 0
                      maximum: 1
                      default: 0.5
                    similarityBoost:
                      type: number
                      description: Voice similarity boost (0 to 1)
                      minimum: 0
                      maximum: 1
                      default: 0.75
                    style:
                      type: number
                      description: Voice style exaggeration (0 to 1)
                      minimum: 0
                      maximum: 1
                      default: 0
                    useSpeakerBoost:
                      type: boolean
                      description: Enable speaker boost for clearer audio
                      default: true
                webhook:
                  type: string
                  description: HTTPS URL to receive completion notification
                  maxLength: 500
                metadata:
                  type: object
                  description: Custom metadata object (max 5KB)
            example:
              script: >-
                Check out this amazing product! It’s super easy to use and I
                love the results.
              avatarId: '2'
              voiceId: confident_voice_id'
              lipsyncModel: base
              caption:
                preset: wrap1
                alignment: bottom
                disabled: false
              audio:
                speed: 1
                stability: 0.5
                similarityBoost: 0.75
                style: 0
                useSpeakerBoost: true
              webhook: https://yoursite.com/webhook
              metadata:
                campaignId: campaign_id
                variant: A
      responses:
        '200':
          description: Talking Avatar created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      videoId:
                        type: string
                      projectId:
                        type: string
                      status:
                        type: string
                  message:
                    type: string
              example:
                success: true
                data:
                  videoId: vid_talking_avatar_abc123xyz
                  projectId: proj_ugc_abc123xyz
                  status: STARTED
                message: Talking avatar successfully created
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: false
                message: 'script: Script must be at least 1 character'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: false
                message: Invalid API key
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````