Engineering

Personalized Video at Scale: 100k Videos a Month

An architecture for personalized video at scale: job queues, webhooks, polling fallback, storage and token budgeting for 100,000 avatar videos a month.

PitchTwin team, , 6 min read

Generating one avatar video is a single API call. Generating 100,000 a month, each with a different name, company and offer, is a systems problem: requests must be throttled, results collected reliably, files stored before links expire, and the bill kept predictable. This post walks through an architecture for that volume.

The examples use the PitchTwin API, but the shape applies to any asynchronous video generation service.

What 100,000 videos a month actually means

Start with the arithmetic, because it drives every design choice.

  • 100,000 videos a month is roughly 3,300 a day. Traffic is bursty: a sales team uploads a 5,000-row list at 9 a.m. and expects results by lunch.
  • If the average video is 30 seconds, that is 3,000,000 seconds of video a month.
  • Video generation is asynchronous. You submit a job, receive an ID, and the finished file arrives later.

So you need to absorb bursts, learn reliably when each job finishes, and store the output durably.

The pipeline at a glance

  1. Ingest: write one row per video (from a CSV, CRM sync or trigger) into a video_jobs table with status pending.
  2. Render scripts: fill the template per row and validate it against the API limits.
  3. Submit: a rate-controlled worker calls POST /generations and stores the returned generation ID.
  4. Collect: a webhook endpoint receives generation.succeeded or generation.failed events; a reconciliation poller catches anything the webhook missed.
  5. Persist: a worker downloads the MP4 and audio to your own storage and marks the job done.
  6. Deliver: show, email or post the video to a CRM.

Every stage reads and writes one jobs table, so any worker can restart without losing state.

Stage 1: the jobs table

Keep it boring. A single table is enough at this volume.

create table video_jobs (
  id              uuid primary key,
  campaign_id     uuid not null,
  avatar_id       text not null,
  script          jsonb not null,
  status          text not null default 'pending',
  generation_id   text unique,
  video_path      text,
  attempts        int not null default 0,
  last_error      text,
  created_at      timestamptz default now(),
  updated_at      timestamptz default now()
);
create index on video_jobs (status, created_at);

Statuses move in one direction: pending → submitted → succeeded / failed → stored. The unique generation_id makes webhook handling idempotent: processing the same event twice updates the same row.

Stage 2: render and validate scripts before you spend tokens

Most failures at scale are input errors: an empty first name, a 7,000-character script, a pause that is too long. Catch them before submission. The API accepts exactly one of text, script or audio; script lets you control pacing with pause_after_ms:

{
  "avatar_id": "av_123",
  "script": [
    { "text": "Hi Maria, I took a look at Northwind's onboarding flow.", "pause_after_ms": 400 },
    { "text": "There's one step I think we could cut entirely.", "pause_after_ms": 0 }
  ],
  "voice": { "speed": 1.0, "language": "en" },
  "webhook_url": "https://app.example.com/hooks/pitchtwin"
}

Validate against the documented limits in your worker: text up to 5,000 characters, up to 200 segments, up to 50 pauses, and no pause longer than 10 seconds. Speed must be between 0.7 and 1.2. Reject or fix the row before it reaches the API, and record why in last_error.

Stage 3: submit with your own concurrency control

Do not loop over 5,000 rows and fire 5,000 requests at once. Put a worker in front of the API that pulls a small batch of pending jobs, submits them with bounded concurrency, and backs off on errors.

import pLimit from "p-limit";

const API = "https://pitchtwin.ai/api/v1";
const limit = pLimit(8); // tune for your workload

async function submit(job: Job) {
  const res = await fetch(`${API}/generations`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PITCHTWIN_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      avatar_id: job.avatar_id,
      script: job.script,
      webhook_url: "https://app.example.com/hooks/pitchtwin",
    }),
  });

  if (res.status !== 202) {
    await markRetry(job, `HTTP ${res.status}: ${await res.text()}`);
    return;
  }
  const { id } = await res.json(); // { id, status: "queued" }
  await db.videoJobs.update(job.id, { status: "submitted", generation_id: id });
}

export async function submitBatch(jobs: Job[]) {
  await Promise.all(jobs.map((j) => limit(() => submit(j))));
}

Treat the concurrency number as a dial, and discuss sustained throughput with your provider before launch.

Before each batch, call GET /balance and stop submitting when the remaining tokens would not cover the batch.

Stage 4: webhooks first, polling as a safety net

Webhooks are the primary channel; polling thousands of jobs during a burst is wasteful. PitchTwin sends a POST with { "type": "generation.succeeded" | "generation.failed", "data": {...} } and a PitchTwin-Signature: t=<unix>,v1=<hex> header.

Verify the signature against the raw body before trusting anything in it:

import crypto from "node:crypto";

export function verify(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Also reject events whose t is too old, which limits replay attacks. The full walkthrough, including Python, is in how to verify HMAC webhook signatures.

Keep the handler small: verify, update the row by generation_id, enqueue a storage job, return 200.

The important detail: PitchTwin delivers each webhook once. If your endpoint is down during a deploy, that event is gone. So run a reconciliation poller every few minutes that selects jobs stuck in submitted for longer than you expect and calls GET /generations/:id for each. The response carries the same fields as the webhook payload (status, video_url, audio_url, words, duration_ms, tokens_charged), so both paths can share one update function. The webhooks section of the docs covers the payload in detail.

Video and audio links returned by the API are signed and expire after 24 hours, which is too short for a video embedded in an email opened next week.

The storage worker should:

  1. Download video_url (MP4) and, if you use it, audio_url.
  2. Upload both to your own bucket under a stable key such as campaigns/<campaign_id>/<job_id>.mp4.
  3. Save the words array alongside the file; word-level timings let you build captions later without another call.
  4. Record duration_ms and tokens_charged on the job for cost reporting.

Serve stored files through your CDN. The output carries no watermark or provider branding.

Stage 6: failures and retries

Separate two kinds of failure:

  • Submission failures (non-202 responses, network errors): retry with exponential backoff, up to a fixed number of attempts, then mark failed with the error.
  • Generation failures (generation.failed or a polled status of failed): inspect the error, fix the input if possible, and resubmit as a new generation. Failed generations are refunded in full automatically, so a retry does not double-charge you.

Show failures in plain language: "3 of 500 videos failed because the first name was empty".

Budgeting 100,000 videos

PitchTwin bills in prepaid tokens that never expire: 1 token per second of video when you bring your own audio, 1.5 tokens per second when it voices the script in the avatar's cloned voice.

Scenario (30 s average)Tokens / monthScale packs ($149 / 12,000)Pack cost
Your own audio3,000,000250$37,250
PitchTwin voices the script4,500,000375$55,875

At this volume, ask about Volume or Platform deals; the pack prices above are list prices from the pricing page. Two levers matter more than any discount:

  • Shorter scripts. A 20-second video costs two thirds of a 30-second one. Personalized videos rarely need to be long.
  • Bring your own audio if you already generate speech; audio mode is 1 token per second.

Avatar consistency across a long campaign

A long campaign needs the avatar to look the same in week 12 as in week 1. Each PitchTwin avatar is pinned to its engine version, so no silent upgrade changes a face mid-campaign, and because avatars keep the original footage of the person, every video looks 1:1 like them.

Try it

Build and test this pipeline on the free tier: sign up for 60 free seconds with no card, create one avatar, and send a few generations to a test webhook. The docs have the full reference.

Keep reading