Skip to main content

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 as POST /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.
The avatar says “Hi Sarah, welcome to TechCorp! …”. When the video is ready, the webhook (or Get Project) gives you the URL and the same 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:
Format numbers for speech before sending: "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 the ids from GET /v1/avatar/list and GET /v1/voice/list once and keep them in your config.

Advanced strategies

Personal visuals

With script-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:
A media id that is not in your team’s library answers 400 media: Media "..." not found.

Avatar intro, shared demo

With scenes, only the first scene needs to be personal. The rest can be the same footage for everybody:
See Scenes for every scene type and its fields.

Integration with CRM data

Map CRM fields in one place and provide fallbacks for missing data:
Put the CRM record id in 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 with metadata. 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

The finished script must stay within the format’s limit (10,000 characters for 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

Send it to 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