What You’ll Learn
Template Variables
Add placeholder variables to your project using double curly brackets
Get Project ID
Find the project ID from the Pictory App URL
API Integration
Use the API to render videos with variable substitution
Personalization at Scale
Generate personalized videos for different audiences
Before You Begin
Make sure you have:- A Pictory account with an existing project (create one here)
- A Pictory API key (get one here)
- Node.js or Python installed on your machine
- Basic understanding of API calls
How Template Variables Work
Template variables are placeholders in your project that get replaced with actual values when you render the video. You define them using double curly brackets syntax:{{variableName}}.
Variable Syntax
| Syntax | Description |
|---|---|
{{Name}} | Simple variable that will be replaced with a name |
{{Year}} | Variable for dynamic year content |
{{CompanyName}} | Variable for company-specific content |
{{ProductName}} | Variable for product names |
- Scene subtitles/text
- Any text element in your project
Step-by-Step Guide
Step 1: Create a Template Project in Pictory App
- Open the Pictory App and create a new project or open an existing one
- In your scene text, add template variables using double curly brackets
- Design your video with visuals, transitions, and any other elements you want

{{Year}}- Will be replaced with the target year (e.g., “2026”){{Name}}- Will be replaced with the recipient’s name (e.g., “James Thomas”)
Step 2: Get the Project ID
Once your template project is ready, you need to get its project ID to use with the API.- Open your project in the Pictory App
- Look at the browser address bar - the URL will look like:
- The project ID is the long string after
/story/:

The project ID is a unique identifier for your project. Copy this ID exactly as shown - it’s case-sensitive and must be complete.
Step 3: Render Video from Template via API
Now use the API to create videos from your template by providing the project ID astemplateId and the variable values:
Understanding the API Request
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | Yes | The project ID from the Pictory App URL |
name | string | Yes | Name for the generated video |
variables | object | Yes | Key-value pairs for template variable substitution |
Variables Object
Thevariables object contains key-value pairs where:
- Key: The variable name (without curly brackets) - must match exactly what you used in your template
- Value: The string to replace the variable with
{{Name}}→James Thomas{{Year}}→2026
Response
Generating Personalized Videos at Scale
The real power of template-based video creation is generating personalized videos for many recipients:Common Use Cases
Personalized Greetings
Product Promotions
Event Invitations
Customer Onboarding
Best Practices
Design Templates for Reusability
Design Templates for Reusability
- Keep variable names generic and reusable
- Use placeholders that make sense for your use case
- Test your template with different variable values to ensure proper text fitting
- Consider text length limits when designing scenes with variables
Manage Variable Consistency
Manage Variable Consistency
- Document all variables used in your template
- Use consistent naming conventions across templates
- Validate variable values before sending to API
- Handle special characters appropriately in variable values
Optimize for Scale
Optimize for Scale
- Use webhooks for notification when videos complete
- Process videos in batches for large campaigns
- Store job IDs for tracking and retrieval
- Implement retry logic for failed jobs
Test Before Production
Test Before Production
- Create test videos with sample data before mass generation
- Verify all variables are replaced correctly
- Check video quality and timing with different text lengths
- Confirm the output meets your quality standards
Troubleshooting
Variable not being replaced
Variable not being replaced
Problem: Template variable appears as
{{Name}} instead of the actual value.Solution:- Ensure the variable name in your
variablesobject matches exactly (case-sensitive) - Check for typos in the variable name
- Verify the variable exists in the template project
- Make sure there are no extra spaces in the variable name
Invalid templateId error
Invalid templateId error
Problem: API returns an error about invalid template ID.Solution:
- Verify you copied the complete project ID from the URL
- Check that the project exists in your Pictory account
- Ensure you’re using the correct API key associated with the account
- Confirm the project is accessible (not deleted or archived)
Text overflow or cut off
Text overflow or cut off
Problem: Replaced variable text is too long and gets cut off.Solution:
- Design templates with maximum expected text length in mind
- Use shorter variable values or abbreviations
- Adjust font size in the template to accommodate longer text
- Consider using multiple scenes for longer content
Job stuck in progress
Job stuck in progress
Problem: Video job remains in-progress for extended time.Solution:
- Check the job status using the Get Job API
- Verify your API subscription is active
- Contact support if job is stuck for over 30 minutes
- Retry with a new request if needed
Next Steps
Enhance your template-based workflows with these features:Add Voice-Over
Add AI narration to your template videos
Apply Branding
Consistent brand styling across all generated videos
Background Music
Add background music to enhance your videos
Save Projects
Save generated videos as editable projects
