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
- Ingest: write one row per video (from a CSV, CRM sync or trigger) into a
video_jobstable with statuspending. - Render scripts: fill the template per row and validate it against the API limits.
- Submit: a rate-controlled worker calls
POST /generationsand stores the returned generation ID. - Collect: a webhook endpoint receives
generation.succeededorgeneration.failedevents; a reconciliation poller catches anything the webhook missed. - Persist: a worker downloads the MP4 and audio to your own storage and marks the job
done. - 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.
Stage 5: copy files before the links expire
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:
- Download
video_url(MP4) and, if you use it,audio_url. - Upload both to your own bucket under a stable key such as
campaigns/<campaign_id>/<job_id>.mp4. - Save the
wordsarray alongside the file; word-level timings let you build captions later without another call. - Record
duration_msandtokens_chargedon 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 markfailedwith the error. - Generation failures (
generation.failedor a polled status offailed): 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 / month | Scale packs ($149 / 12,000) | Pack cost |
|---|---|---|---|
| Your own audio | 3,000,000 | 250 | $37,250 |
| PitchTwin voices the script | 4,500,000 | 375 | $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.