Scene-Level Customization

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

string

Override preset position: top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right

string

Custom top position as percentage (e.g., “10%”, “25%”)

string

Custom left position as percentage (e.g., “5%”, “80%”)

string

Avatar width as percentage (e.g., “15%”, “20%”, “30%”)

string

Corner rounding: "0", "50", "100"

string

Border color in RGBA format (e.g., “rgba(255,255,255,1)”, “rgba(132,44,254,1)”)

number

Border width in pixels (0, 2, 4, 6, 8)

string

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

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

import requests

response = requests.post(
    'https://api.pictory.ai/pictoryapis/v2/video/storyboard',
    headers={
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        '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': '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
                'avatar': {
                    'position': 'bottom-left',
                    'width': '18%'
                }
            }
        ]
    }
)

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

Best Practices

Plan Your Scene Flow

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

Maintain Visual Consistency

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

Test Scene Transitions

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

Hide Avatar Strategically

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

Scene Override Not Working

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 %
}

Avatar Jumps Between Scenes

Problem: Avatar position changes too abruptlySolutions:

Use adjacent positions (e.g., bottom-right → bottom-center → bottom-left)
Add transition scene between major position changes
Keep position consistent for related content
Test preview to verify smoothness

Inconsistent Avatar Appearance

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

​Overview

​How It Works

​Global vs Scene-Level Configuration

​Common Use Cases

​Use Case 1: Hide Avatar for Specific Scenes

​Use Case 2: Reposition for Background Content

​Use Case 3: Adjust Size for Emphasis

​Use Case 4: Change Background Color by Scene

​Use Case 5: Custom Positioning for Complex Layouts

​Scene-Level Properties

​Advanced Patterns

​Pattern 1: Progressive Avatar Presence

​Pattern 2: Split-Screen Effect

​Pattern 3: Background-Adaptive Positioning

​Pattern 4: Themed Scenes with Matching Avatar Style

​Complete Example

​Best Practices

​Troubleshooting

​Quick Reference

​Scene Avatar Override Template

​Next Steps

Avatar Positioning

Create Avatar Video

API Reference

Background Settings

Overview

How It Works

Global vs Scene-Level Configuration

Common Use Cases

Use Case 1: Hide Avatar for Specific Scenes

Use Case 2: Reposition for Background Content

Use Case 3: Adjust Size for Emphasis

Use Case 4: Change Background Color by Scene

Use Case 5: Custom Positioning for Complex Layouts

Scene-Level Properties

Advanced Patterns

Pattern 1: Progressive Avatar Presence

Pattern 2: Split-Screen Effect

Pattern 3: Background-Adaptive Positioning

Pattern 4: Themed Scenes with Matching Avatar Style

Complete Example

Best Practices

Troubleshooting

Quick Reference

Scene Avatar Override Template

Next Steps