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

# Create Video with Avatar

> Learn how to create engaging videos with AI avatars using the Pictory API

<Note>
  **🎉 New Feature!** AI Avatars are now available in the Pictory API. Create presenter-style videos with lifelike avatars that lip-sync to AI narration - no cameras or studios required.
</Note>

## Introduction

AI avatars bring a human presence to your videos without requiring cameras, studios, or on-screen talent. This guide walks you through creating professional avatar-powered videos using the Pictory API.

<Note>
  Avatar videos combine AI voice-over with lifelike avatar animations that lip-sync to your narration, creating engaging presenter-style content perfect for training, marketing, education, and social media.
</Note>

***

## Quick Start

Here's a minimal example to create your first avatar video:

```javascript theme={null}
const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'my_first_avatar_video',
    language: 'en',
    videoWidth: 1920,
    videoHeight: 1080,

    // Voice-over is required for avatar videos
    voiceOver: {
      enabled: true,
      aiVoices: [{
        speaker: 'Matthew',
        speed: 100
      }]
    },

    // Avatar configuration
    avatar: {
      avatarId: 'Annie_expressive12_public',
      position: 'bottom-right',
      width: '20%'
    },

    // Your content
    scenes: [{
      story: 'Welcome to my video! Today we will explore how AI avatars make video creation simple and engaging.',
      createSceneOnEndOfSentence: true,
      minimumDuration: 4
    }]
  })
});

const result = await response.json();
console.log('Job ID:', result.data.jobId);
```

***

## AI Credits

Avatar video generation consumes AI credits from your account. Ensure you have sufficient AI credits before using the Avatar feature.

<Warning>
  Avatar generation costs **15 AI credits per 30 seconds** of video. Plan your video length accordingly to manage credit usage.
</Warning>

***

## Prerequisites

Before creating avatar videos, you need:

1. **API Key** - Get your API key from the Pictory dashboard
2. **Avatar Details** - Use the [Get Avatars](/api-reference/avatars/get-avatars) API to retrieve available `avatarId` values
3. **Voice Selection** - Choose an AI voice from the [Get Voiceover Tracks](/api-reference/voiceovers/get-voiceover-tracks) API
4. **AI Credits** - Sufficient AI credits in your account (15 credits per 30 seconds of avatar video)

***

## Step-by-Step Guide

### Step 1: Configure Basic Video Settings

Start with the essential video parameters:

```json theme={null}
{
  "videoName": "corporate_training_video",
  "language": "en",
  "videoWidth": 1920,
  "videoHeight": 1080,
  "saveProject": true
}
```

<ParamField body="videoName" type="string" required>
  Give your video a descriptive name (alphanumeric, spaces, underscores, hyphens)
</ParamField>

<ParamField body="language" type="string">
  Content language: `en`, `es`, `fr`, `de`, `it`, `pt`, `ja`, `ko`, `zh`, `nl`, `ru`, `hi`
</ParamField>

<ParamField body="videoWidth" type="integer">
  Video width in pixels (e.g., 1920 for Full HD)
</ParamField>

<ParamField body="videoHeight" type="integer">
  Video height in pixels (e.g., 1080 for Full HD)
</ParamField>

<ParamField body="saveProject" type="boolean">
  Save project for future editing (recommended: `true`)
</ParamField>

***

### Step 2: Set Up Voice-Over

Voice-over is **required** when using avatars - the avatar will lip-sync to the narration:

```json theme={null}
{
  "voiceOver": {
    "enabled": true,
    "aiVoices": [
      {
        "speaker": "Matthew",
        "speed": 100,
        "amplificationLevel": 0
      }
    ]
  }
}
```

<Tip>
  **Voice Selection Tips:**

  * Match voice gender to your avatar when possible
  * Use professional voices (Brian, Matthew, Emma) for business content
  * Adjust speed to 90-110 for natural delivery
  * Get available voices from [Get Voiceover Tracks](/api-reference/voiceovers/get-voiceover-tracks)
</Tip>

***

### Step 3: Configure Your Avatar

Add the avatar configuration with appearance and positioning:

```json theme={null}
{
  "avatar": {
    "avatarId": "Annie_expressive12_public",
    "position": "bottom-right",
    "width": "20%",
    "borderRadius": "100",
    "borderColor": "rgba(185,185,186,1)",
    "borderThickness": 4,
    "backgroundColor": "rgba(255,255,255,1)"
  }
}
```

#### Required Avatar Fields

<ParamField body="avatarId" type="string" required>
  Unique identifier for the avatar (e.g., "Annie\_expressive12\_public"). Get from [Get Avatars](/api-reference/avatars/get-avatars) API.
</ParamField>

#### Optional Styling

<ParamField body="position" type="string">
  Preset position: `top-left`, `top-center`, `top-right`, `center-left`, `center-center`, `center-right`, `bottom-left`, `bottom-center`, `bottom-right`

  Default: `bottom-right`
</ParamField>

<ParamField body="width" type="string">
  Avatar width as percentage. Must be an integer percentage from 0% to 100% (e.g., "20%", "25%", "30%"). Decimal percentages like "25.5%" are not supported.

  Default: `"20%"`

  Recommended: 15-30% for optimal balance
