Skip to main content
🎉 New Feature! Customize avatar appearance per scene for dynamic, professional videos.

​
Overview

Scene-level avatar customization allows you to adapt your avatar’s appearance, position, and visibility for each individual scene. This creates dynamic, professional videos that respond to changing content and backgrounds.
Scene-level settings override global avatar configuration. Any property not specified at the scene level inherits from the global avatar settings.

​
How It Works

​
Global vs Scene-Level Configuration

{
  // Global avatar configuration (applies to all scenes)
  "avatar": {
    "avatarId": "...",
    "position": "bottom-right",
    "width": "20%",
    "backgroundColor": "rgba(255,255,255,1)"
  },

  "scenes": [
    {
      // Scene 1: Uses global avatar settings
      "story": "Introduction scene"
    },
    {
      // Scene 2: Overrides position and background color
      "story": "Demo scene with custom layout",
      "avatar": {
        "top": "10%",
        "left": "5%",
        "backgroundColor": "rgba(244,241,246,1)"
      }
    },
    {
      // Scene 3: Hides avatar completely
      "story": "Focus on content without avatar",
      "avatar": {
        "hide": true
      }
    }
  ]
}
Pro Tip: Define your default avatar configuration globally, then only override specific properties in scenes where you need different behavior.

​
Common Use Cases

​
Use Case 1: Hide Avatar for Specific Scenes

Hide the avatar to focus attention on content: 
{
  "avatar": {
    "avatarId": "Annie_expressive12_public",
    "position": "bottom-right",
    "width": "20%"
  },

  "scenes": [
    {
      "story": "Welcome to our product demo. I will guide you through the features.",
      // Avatar visible (uses global config)
    },
    {
      "story": "Here is our product interface.",
      "background": {
        "visualUrl": "https://example.com/product-screenshot.jpg",
        "type": "image"
      },
      // Hide avatar to show full interface
      "avatar": {
        "hide": true
      }
    },
    {
      "story": "Now let me explain how it works.",
      // Avatar returns (uses global config again)
    }
  ]
}
When to hide avatar:
  • Showing detailed interfaces or dashboards
  • Displaying full-screen graphics
  • Focusing on text-heavy content
  • Transition scenes or title cards

​
Use Case 2: Reposition for Background Content

Move avatar to avoid covering important content: 
{
  "avatar": {
    "avatarId": "...",
    "position": "bottom-right",  // Default position
    "width": "20%"
  },

  "scenes": [
    {
      "story": "Let me show you our dashboard.",
      "background": {
        "visualUrl": "https://example.com/dashboard-right-panel.jpg",
        "type": "image"
      },
      // Move to left since important content is on right
      "avatar": {
        "position": "bottom-left"
      }
    },
    {
      "story": "Here are the analytics charts.",
      "background": {
        "visualUrl": "https://example.com/charts-left-side.jpg",
        "type": "image"
      },
      // Move to right since charts are on left
      "avatar": {
        "position": "bottom-right"
      }
    }
  ]
}

​
Use Case 3: Adjust Size for Emphasis

Vary avatar size based on scene importance: 
{
  "avatar": {
    "avatarId": "...",
    "position": "bottom-right",
    "width": "20%"  // Standard size
  },

  "scenes": [
    {
      "story": "Welcome! I am excited to share this with you.",
      // Larger avatar for personal introduction
      "avatar": {
        "width": "28%",
        "position": "center-right"
      }
    },
    {
      "story": "Here are the technical details and specifications.",
      // Smaller avatar to focus on content
      "avatar": {
        "width": "15%"
      }
    },
    {
      "story": "Thank you for watching! Remember to subscribe.",
      // Larger avatar for closing statement
      "avatar": {
        "width": "25%"
      }
    }
  ]
}

​
Use Case 4: Change Background Color by Scene

Adapt avatar background for different video backgrounds: 
{
  "avatar": {
    "avatarId": "...",
    "position": "bottom-right",
    "width": "20%",
    "backgroundColor": "rgba(255,255,255,1)"  // White by default
  },

  "scenes": [
    {
      "story": "This is our light-themed interface.",
      "background": {
        "color": "rgba(245,245,245,1)"  // Light gray background
      }
      // Uses default white avatar background
    },
    {
      "story": "And here is our dark mode.",
      "background": {
        "color": "rgba(30,30,30,1)"  // Dark background
      },
      // Dark avatar background for contrast
      "avatar": {
        "backgroundColor": "rgba(50,50,50,0.9)"
      }
    }
  ]
}

​
Use Case 5: Custom Positioning for Complex Layouts

