Create Video with Avatar

🎉 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.

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.

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.

Quick Start

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

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.

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

Prerequisites

Before creating avatar videos, you need:

API Key - Get your API key from the Pictory dashboard
Avatar Details - Use the Get Avatars API to retrieve available avatarId values
Voice Selection - Choose an AI voice from the Get Voiceover Tracks API
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:

{
  "videoName": "corporate_training_video",
  "language": "en",
  "videoWidth": 1920,
  "videoHeight": 1080,
  "saveProject": true
}

videoName

string

required

Give your video a descriptive name (alphanumeric, spaces, underscores, hyphens)

language

string

Content language: en, es, fr, de, it, pt, ja, ko, zh, nl, ru, hi

videoWidth

integer

Video width in pixels (e.g., 1920 for Full HD)

videoHeight

integer

Video height in pixels (e.g., 1080 for Full HD)

saveProject

boolean

Save project for future editing (recommended: true)

Step 2: Set Up Voice-Over

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

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

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

Step 3: Configure Your Avatar

Add the avatar configuration with appearance and positioning:

{
  "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

avatarId

string

required

Unique identifier for the avatar (e.g., “Annie_expressive12_public”). Get from Get Avatars API.

Optional Styling

position

string

Preset position: top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-rightDefault: bottom-right

width

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

borderRadius

string

Corner rounding: 0 (square), 50 (rounded), 100 (circular)

backgroundColor

string

Background color in RGBA format (e.g., “rgba(255,255,255,1)“)

Step 4: Add Your Content

Define scenes with the text your avatar will narrate:

{
  "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
        }
      }
    }
  ]
}

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

Step 5: Add Background Music (Optional)

Enhance your video with background music:

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

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

Complete Example

Here’s a full example with all features:

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);

Monitoring Progress

After creating your avatar video, poll the job status:

// 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

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

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

Social Media Content

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

Best Practices

Script Writing

Write in conversational tone
Use short, clear sentences
Include natural pauses
Test pronunciation of technical terms

Avatar Positioning

Don’t overlap subtitles or key visuals
Keep size between 15-25% of frame
Use consistent positioning
Consider background contrast

Audio Balance

Set music volume to 0.1-0.2
Use clear AI voices
Adjust speed to 90-110
Test audio clarity

Scene Pacing

4-5 seconds minimum per scene
Natural sentence breaks
Add pauses between topics
Keep scenes under 15 seconds

Troubleshooting

Avatar Not Appearing

Issue: Avatar doesn’t show in videoSolutions:

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

Lip Sync Issues

Issue: Avatar lip movements don’t match audioSolutions:

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

Audio Too Quiet/Loud

Issue: Voice or music volume is offSolutions:

Adjust amplificationLevel (-1 to 1)
Reduce background music volume (0.1-0.2)
Test different volume combinations
Keep music instrumental only

Avatar Position Issues

Issue: Avatar overlaps important contentSolutions:

Try different preset positions
Use custom top/left positioning
Reduce avatar width
Adjust per-scene if needed

Next Steps

Get Avatars

Browse available avatars and their looks

Avatar Positioning

Learn advanced positioning techniques

Scene-Level Customization

Customize avatars per scene

API Reference

Full API documentation

Voice-Over Guide

Master AI voice-over settings

Getting started

Text to Video

Video with Avatar

Article to Video

Presentation to Video

Audio to Video

Video to Shorts

AI-Generated Visuals

Video Story CoPilot

Smart Layouts and Subtitles

Branding & Customization

Template to Video

Voice-Over

Advanced Features

​Introduction

​Quick Start

​AI Credits

​Prerequisites

​Step-by-Step Guide

​Step 1: Configure Basic Video Settings

​Step 2: Set Up Voice-Over

​Step 3: Configure Your Avatar

​Required Avatar Fields

​Optional Styling

​Step 4: Add Your Content

​Step 5: Add Background Music (Optional)

​Complete Example

​Monitoring Progress

​Common Use Cases

​Best Practices

Script Writing

Avatar Positioning

Audio Balance

Scene Pacing

​Troubleshooting

​Next Steps

Get Avatars

Avatar Positioning

Scene-Level Customization

API Reference

Voice-Over Guide

Introduction

Quick Start

AI Credits

Prerequisites

Step-by-Step Guide

Step 1: Configure Basic Video Settings

Step 2: Set Up Voice-Over

Step 3: Configure Your Avatar

Required Avatar Fields

Optional Styling

Step 4: Add Your Content

Step 5: Add Background Music (Optional)

Complete Example

Monitoring Progress

Common Use Cases

Best Practices

Troubleshooting

Next Steps