</ParamField>

<ParamField body="borderRadius" type="string">
  Corner rounding: `0` (square), `50` (rounded), `100` (circular)
</ParamField>

<ParamField body="backgroundColor" type="string">
  Background color in RGBA format (e.g., "rgba(255,255,255,1)")
</ParamField>

***

### Step 4: Add Your Content

Define scenes with the text your avatar will narrate:

```json theme={null}
{
  "scenes": [
    {
      "story": "Welcome to Pictory. In this video, we will explore how AI avatars work.",
      "createSceneOnEndOfSentence": true,
      "minimumDuration": 4
    },
    {
      "story": "You can create professional videos without cameras or studios.",
      "createSceneOnEndOfSentence": true,
      "minimumDuration": 4,
      "background": {
        "type": "video",
        "visualUrl": "https://example.com/background.mp4",
        "settings": {
          "mute": true,
          "loop": true
        }
      }
    }
  ]
}
```

<Tip>
  **Scene Best Practices:**

  * Use `createSceneOnEndOfSentence: true` for natural pacing
  * Set minimum duration of 3-5 seconds
  * Keep individual scenes under 15 seconds
  * Use clear, conversational language
</Tip>

***

### Step 5: Add Background Music (Optional)

Enhance your video with background music:

```json theme={null}
{
  "backgroundMusic": {
    "enabled": true,
    "autoMusic": true,
    "volume": 0.15
  }
}
```

<Warning>
  **Volume Recommendations:**

  * Keep music volume between 0.1-0.2 when using voice-over
  * Higher volumes may overpower the avatar's narration
  * Test different levels to find the right balance
</Warning>

***

## Complete Example

Here's a full example with all features:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard', {
    method: 'POST',
    headers: {
      'Authorization': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      videoName: 'complete_avatar_demo',
      language: 'en',
      videoWidth: 1920,
      videoHeight: 1080,
      saveProject: true,

      voiceOver: {
        enabled: true,
        aiVoices: [{
          speaker: 'Matthew',
          speed: 100,
          amplificationLevel: 0
        }]
      },

      backgroundMusic: {
        enabled: true,
        autoMusic: true,
        volume: 0.15
      },

      avatar: {
        avatarId: 'Annie_expressive12_public',
        position: 'bottom-right',
        width: '20%',
        borderRadius: '100',
        borderColor: 'rgba(185,185,186,1)',
        borderThickness: 4,
        backgroundColor: 'rgba(255,255,255,1)'
      },

      scenes: [
        {
          story: 'Welcome to our training session. Today we will cover three important topics.',
          createSceneOnEndOfSentence: true,
          minimumDuration: 4
        },
        {
          story: 'First, we will explore the fundamentals of our product.',
          createSceneOnEndOfSentence: true,
          minimumDuration: 4
        },
        {
          story: 'Then we will learn about best practices and common use cases.',
          createSceneOnEndOfSentence: true,
          minimumDuration: 4
        }
      ]
    })
  });

  const result = await response.json();
  console.log('Job ID:', result.data.jobId);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.pictory.ai/pictoryapis/v2/video/storyboard',
      headers={
          'Authorization': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'videoName': 'complete_avatar_demo',
          'language': 'en',
          'videoWidth': 1920,
          'videoHeight': 1080,
          'saveProject': True,

          'voiceOver': {
              'enabled': True,
              'aiVoices': [{
                  'speaker': 'Matthew',
                  'speed': 100,
                  'amplificationLevel': 0
              }]
          },

          'backgroundMusic': {
              'enabled': True,
              'autoMusic': True,
              'volume': 0.15
          },

          'avatar': {
              'avatarId': 'Annie_expressive12_public',
              'position': 'bottom-right',
              'width': '20%',
              'borderRadius': '100',
              'borderColor': 'rgba(185,185,186,1)',
              'borderThickness': 4,
              'backgroundColor': 'rgba(255,255,255,1)'
          },

          'scenes': [
              {
                  'story': 'Welcome to our training session. Today we will cover three important topics.',
                  'createSceneOnEndOfSentence': True,
                  'minimumDuration': 4
              },
              {
                  'story': 'First, we will explore the fundamentals of our product.',
                  'createSceneOnEndOfSentence': True,
                  'minimumDuration': 4
              },
              {
                  'story': 'Then we will learn about best practices and common use cases.',
                  'createSceneOnEndOfSentence': True,
                  'minimumDuration': 4
              }
          ]
      }
  )

  result = response.json()
  print(f"Job ID: {result['data']['jobId']}")
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.pictory.ai/pictoryapis/v2/video/storyboard \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "videoName": "complete_avatar_demo",
      "language": "en",
      "videoWidth": 1920,
      "videoHeight": 1080,
      "saveProject": true,
      "voiceOver": {
        "enabled": true,
        "aiVoices": [{
          "speaker": "Matthew",
          "speed": 100,
          "amplificationLevel": 0
        }]
      },
      "backgroundMusic": {
        "enabled": true,
        "autoMusic": true,
        "volume": 0.15
      },
      "avatar": {
        "avatarId": "Annie_expressive12_public",
        "position": "bottom-right",
        "width": "20%",
        "borderRadius": "100",
        "borderColor": "rgba(185,185,186,1)",
        "borderThickness": 4,
        "backgroundColor": "rgba(255,255,255,1)"
      },
      "scenes": [
        {
          "story": "Welcome to our training session. Today we will cover three important topics.",
          "createSceneOnEndOfSentence": true,
          "minimumDuration": 4
        }
      ]
    }'
  ```
</CodeGroup>

***

## Monitoring Progress

After creating your avatar video, poll the job status:

```javascript theme={null}
// Poll for job completion
const checkStatus = async (jobId) => {
  const response = await fetch(
    `https://api.pictory.ai/pictoryapis/v1/jobs/${jobId}`,
    {
      headers: { 'Authorization': 'YOUR_API_KEY' }
    }
  );

  const job = await response.json();

  if (job.data.status === 'completed') {
    console.log('Video ready!');
    console.log('Preview URL:', job.data.previewUrl);
    console.log('Project URL:', job.data.projectUrl);
    console.log('Video URL:', job.data.videoURL);
  } else if (job.data.status === 'failed') {
    console.error('Video creation failed');
  } else {
    console.log('Status:', job.data.status);
    // Poll again after 5 seconds
    setTimeout(() => checkStatus(jobId), 5000);
  }
};

