Guides

Create an AI Avatar From Video: A Step-by-Step Guide

Create an AI avatar from a short video of a real person: clip requirements, uploads, voice cloning, polling and testing, with working cURL and Python examples.

PitchTwin team, , 5 min read

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:

RequirementValue
Length10 to 120 seconds
SizeUp to 200 MB by URL, up to 50 MB by upload
ContentOne person facing the camera, talking
FormatMP4 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:

  1. 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.
  2. Clone from a separate sample. Pass voice_url with 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.
  3. 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: false and 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 /avatars lists every avatar on your account.
  • DELETE /avatars/:id removes 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.

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.

Keep reading