Use precise positioning for specific scene requirements: 
{
  "avatar": {
    "avatarId": "...",
    "position": "bottom-right",
    "width": "20%"
  },

  "scenes": [
    {
      "story": "Standard introduction scene."
      // Uses preset position
    },
    {
      "story": "Special layout scene.",
      "background": {
        "visualUrl": "https://example.com/complex-layout.jpg",
        "type": "image"
      },
      // Fine-tuned positioning
      "avatar": {
        "top": "18%",
        "left": "76%",
        "width": "22%"
      }
    }
  ]
}

​
Scene-Level Properties

All avatar properties can be overridden at scene level:
​
avatar.position
string
Override preset position: top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right
​
avatar.top
string
Custom top position as percentage (e.g., “10%”, “25%”)
​
avatar.left
string
Custom left position as percentage (e.g., “5%”, “80%”)
​
avatar.width
string
Avatar width as percentage (e.g., “15%”, “20%”, “30%”)
​
avatar.borderRadius
string
Corner rounding: "0", "50", "100"
​
avatar.borderColor
string
Border color in RGBA format (e.g., “rgba(255,255,255,1)”, “rgba(132,44,254,1)”)
​
avatar.borderThickness
number
Border width in pixels (0, 2, 4, 6, 8)
​
avatar.backgroundColor
string
Background color in RGBA (e.g., “rgba(255,255,255,1)”)
​
avatar.hide
boolean
Hide avatar for this scene (true or false)
Important: You cannot change avatarId at the scene level. The same avatar must be used throughout the video. You can only override styling and positioning properties.

​
Advanced Patterns

​
Pattern 1: Progressive Avatar Presence

Start subtle, become more prominent, then fade out: 
{
  "scenes": [
    {
      "story": "Opening title sequence.",
      "avatar": { "hide": true }
    },
    {
      "story": "Hello, welcome to the presentation.",
      "avatar": { "width": "18%", "position": "bottom-right" }
    },
    {
      "story": "Let me explain the key concepts in detail.",
      "avatar": { "width": "22%", "position": "center-right" }
    },
    {
      "story": "Here are the detailed specifications.",
      "avatar": { "hide": true }
    },
    {
      "story": "Thank you for watching!",
      "avatar": { "width": "25%", "position": "center-center" }
    },
    {
      "story": "Closing credits.",
      "avatar": { "hide": true }
    }
  ]
}

​
Pattern 2: Split-Screen Effect

Position avatar on alternating sides for visual variety: 
{
  "scenes": [
    {
      "story": "First point about product benefits.",
      "avatar": { "position": "center-left", "width": "25%" }
    },
    {
      "story": "Second point about ease of use.",
      "avatar": { "position": "center-right", "width": "25%" }
    },
    {
      "story": "Third point about pricing.",
      "avatar": { "position": "center-left", "width": "25%" }
    },
    {
      "story": "Fourth point about support.",
      "avatar": { "position": "center-right", "width": "25%" }
    }
  ]
}

​
Pattern 3: Background-Adaptive Positioning

Automatically adjust based on background content: 
const createSceneWithAdaptiveAvatar = (story, backgroundUrl, contentPosition) => {
  const avatarPosition = {
    left: 'bottom-right',
    right: 'bottom-left',
    center: 'top-center',
    top: 'bottom-center',
    bottom: 'top-center'
  };

  return {
    story,
    background: {
      visualUrl: backgroundUrl,
      type: 'image',
      settings: { mute: true, loop: true }
    },
    avatar: {
      position: avatarPosition[contentPosition]
    }
  };
};

const scenes = [
  createSceneWithAdaptiveAvatar(
    'Content on left side',
    'https://example.com/left-content.jpg',
    'left'
  ),
  createSceneWithAdaptiveAvatar(
    'Content on right side',
    'https://example.com/right-content.jpg',
    'right'
  )
];

​
Pattern 4: Themed Scenes with Matching Avatar Style

Coordinate avatar styling with scene themes: 
{
  "scenes": [
    {
      "story": "Welcome to our professional services overview.",
      // Professional theme: subtle, neutral
      "background": { "color": "rgba(240,240,245,1)" },
      "avatar": {
        "backgroundColor": "rgba(255,255,255,1)",
        "borderColor": "rgba(204,204,204,1)",
        "borderThickness": 2,
        "borderRadius": "50"
      }
    },
    {
      "story": "Now for our creative solutions!",
      // Creative theme: colorful, bold
      "background": { "color": "rgba(255,235,245,1)" },
      "avatar": {
        "backgroundColor": "rgba(132,44,254,0.15)",
        "borderColor": "rgba(132,44,254,1)",
        "borderThickness": 4,
        "borderRadius": "100"
      }
    }
  ]
}

