Guides

Add AI Avatar Video to Your SaaS: A Practical Guide

How to add AI avatar video to your SaaS: the data model, the API calls, webhooks, billing and the UX decisions that matter before you ship it to customers.

PitchTwin team, , 5 min read

Your customers want videos of a real person talking, and they want hundreds of them: one per prospect, per lesson, per new account. Recording each one by hand does not scale, and building your own video model is a research project, not a feature. This guide walks through what it takes to add AI avatar video to your SaaS with an API, from the first upload to the finished MP4 in your user's library.

Decide what the feature actually is

Before writing code, pin down three things, because they shape the integration more than the API does.

  • Who appears in the video. Your customer's own team (a sales rep, a trainer, a recruiter) or a stock presenter? If it is your customer's team, you need an onboarding step where they record or upload a clip of themselves, and you need their consent on file.
  • Where the words come from. Typed by the user, generated by an LLM from a template, or already voiced elsewhere (for example, your product already uses its own text-to-speech). This decides whether you send text or finished audio.
  • What happens after the video exists. Embedded in an email, posted to an LMS, downloaded as a file, captioned. This decides whether you need word timings and how long you keep the file.

The integration in four calls

With PitchTwin the whole flow is a small REST API. The base URL is https://pitchtwin.ai/api/v1 and every request carries Authorization: Bearer pt_live_…. Keep the key on your server; never ship it to a browser or mobile app.

1. Get the source clip in

If the clip is already at a public https URL, pass it directly. If it lives in your private storage or comes straight from the user's browser, request a one-time upload URL first:

curl -X POST https://pitchtwin.ai/api/v1/uploads \
  -H "Authorization: Bearer $PITCHTWIN_KEY"
# → { "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

Uploads are capped at 50 MB; clips passed by URL can be up to 200 MB. The source clip should be 10 to 120 seconds long.

2. Create the avatar once

const PT = "https://pitchtwin.ai/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.PITCHTWIN_KEY}`,
  "Content-Type": "application/json",
};

async function createAvatar(videoUrl: string, name: string) {
  let av = await fetch(`${PT}/avatars`, {
    method: "POST",
    headers,
    body: JSON.stringify({ name, video_url: videoUrl }),
  }).then((r) => r.json());

  while (av.status === "processing") {
    await new Promise((r) => setTimeout(r, 5000));
    av = await fetch(`${PT}/avatars/${av.id}`, { headers }).then((r) => r.json());
  }
  if (av.status !== "ready") throw new Error(av.error);
  return av; // store av.id and av.has_voice on your user record
}

The call returns 202 with status: "processing", which is the standard HTTP way of saying "accepted, not finished yet" (MDN on 202 Accepted). Store the avatar ID against your user. You create it once and reuse it for every video.

Two details are worth saving with it. has_voice tells you whether the avatar can speak text: the voice is cloned from the clip itself if it contains at least 10 seconds of speech, or from a separate voice_url sample. And each avatar is pinned to the engine version it was created with, so a customer's avatar will not change appearance because of an upgrade on our side.

3. Generate a video

Send exactly one of text, script or audio:

{
  "avatar_id": "av_3f9c1e7a2b4d6e80",
  "text": "Hi Mark, saw Acme just raised. Congrats! I have a quick idea for your onboarding.",
  "voice": { "speed": 1.0 },
  "webhook_url": "https://your.app/hooks/pitchtwin"
}

The response is 202 with { "id": "…", "status": "queued", … }. Use script instead of text when you need exact pauses, and audio when your product already produces the voice track. The guide on writing scripts for AI avatars covers pauses and pacing in detail.

4. Receive the result

When the video is done, PitchTwin POSTs { "type": "generation.succeeded", "data": { … } } to your webhook_url, signed with a PitchTwin-Signature: t=<unix>,v1=<hex> header. The signature is an HMAC-SHA256 (RFC 2104) of ${t}.${raw_body} using the webhook secret from Dashboard → API keys:

import crypto from "node:crypto";

function verify(rawBody: string, header: string, secret: string) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Webhooks are delivered once. Run a small reconciliation job that polls GET /generations/:id for anything still marked pending in your database after a while, so a missed delivery never leaves a user waiting forever. Details are in the webhooks docs.

The generation object gives you video_url (MP4), audio_url, words with word-level timings, duration_ms, tokens_charged and status.

Things that bite in production

video_url and audio_url are signed and expire after 24 hours. If your users come back to a video next week, copy the MP4 into your own storage when the webhook arrives, or fetch the generation again for a fresh link.

Phone footage is messy

Users will upload vertical iPhone clips in HEVC with rotation metadata. PitchTwin normalizes input on its side (rotation, HEVC to H.264, long side up to 1920 px, 25 fps), so you do not need an ffmpeg step before upload. You still want client-side checks for duration (10 to 120 seconds) and file size so users get a clear message instead of a failed job.

Text limits

A generation accepts up to 5,000 characters of text, 200 script segments and 50 pauses of at most 10 seconds each; audio can be up to 10 minutes. If your feature lets users paste long documents, split them before sending.

PitchTwin's Terms require every person in an avatar to have agreed to it. Build that into your onboarding: a checkbox and a record of who agreed and when is the minimum. If your users create avatars of other people (a manager uploading a rep's clip), make the consent step explicit.

Billing your customers

Your cost is per second of finished video. PitchTwin uses prepaid tokens that never expire: 1 token per second when you send your own audio, 1.5 tokens per second when PitchTwin voices the script. Packs run from $9 for 600 tokens to $149 for 12,000, which works out to $0.74 to $0.90 per minute with your own audio and $1.12 to $1.35 per minute with PitchTwin's voice. Failed generations are refunded automatically. See pricing for the full table.

Because tokens_charged comes back on every generation, you can meter usage per customer exactly and pass it through as credits, minutes or a plan allowance.

White-label by default

Output has no watermark and no PitchTwin branding, and videos are delivered to your webhook, so your customers only ever see your product. That matters if you resell video as part of your own plan.

Try it

Sign up at /signup to get 60 free tokens with no card, create an avatar from a short clip in the dashboard, and use the Playground to generate a test video and copy the equivalent request. When you are ready to wire it in, the quickstart has every call above.

Keep reading