You have a short clip of a real person, maybe a founder, a sales rep or a course instructor, and you want to generate new videos of them saying anything. The question is what that clip needs to look like, how to get it into an API, and how to know the avatar is ready to use. This guide covers the full path, from raw phone footage to a tested avatar ID you can generate with.
Why build the avatar from real video
There are two broad ways to make a talking avatar. One re-generates the person's face with a model, which tends to smooth out skin, hair and lighting into something slightly "plastic". The other keeps the real footage and changes only what the new speech requires.
PitchTwin takes the second route: the avatar is built from real video of the person and keeps that footage, so the output looks 1:1 like them, with their own skin texture, hair, lighting and expressions. The consequence for you is simple: the avatar looks exactly as good as the clip. Most of the work in this guide is getting a good clip in.
Step 1: Check the clip
Requirements for a source clip:
| Requirement | Value |
|---|---|
| Length | 10 to 120 seconds |
| Size | Up to 200 MB by URL, up to 50 MB by upload |
| Content | One person facing the camera, talking |
| Format | MP4 or MOV, H.264 or HEVC |
You do not need to pre-process phone footage. PitchTwin normalizes input on its side: it corrects phone rotation, converts HEVC to H.264, scales the long side to at most 1920 px and sets 25 fps.
What you do need is good footage. The companion post on recording a clip that makes a great AI avatar covers framing, light, sound and what to say. The short version: steady camera, even light on the face, the person talking naturally for most of the clip.
Remember that one avatar is one look. The outfit, background and framing in the clip are what every generated video will show. If a customer wants a studio version and a home-office version, that is two clips and two avatars.
Step 2: Get the file to the API
If the clip already sits at a public https URL, skip this step and pass that URL as video_url.
If it is in private storage or comes from a user's browser, request a one-time upload URL, then PUT the file to it:
curl -X POST https://pitchtwin.ai/api/v1/uploads \
-H "Authorization: Bearer $PITCHTWIN_KEY"
# → 201 { "file_id": "0f2c…", "ref": "upload:0f2c…", "upload_url": "https://…", "method": "PUT", … }
curl -X PUT "<upload_url>" \
-H "Content-Type: video/mp4" \
--data-binary @sarah.mp4
The file is now referenced as upload:<file_id>, which you can pass anywhere the API expects a media URL.
Step 3: Decide where the voice comes from
An avatar can have a cloned voice, which it needs for text and script mode (where PitchTwin synthesizes the speech). There are three options:
- Clone from the clip. If the clip contains at least 10 seconds of speech, the voice is cloned from it automatically. This is the easiest path.
- Clone from a separate sample. Pass
voice_urlwith a clean recording of the person. One to two minutes of speech gives the best clone. Use this when the clip's audio is noisy or mostly silent. - No voice. If you will always send finished audio (for example from your own ElevenLabs account), you do not need a voice at all. The avatar is created with
has_voice: falseand works in audio mode only.
Step 4: Create the avatar
curl -X POST https://pitchtwin.ai/api/v1/avatars \
-H "Authorization: Bearer $PITCHTWIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sarah — office",
"video_url": "upload:0f2c…",
"voice_url": "https://example.com/sarah-voice.m4a"
}'
# → 202 { "id": "av_3f9c1e7a2b4d6e80", "status": "processing", … }
name is for your own reference; voice_url is optional. The response is 202 with status: "processing".
Step 5: Wait until it is ready
Poll GET /avatars/:id until the status leaves processing. In Python:
import os
import time
import requests
PT = "https://pitchtwin.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PITCHTWIN_KEY']}"}
def wait_for_avatar(avatar_id: str) -> dict:
while True:
av = requests.get(f"{PT}/avatars/{avatar_id}", headers=HEADERS).json()
if av["status"] != "processing":
break
time.sleep(5)
if av["status"] != "ready":
raise RuntimeError(av.get("error"))
return av
avatar = wait_for_avatar("av_3f9c1e7a2b4d6e80")
print(avatar["id"], avatar["has_voice"])
Store the avatar id and has_voice against the person in your database. If has_voice is false, route that avatar's generations to audio mode in your code instead of letting a text request fail.
Step 6: Generate a test video
Before you hand the avatar to a customer, render something short and look at it at full size:
curl -X POST https://pitchtwin.ai/api/v1/generations \
-H "Authorization: Bearer $PITCHTWIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"avatar_id": "av_3f9c1e7a2b4d6e80",
"script": [
{ "text": "Hi, this is a quick test.", "pause_after_ms": 600 },
{ "text": "If you can see this, the avatar is working." }
]
}'
# → 202 { "id": "9b1e…", "status": "queued", … }
Poll GET /generations/:id until status is succeeded or failed, then download video_url. Check three things: does it look like the person, does the voice sound like them, and does the pause land where you expect. If the likeness is off, the fix is almost always a better clip, not a setting. Failed generations are refunded in full automatically.
If you would rather not write code yet, the dashboard lets you upload an avatar from the browser and generate test videos in the Playground, which also shows the equivalent cURL or Node request.
Managing avatars over time
GET /avatarslists every avatar on your account.DELETE /avatars/:idremoves the avatar and also deletes its cloned voice. Wire this to your own "delete my data" flow.- Each avatar is pinned to its engine version. There are no silent upgrades, so the face your customer approved in week one is the face they get in month six. If you want to move an avatar to a newer engine later, create a new avatar from the same clip and let the customer compare.
Consent
PitchTwin's Terms require that every person in an avatar has agreed to it. If your users upload clips of colleagues or clients, ask for that agreement in your product and keep a record of it.
Try it
Create a free account at /signup to get 60 free tokens, no card needed, and make your first avatar from a phone clip in the dashboard. The quickstart covers the same calls, and the avatar from video page explains the approach in more detail.