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

# Avatar Videos with Custom Audio

> Use your own audio file instead of text-to-speech

## Introduction

Use your own audio recordings instead of text-to-speech for complete control over voice, timing, and delivery. Perfect for professional voice-overs, branded audio, or languages not supported by TTS.

### Key Features

<CardGroup cols={2}>
  <Card title="Custom Voice" icon="microphone">
    Use professional voice talent recordings
  </Card>

  <Card title="Full Control" icon="sliders">
    Control timing, tone, and delivery
  </Card>

  <Card title="Brand Voice" icon="palette">
    Maintain consistent brand audio identity
  </Card>

  <Card title="Any Language" icon="language">
    Use audio in any language or dialect
  </Card>
</CardGroup>

<Info>
  **When to Use:** Best for professional voice-overs, branded audio, dialects not supported by TTS, or when you need precise control over delivery.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                         | Purpose                 | Documentation                                                  |
| -------------------------------- | ----------------------- | -------------------------------------------------------------- |
| `POST /upload/asset`             | Upload audio file       | [API Reference](/api-reference/v2/Asset/UploadAsset)           |
| `POST /create_video_from_avatar` | Create video with audio | [API Reference](/api-reference/v2/Video/CreateVideoFromAvatar) |
| `GET /avatar_video/{id}`         | Check video status      | [API Reference](/api-reference/v2/Video/AvatarVideoGet)        |

### Key Parameters

| Parameter            | Type    | Required | Description                                         |
| -------------------- | ------- | -------- | --------------------------------------------------- |
| `voice.type`         | string  | ✅        | **Must be "audio"** when using audio\_url           |
| `voice.audio_url`    | string  | ✅        | URL of uploaded audio file                          |
| `voice.voice_id`     | string  | ✅        | Voice ID (still required)                           |
| `avatar.avatar_id`   | integer | ✅        | Avatar ID                                           |
| `avatar.avatar_type` | integer | ✅        | 0=Public, 1=Custom                                  |
| `aspect_ratio`       | string  | ✅        | portrait/landscape/square                           |
| `screen_style`       | integer | ✅        | 1=Full screen, 2=Split screen, 3=Picture in picture |

<Warning>
  **Important:** When using `voice.audio_url`, set `voice.type` to "audio" and do NOT include `voice.script`. The `voice.voice_id` is still required.
</Warning>

## Audio Requirements

**Supported Formats:**

* MP3 (recommended)
* WAV
* M4A

**Specifications:**

* Max size: 20MB
* Max duration: 10 minutes
* Recommended bitrate: 192 kbps for music, 128 kbps for voice
* Sample rate: 44.1 kHz

**Quality Tips:**

```bash theme={null}
# Optimize audio with FFmpeg
ffmpeg -i input.wav -codec:a libmp3lame -b:a 192k output.mp3

# Normalize audio levels
ffmpeg -i input.mp3 -filter:a loudnorm output.mp3
```

***

## Code Examples

### Step 1: Get signed URL for upload

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/upload/asset' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filename": "audio.mp3",
    "content_type": "audio/mpeg"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "sign_url": "https://storage.jogg.ai/upload/signed-url-here",
    "asset_url": "https://res.jogg.ai/assets/aud_abc123.mp3"
  }
}
```

### Step 2: Upload your file using PUT

```bash theme={null}
curl --request PUT \
  --url 'https://storage.jogg.ai/upload/signed-url-here' \
  --header 'Content-Type: audio/mpeg' \
  --data-binary '@/path/to/audio.mp3'
```

### Step 3: Create video with the audio

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "avatar_id": 81,
      "avatar_type": 0
    },
    "voice": {
      "type": "audio",
      "voice_id": "en-US-ChristopherNeural",
      "audio_url": "https://res.jogg.ai/assets/aud_abc123.mp3"
    },
    "aspect_ratio": "portrait",
    "screen_style": 1,
    "caption": false
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

<Check>
  Save the `asset_url` from upload response to use as `voice.audio_url`. Video length will automatically match audio duration.
</Check>

### Step 4: Check Video Status

Poll to check if video is ready:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatar_video/video_123456' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "processing",
    "created_at": 1732806631
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/video_123456.mp4",
    "cover_url": "https://res.jogg.ai/covers/cover_123456.jpg",
    "created_at": 1732806631
  }
}
```

<Tip>
  Instead of polling, use \[Webhooks]\(/api-reference/v2/API Documentation/WebhookIntegration) to get notified instantly when videos are ready!
</Tip>

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="Professional Voice-Overs">
    Use recordings from professional voice talent:

    * Record in professional studio
    * Upload final edited audio
    * Create videos with consistent voice
    * Maintain professional quality
  </Accordion>

  <Accordion title="Brand Voice">
    Maintain branded audio across videos:

    * Use company spokesperson voice
    * Record once, use in multiple videos
    * Consistent brand audio identity
    * Scale branded content easily
  </Accordion>

  <Accordion title="Multiple Takes">
    Use best take from multiple recordings:

    * Record several versions
    * Upload the best performance
    * Edit audio before uploading
    * Perfect timing and delivery
  </Accordion>

  <Accordion title="Unsupported Languages">
    Use audio in languages not supported by TTS:

    * Record in any language or dialect
    * Upload custom audio
    * Create videos with native speakers
    * Reach diverse audiences
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Audio Quality:**

  * Use clear speech audio (not music) for best lip sync
  * Ensure audio quality is good (44.1 kHz, 128-192 kbps)
  * Trim silence at start/end
  * Normalize audio levels
  * Check audio language matches avatar capabilities
</Tip>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Create Avatar Videos" icon="user" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Main avatar video guide
  </Card>

  <Card title="Upload Media" icon="upload" href="/api-reference/v2/API Documentation/UploadMedia">
    Upload audio files guide
  </Card>

  <Card title="Upload Asset API" icon="code" href="/api-reference/v2/Asset/UploadAsset">
    Complete upload API documentation
  </Card>

  <Card title="Get Avatar Video" icon="video" href="/api-reference/v2/Video/AvatarVideoGet">
    Check video status
  </Card>
</CardGroup>