Overview
A personalized video is a normal create request with a script written for one person. Your code builds the script from your own data (name, company, plan, numbers), sends it to a format endpoint such asPOST /v1/project/create/talking-avatar or POST /v1/project/create/script-to-video, and tags the project with metadata so you know who the finished video is for.
metadata.
Choosing a format
Types of personalization
1. Basic information
Names, companies, roles, cities. Keep values short and in the form you would say them out loud.2. Metrics and data
Numbers from your product make a video feel specific:"twelve" or "12" both work, but "12.000000" or "1.2e1" will be read literally.
3. Conditional content
Choose the text in your code and send the finished script:4. Different look per audience
When the look should change too (a different avatar, voice or visual style per industry), keep a small map in your code and pick the ids from it:GET /v1/avatar/list and GET /v1/voice/list once and keep them in your config.
Advanced strategies
Personal visuals
Withscript-to-video and mediaType: "media", the video uses files from your team’s media library. Add a file per customer (their logo, their product photos) with Import Media from URL or Upload Media, keep the media ids next to the customer record, and send them per request:
400 media: Media "..." not found.
Avatar intro, shared demo
Withscenes, only the first scene needs to be personal. The rest can be the same footage for everybody:
Integration with CRM data
Map CRM fields in one place and provide fallbacks for missing data:metadata so the webhook tells you which contact the finished video belongs to:
A/B testing
Create two versions of the script and tag each withmetadata. When the webhook arrives, store the video against the variant and measure results on your side.
Best practices
1. Write for the ear
The script is spoken. Read it out loud with real values in place. Avoid abbreviations and symbols the voice may read oddly.2. Do not overdo it
One or two personal details per video feels natural. A name in every sentence does not.3. Provide defaults
A missing value leaves a gap in the sentence (“Hi , welcome”). Give every field a fallback before you build the script:4. Validate data quality
talking-avatar, ugc-studio/* and script-to-video; 5,000 per scene in scenes). In talking-avatar, ugc-studio/* and script-to-video, text that looks like code is refused with 400 script: Contains potentially dangerous content that is not allowed.: HTML tags such as <script> or <iframe>, text between backticks, $(...), ../, control characters, and SQL-like fragments such as ' OR '1. The same check runs on name in talking-avatar and ugc-studio/*. Clean these out of your data before you build the script, or one bad record fails its request.
Real-world examples
Sales outreach
talking-avatar with metadata: { leadId: lead.id }, and put the video link in your outreach email once the webhook arrives.
Customer onboarding
Create a video when a user signs up, with their name and plan, and send it in your welcome email once the webhook arrives.Event invitations
Say the guest’s name, the event date and the city. Write the date as you want it spoken:"Thursday, October ninth" rather than "2026-10-09".
Checklist
1
Format and ids chosen
You know which endpoint you call and have the avatar, voice and media ids from the list endpoints.
2
Every value filled
Defaults for missing data; no gaps or raw field names left in the script.
3
Values read well
Names capitalized, numbers and dates written as they should sound.
4
Tracking in place
metadata carries your own ids, and a webhook or polling loop stores the result.5
Tested on a few records
Create a handful and watch them before sending a whole list.
Next steps
Bulk Generation
Create videos for many recipients
Creating videos
Every create endpoint and what it makes