Guides

What Is an AI Avatar API? A Guide for Developers

What an AI avatar API is, how it works under the hood, what the requests look like and what to check before you build a product on one. Written for developers.

PitchTwin team, , 5 min read

You are building a product that needs videos of a person talking: a sales tool, a training platform, an onboarding flow. You have seen avatar video in demos, but it is not obvious what an "AI avatar API" actually gives you, which parts you still build yourself, and how to tell providers apart. This post explains the moving parts in plain terms.

The short definition

An AI avatar API is an HTTP service that turns a person and a script into a video of that person saying the script. You make two kinds of requests:

  1. Create an avatar: send footage (or sometimes a photo) of a person. The provider prepares a reusable avatar and, often, a cloned voice.
  2. Generate a video: send the avatar's ID plus text or audio. The provider renders an MP4 of the avatar speaking it.

Everything else (uploads, webhooks, billing, word timings) exists to make those two calls practical in a real product.

What happens behind the API

Avatar creation

Providers take different approaches here, and the approach decides how the output looks.

  • Re-generated faces. The model learns the person's appearance and draws the face frame by frame. This gives flexibility (new poses, new angles) but can produce a smoothed, slightly "plastic" look: skin texture, hair and lighting drift toward an average.
  • Built from real video. The avatar keeps the original footage of the person and generates only what has to change for the new speech. Skin, hair, lighting and the person's own expressions come from the real recording, so the result looks 1:1 like the person. The trade-off is that the avatar looks the way the clip looks: a different outfit or background means a new clip.

PitchTwin uses the second approach. It is a good fit when the person in the video is your customer's own rep, trainer or recruiter and the people watching know what they look like.

Voice

To speak text, the avatar needs a voice. Most APIs clone one from a sample. With PitchTwin, the voice is cloned from the clip itself if it has at least 10 seconds of speech, or from a separate sample (1 to 2 minutes gives the best clone). If you already produce speech elsewhere, you can skip voice entirely and send finished audio.

Rendering

Rendering video takes real compute, so generation is asynchronous. The API accepts the job, returns 202 (MDN: 202 Accepted) with a job ID, and you either poll for the result or receive it on a webhook.

What the requests look like

Here is a minimal PitchTwin flow. The base URL is https://pitchtwin.ai/api/v1.

Create an avatar from a clip:

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": "https://example.com/sarah.mp4" }'
# → 202 { "id": "av_3f9c1e7a2b4d6e80", "status": "processing", … }

Poll GET /avatars/:id until status is ready. Then generate:

curl -X POST https://pitchtwin.ai/api/v1/generations \
  -H "Authorization: Bearer $PITCHTWIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_id": "av_3f9c1e7a2b4d6e80",
    "text": "Hi Mark, saw Acme just raised. Congrats!",
    "webhook_url": "https://your.app/hooks/pitchtwin"
  }'
# → 202 { "id": "9b1e…", "status": "queued", … }

When the job finishes, the generation object contains:

FieldWhat it is
video_urlThe MP4, behind a signed link that expires after 24 hours
audio_urlThe exact soundtrack of the video
wordsWord-level timings, useful for captions and highlighting
duration_msLength of the video
tokens_chargedWhat this video cost
statusqueued, rendering, succeeded or failed

Text mode vs audio mode

A good avatar API lets you choose who produces the speech.

  • Text or script mode. You send words; the provider synthesizes them in the avatar's cloned voice. PitchTwin accepts plain text, or a script array of { text, pause_after_ms } segments when you need exact pauses. You can set voice.speed (0.7 to 1.2) and voice.language as an ISO 639-1 code such as en.
  • Audio mode. You send finished audio, for example from your own ElevenLabs account, and the avatar speaks it as is. You can include character-level alignment; ElevenLabs' /with-timestamps output is accepted without conversion.

Audio mode matters if you already have a voice pipeline, a preferred TTS vendor, or recorded human voiceover. It is also cheaper on PitchTwin: 1 token per second of video instead of 1.5.

What to evaluate before you commit

Likeness

Generate a test video of someone you know well and watch it at full size. Look at skin texture, hair edges and whether the expressions feel like that person. Your customers will do exactly this with their own faces.

Consistency over time

If the provider upgrades its model, does your customer's avatar change? PitchTwin pins each avatar to its engine version: no silent upgrades, so faces do not drift between last month's videos and this month's.

White-label

If the videos go out under your brand, check for watermarks, provider logos and provider-hosted player pages. PitchTwin output has no watermark or branding and is delivered to your webhook.

Pricing model

Avatar APIs bill per second or per minute of video, but the packaging differs: monthly plans with included minutes, prepaid wallets, or prepaid credits. Work out your cost per video at your expected volume, including failed jobs and any minimums. PitchTwin uses prepaid tokens that never expire, with no seats or subscription, and refunds failed generations automatically; see pricing. We also maintain a pricing comparison across providers.

Developer experience

Read the docs end to end before you sign up. You want clear limits, a predictable error format, signed webhooks and a way to test without writing code. PitchTwin's dashboard has a Playground that generates test videos and shows the equivalent cURL or Node request.

Where established providers are strong

HeyGen, Synthesia and Tavus all offer APIs and are mature products. HeyGen's API covers several avatar types, including digital twins built from video and photo avatars (G2 on HeyGen API pricing). Synthesia offers API access from its Creator plan, though not every avatar type is API-compatible (overview of Synthesia pricing). Tavus also covers real-time conversational video agents, which PitchTwin does not (Tavus pricing). If your product needs photo avatars, live conversation, or avatar types beyond "this specific person on camera", one of them may fit better. If you need a B2B API where every video looks like the real person in your customer's clip, under your own brand, that is what PitchTwin is built for.

Try it

You get 60 free tokens on signup, no card required. Create an avatar from a short clip in the dashboard, generate a test video in the Playground, then read the docs when you are ready to integrate.

Keep reading