​
Complete Example

Here’s a full video demonstrating multiple customization techniques: 
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: 'dynamic_avatar_demo',
    language: 'en',
    videoWidth: 1920,
    videoHeight: 1080,
    saveProject: true,

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

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

    // Global avatar configuration
    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 product demonstration. I will guide you through all the features.',
        createSceneOnEndOfSentence: true,
        minimumDuration: 4
        // Uses global avatar settings
      },
      {
        story: 'First, let me show you the main dashboard interface.',
        createSceneOnEndOfSentence: true,
        minimumDuration: 4,
        background: {
          type: 'image',
          visualUrl: 'https://example.com/dashboard.jpg',
          settings: { mute: true }
        },
        // Hide avatar to show full interface
        avatar: {
          hide: true
        }
      },
      {
        story: 'The dashboard provides real-time analytics and insights.',
        createSceneOnEndOfSentence: true,
        minimumDuration: 4
        // Avatar returns with global settings
      },
      {
        story: 'Now let us look at the settings panel on the right side.',
        createSceneOnEndOfSentence: true,
        minimumDuration: 4,
        background: {
          type: 'image',
          visualUrl: 'https://example.com/settings-right.jpg',
          settings: { mute: true }
        },
        // Move avatar to left to avoid covering settings
        avatar: {
          position: 'bottom-left',
          width: '18%'
        }
      },
      {
        story: 'Thank you for watching! Visit our website to learn more.',
        createSceneOnEndOfSentence: true,
        minimumDuration: 4,
        // Larger, centered avatar for closing
        avatar: {
          position: 'center-center',
          width: '28%'
        }
      }
    ]
  })
});

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

​
Best Practices

Before coding:
  • Sketch your video flow
  • Identify scenes where avatar should hide
  • Mark scenes needing position changes
  • Note background content locations
Benefits:
  • Smoother visual transitions
  • Better content presentation
  • Fewer adjustments needed
Guidelines:
  • Keep avatar size consistent (±5% variation max)
  • Use the same styling throughout
  • Make position changes purposeful, not random
  • Return to default position when possible
Exception:
  • Intro/outro scenes can have different sizes
Check for:
  • Jarring position jumps
  • Sudden size changes
  • Style inconsistencies
  • Background color clashes
Fix with:
  • Gradual position shifts
  • Smoother size transitions
  • Consistent styling
  • Scene-appropriate colors
Good reasons to hide:
  • Full-screen demonstrations
  • Complex visual content
  • Title cards or transitions
  • Text-heavy information
Avoid hiding:
  • For more than 2-3 consecutive scenes
  • Without clear visual benefit
  • Randomly throughout video

​
Troubleshooting

Problem: Scene-level settings not applyingCheck:
  • Property names match exactly (case-sensitive)
  • RGBA format is correct for colors
  • Percentage values include ”%” symbol
  • Not trying to override avatarId (identity field cannot be changed at scene level)
Solution:
// Correct
avatar: {
  "backgroundColor": "rgba(255,255,255,1)",
  "width": "20%"
}

// Incorrect
avatar: {
  "background-color": "rgb(255,255,255)",  // Wrong format
  "width": 20  // Missing %
}
Problem: Avatar position changes too abruptlySolutions:
  1. Use adjacent positions (e.g., bottom-right → bottom-center → bottom-left)
  2. Add transition scene between major position changes
  3. Keep position consistent for related content
  4. Test preview to verify smoothness
Problem: Avatar looks different across scenesCheck:
  • Border settings are consistent
  • Background colors have proper contrast
  • Size variations are intentional
  • All scenes inherit global settings properly
Fix:
  • Set global defaults for consistency
  • Only override when necessary
  • Document your overrides

​
Quick Reference

​
Scene Avatar Override Template

// Copy this template for scene-level customization
{
  "story": "Your scene text here",
  "createSceneOnEndOfSentence": true,
  "minimumDuration": 4,
  "avatar": {
    // Position (choose one method)
    "position": "bottom-right",        // OR
    "top": "10%", "left": "80%",       // Custom position

    // Size
    "width": "20%",

    // Styling
    "borderRadius": "100",
    "borderColor": "rgba(185,185,186,1)",
    "borderThickness": 4,
    "backgroundColor": "rgba(255,255,255,1)",

    // Visibility
    "hide": false
  }
}

​
Next Steps

Avatar Positioning

Master positioning techniques and best practices

Create Avatar Video

Complete guide to creating avatar videos

API Reference

Full technical API documentation

Background Settings

Configure background media settings