// Start polling
checkStatus(result.data.jobId);
```

***

## Common Use Cases

<AccordionGroup>
  <Accordion title="Corporate Training Videos">
    Create training modules with a professional avatar instructor:

    * Use formal voices (Matthew, Brian)
    * Position avatar prominently (center-left or center-right)
    * Include clear topic transitions
    * Add relevant background visuals
  </Accordion>

  <Accordion title="Product Demo Videos">
    Showcase products with an avatar guide:

    * Use friendly voices (Emma, Joanna)
    * Position avatar in bottom corner to not block product
    * Keep narration concise and benefits-focused
    * Use product images/videos as backgrounds
  </Accordion>

  <Accordion title="Social Media Content">
    Create engaging social posts:

    * Use 9:16 aspect ratio (vertical)
    * Position avatar prominently (center or top-third)
    * Keep videos under 60 seconds
    * Use dynamic voice pacing
  </Accordion>

  <Accordion title="Educational Content">
    Build course content with avatar teachers:

    * Use clear, measured voice pacing
    * Position avatar consistently across lessons
    * Break content into 5-10 minute segments
    * Include visual aids in backgrounds
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Script Writing" icon="pen-to-square">
    * Write in conversational tone
    * Use short, clear sentences
    * Include natural pauses
    * Test pronunciation of technical terms
  </Card>

  <Card title="Avatar Positioning" icon="arrows-to-circle">
    * Don't overlap subtitles or key visuals
    * Keep size between 15-25% of frame
    * Use consistent positioning
    * Consider background contrast
  </Card>

  <Card title="Audio Balance" icon="volume">
    * Set music volume to 0.1-0.2
    * Use clear AI voices
    * Adjust speed to 90-110
    * Test audio clarity
  </Card>

  <Card title="Scene Pacing" icon="clock">
    * 4-5 seconds minimum per scene
    * Natural sentence breaks
    * Add pauses between topics
    * Keep scenes under 15 seconds
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Avatar Not Appearing">
    **Issue:** Avatar does not show in video

    **Solutions:**

    * Verify all required avatar fields are provided
    * Check avatar URLs are accessible
    * Ensure voiceOver is enabled with at least one AI voice
    * Validate avatarId field
  </Accordion>

  <Accordion title="Lip Sync Issues">
    **Issue:** Avatar lip movements do not match audio

    **Solutions:**

    * Ensure voice-over is properly configured
    * Check that speaker is available for your plan
    * Try adjusting voice speed to 100
    * Contact support if issue persists
  </Accordion>

  <Accordion title="Audio Too Quiet/Loud">
    **Issue:** Voice or music volume is off

    **Solutions:**

    * Adjust `amplificationLevel` (-1 to 1)
    * Reduce background music volume (0.1-0.2)
    * Test different volume combinations
    * Keep music instrumental only
  </Accordion>

  <Accordion title="Avatar Position Issues">
    **Issue:** Avatar overlaps important content

    **Solutions:**

    * Try different preset positions
    * Use custom top/left positioning
    * Reduce avatar width
    * Adjust per-scene if needed
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Get Avatars" icon="users" href="/api-reference/avatars/get-avatars">
    Browse available avatars and their looks
  </Card>

  <Card title="Avatar Positioning" icon="location-dot" href="/guides/video-with-avatar/avatar-positioning">
    Learn advanced positioning techniques
  </Card>

  <Card title="Scene-Level Customization" icon="sliders" href="/guides/video-with-avatar/scene-level-customization">
    Customize avatars per scene
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/videos/create-storyboard-preview">
    Full API documentation
  </Card>

  <Card title="Voice-Over Guide" icon="microphone" href="/guides/text-to-video/ai-voiceover">
    Master AI voice-over settings
  </Card>
</CardGroup>