PitchTwin API reference
Turn a short clip of a real person into an avatar, then generate videos of them saying any text. Base URL: https://pitchtwin.ai/api/v1
Quickstart
Three calls: create an avatar once, then generate as many videos as you need.
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", … }curl https://pitchtwin.ai/api/v1/avatars/av_3f9c1e7a2b4d6e80 -H "Authorization: Bearer $PITCHTWIN_KEY"
→ 200 { "id": "av_3f9c1e7a2b4d6e80", "status": "ready", … }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! Got a quick idea for you.",
"webhook_url": "https://your.app/hooks/pitchtwin"
}'
→ 202 { "id": "9b1e…", "mode": "tts", "status": "queued", "estimated_seconds": 5, … }curl -X POST https://pitchtwin.ai/api/v1/generations -H "Authorization: Bearer $PITCHTWIN_KEY" -H "Content-Type: application/json" -d '{
"avatar_id": "av_3f9c1e7a2b4d6e80",
"audio": {
"url": "https://your.cdn/line-42.mp3",
"alignment": { "characters": ["H","i"], "start_times": [0, 0.09], "end_times": [0.09, 0.18] }
}
}'
→ 202 { "id": "4c7a…", "mode": "audio", "status": "queued", "tokens_charged": 4, … }When the video is ready we POST it to your webhook_url. You can also poll GET /generations/:id.
Authentication
Create a key in Dashboard → API keys and send it as a bearer token. Keys are secret: call the API from your server, never from a browser or mobile app.
Authorization: Bearer pt_live_…
Uploads
Avatars accept a public https URL. If your file isn't public, upload it to us first and pass the returned ref instead.
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",
"max_bytes": 52428800,
"expires_in": 7200
}
curl -X PUT "<upload_url>" -H "Content-Type: video/mp4" --data-binary @sarah.mp4Avatar v1 vs v2
There are two ways to create an avatar. Both give you the same avatar_id for POST /generations.
| v1 · from a clip | POST /avatars | You already have a 10–120 s video of the person. Send its URL, we build the avatar. Free. |
| v2 · guided call | POST /capture_sessions | You get a link for your user. They have a ~5 minute video call with Lily, our AI assistant: she interviews them about what you need to know, records a range of emotions and returns an avatar, a clean voice sample and a text profile of the person. 30 tokens per avatar. |
Use v2 when you onboard real people (creators, sales reps, experts): nobody has to film anything, the emotions are captured on purpose, and you learn about the person in the same call.
Avatars (v1)
An avatar is one person in one look: one source clip and one voice. Want a different outfit or background? Create another avatar. We normalize the clip (rotation, codecs, resolution) and keep a voice sample, which is used when you ask us to synthesize speech. Each avatar is tied to the engine version it was created with, so the output never changes silently.
| video_url | string | Required. https URL or upload:<file_id>. 10–120 s, one person facing the camera, talking. MP4/MOV, H.264 or HEVC. |
| voice_url | string | Optional. Separate voice sample (≥ 10 s, ideally 1–2 min of clean speech). By default we use the clip's own audio if it's at least 10 s. Only needed for text/script mode. |
| name | string | Optional. For your own reference. |
Returns 202 with status: "processing". It moves to ready or failed (see error).
{
"id": "av_3f9c1e7a2b4d6e80",
"object": "avatar",
"name": "Sarah — office",
"status": "ready", // processing | ready | failed
"error": null,
"width": 1080,
"height": 1920,
"duration_ms": 31040,
"has_voice": true, // false → only audio mode is available
"engine": "veed-lipsync@fal",
"created_at": "2026-09-26T12:00:00Z",
"ready_at": "2026-09-26T12:01:10Z"
}Every avatar has type: "v1" or "v2". Deleting an avatar removes it forever, together with all its generations. See Deleting data.
Avatars v2: capture sessions
Create a capture session from your server and send the returned url to your user (or redirect them). They open it on a laptop or a phone, press Start and talk to Lily. No buttons, no scripts to read: Lily asks questions by voice, figures out when they finished answering and asks follow-ups.
- Consent. The person repeats a consent phrase on camera.
- Interview, 1.5–2.5 min. Lily asks about what you put in
goal, with follow-up questions, in the context of your product (context). - Emotions. Smile, drive, serious, sad, surprise: whatever didn't show up naturally, Lily asks for with short tasks.
- Listening footage and a goodbye wave.
You don't have to wait for processing. Seconds after the call ends we POST avatar.created to your webhook_url with the avatar id, a photo (preview_image_url) and the profile: show the avatar to your user right away. You can already send POST /generations for it: the generation waits in queued and starts as soon as the avatar's video is built (with emotions, when the emotion clips are ready). When everything is done we POST avatar.ready with the voice sample and video links. If processing fails, waiting generations fail too and their tokens are refunded.
| context | string | Optional, ≤ 1500 chars. What your product does and what the avatar is for. Lily uses it to ask relevant questions. |
| goal | string | Optional, ≤ 1500 chars. What Lily should find out about the person. Without it she asks what they do, for whom, what works best and their plans. |
| orientation | string | "landscape" (default): a video-call layout, 16:9 avatar. "portrait": a vertical Reels-style screen and a 9:16 avatar. For portrait, ask people to use their phone. |
| language | string | Call language: "ru" (default) or "en". Lily speaks, listens and writes the profile in this language. More languages are coming. |
| name | string | Optional. For your own reference. |
| external_user_id | string | Optional. Your id for this person, returned on the session and the avatar. |
| webhook_url | string | Optional. https URL for avatar.created (seconds after the call: photo + profile) / avatar.ready / avatar.failed. |
| return_url | string | Optional. https URL: after the call we show a Back button to it. |
| branding | object | Optional. name, logo_url, accent (#hex), assistant_name, assistant_photo_url, powered_by (false hides "Powered by PitchTwin"). |
| expires_in_hours | integer | Optional. Link lifetime, 1–168, default 24. Each link can be used for one avatar. |
| mode | string | "hosted" (default): we return a url to our call page. "headless": we return a client_token for your own UI with our JS SDK. See Avatars v2: your own UI. |
| expires_in_minutes | integer | Optional, 10–10080. A short lifetime for headless tokens (instead of expires_in_hours). |
curl -X POST https://pitchtwin.ai/api/v1/capture_sessions \
-H "Authorization: Bearer $PITCHTWIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Anna — travel blog",
"external_user_id": "user_8841",
"orientation": "portrait",
"language": "ru",
"context": "Сервис делает Reels для Instagram с AI-аватаром блогера: блогер один раз записывается, дальше ролики генерируются по сценариям.",
"goal": "Узнать: о чём блог и какой он (экспертный, лайфстайл, юмор); кто аудитория; кто конкуренты или на кого ориентируется; какие рилсы снимает чаще (обзоры, мнение, провокация, сторителлинг) и что заходит лучше; тон общения; цель блога.",
"webhook_url": "https://your.app/hooks/pitchtwin",
"return_url": "https://your.app/onboarding/done",
"branding": { "name": "YourApp", "accent": "#8b5cf6" }
}'
→ 201 {
"id": "cs_5a1f0c9e2b7d4e31",
"object": "capture_session",
"status": "created",
"url": "https://pitchtwin.ai/capture/ct_…", // send this to the person; shown only once
"language": "ru",
"orientation": "portrait",
"avatar_id": null,
"expires_at": "2026-10-23T12:00:00Z",
…
}Session status: created → opened → uploading → processing → completed, or failed, expired, cancelled. Once the call is uploaded the session gets an avatar_id.
Deleting a session cancels a link that hasn't been used yet.
{
"id": "av_9d2e4b1c7a3f5e60",
"object": "avatar",
"type": "v2",
"status": "ready", // processing | ready | failed
"orientation": "portrait",
"language": "ru",
"external_user_id": "user_8841",
"session_id": "cs_5a1f0c9e2b7d4e31",
"width": 1080, "height": 1920,
"has_voice": true,
"preview_image_url": "https://…/preview.jpg", // photo of the person, same framing as the avatar; already set while processing
"profile": "Анна ведёт тревел-блог про Азию для девушек 25–35…\nТип блога: лайфстайл + полезные гайды\nАудитория: …\nКонкуренты: не выяснили\nЕщё: …",
"voice_sample_url": "https://…/voice.mp3", // clean speech of the person, up to 5 min, signed 24 h
"video_url": "https://…/video.mp4", // the avatar's driver clip
"recording_url": "https://…/recording.webm", // the full call as recorded
"emotions": ["neutral", "smile", "drive", "serious", "surprise", "sad", "listen"], // what you can pass in emotions[] of POST /generations
"clips": [ // parts of the recording by emotion, seconds
{ "emotion": "interview", "kind": "question", "start": 21.4, "end": 48.9, "good_s": 22.1 },
{ "emotion": "drive", "kind": "question", "start": 96.0, "end": 104.5, "good_s": 6.2 },
{ "emotion": "smile", "kind": "task", "start": 171.2, "end": 176.0, "good_s": 3.8 }
],
"transcript": [ { "who": "lily", "text": "…" }, { "who": "user", "text": "…" } ],
"context": "…", "goal": "…",
"created_at": "…", "ready_at": "…"
}profile is plain text: a short summary, then one line per item of your goal ("не выяснили" if it didn't come up), ready to paste into your prompts as context. Lily never asks for sensitive data (address, documents, payment details, health), even if goal mentions it.
Avatars v2: your own UI (headless)
Draw the whole recording screen in your design: camera preview, captions, Lily, progress, buttons. Our JS SDK runs the call in the browser and talks to our backend: Lily's voice, listening, the interview, emotion tracking, a lossless recording and the upload. You get events and send commands. The avatar is built exactly like with the hosted page, and avatar.ready arrives at your webhook.
- Your server creates a session with
"mode": "headless"and passes theclient_tokento the browser. Your API key never leaves your server. - Your page loads the SDK, calls
start()on a tap and renders the events.
curl -X POST https://pitchtwin.ai/api/v1/capture_sessions \
-H "Authorization: Bearer $PITCHTWIN_KEY" -H "Content-Type: application/json" \
-d '{ "mode": "headless", "orientation": "portrait", "context": "…", "goal": "…",
"expires_in_minutes": 60, "webhook_url": "https://your.app/hooks/pitchtwin" }'
→ 201 { "id": "cs_5a1f…", "mode": "headless", "client_token": "ct_9Qx…", "status": "created", … }The client_token opens only this one session. It stops working once the recording is uploaded or when the session expires, so it's safe in the browser.
import { createCapture, FILTERS } from "https://pitchtwin.ai/sdk/pitchtwin-capture.js";
// or copy pitchtwin-capture.js + pitchtwin-capture.d.ts into your project
const cap = createCapture({ token: clientToken });
cap.on("stream", ({ stream }) => { video.srcObject = stream; }); // <video muted playsinline>, mirror it with CSS
cap.on("lily", ({ status }) => setLily(status)); // speaking | listening | thinking | story | idle
cap.on("talking", ({ talking }) => pulse(talking)); // Lily's audio is playing right now
cap.on("caption", ({ text }) => setCaption(text)); // what Lily says → subtitles
cap.on("prompt", (p) => setCard(p)); // question | consent (+ phrase) | emotion_task (+ emotion) | story | outro
cap.on("step", ({ index, total, id }) => setStep(index, total)); // consent → interview → emotions → story → outro
cap.on("progress",({ elapsed, ratio }) => setProgress(elapsed, ratio));
cap.on("warning", ({ code, text }) => setWarning(text)); // no_face | too_dark | too_bright | noisy | network | low_res | null
cap.on("upload", ({ progress }) => setUpload(progress));
cap.on("done", ({ avatar_id }) => finish(avatar_id));
cap.on("error", ({ code, message, retryable }) => showError(message));
startButton.onclick = () => cap.start(); // must be a tap: browsers need a gesture for camera + sound| start() | command | Camera on, Lily greets the person and checks the frame. Then she waits for "let's go" by voice. |
| go() | command | Start recording now (your "Let's go" button). |
| pause() / resume() | command | Lily stops and the recording pauses. On resume she asks the current question again. |
| repeat() | command | Ask the current question or task again. |
| end() | command | Finish early. What is recorded is uploaded. |
| retry() | command | Upload again after a network error. |
| setFilter(id) / setMirror(on) | command | Preview them yourself with CSS (FILTERS[].css, scaleX(-1)); we apply the same look to the final avatar. The recording stays raw. |
| setVoice(on) | command | Lily's voice on/off. Captions keep coming. |
| destroy() | command | Stop everything and release the camera. |
| state | getter | phase, lily, step, warning, elapsed, avatar_id, error. |
phase goes idle → connecting → setup → recording ⇄ paused → uploading → done, or error. Error codes: invalid_session, session_expired, camera_denied (retryable: ask to allow the camera and call start() again), network_error, upload_failed (retryable), insufficient_tokens.
Why not a media stream to your servers? The camera is recorded in the browser at full sensor quality (up to 1080p, ~8 Mbit/s) and uploaded once at the end. A live WebRTC stream adapts to the network and would degrade the avatar on a weak connection. Only short answer clips go to us during the call, for speech recognition.
A full React example: CaptureScreen.tsx. Types: pitchtwin-capture.d.ts. Works in current Chrome, Safari (iOS 15+) and Firefox; on iOS use Safari or an in-app browser with camera access.
Deleting data
→ 200 { "id": "av_…", "object": "avatar", "deleted": true, "generations_deleted": 12 }Removes, permanently and immediately: the avatar, every generation made with it (videos and audio), and for v2 also the call recording, the voice sample, the profile, the transcript and the capture session. Voice clones at our TTS provider are deleted too. This cannot be undone. Use it when a person withdraws consent or asks to be forgotten. Billing records (token charges) are kept without any content.
Generations
| avatar_id | string | Required. A ready avatar. |
| text | string | We synthesize the speech. See Text & script. |
| script | array | We synthesize the speech, with pauses. See Text & script. |
| audio | object | You bring the audio (+ optional timings). See Your own audio. |
| voice.speed | number | Text/script only. 0.7–1.2, default 1. |
| voice.language | string | Text/script only. ISO 639-1 code, e.g. "en", "es", "ru". Leave it out for the best quality: the language is detected from the text. Set it only if detection gets it wrong (uses a faster, slightly lighter voice model). |
| emotions | array | Optional, v2 avatars only. Which emotion the person shows on each part of the audio. See Your own audio → Emotions. |
| webhook_url | string | Optional. https URL we POST the result to. |
Send exactly one of text, script or audio.
Returns 202. Status goes queued → synthesizing → rendering → succeeded, or failed. Audio mode skips synthesizing. Rendering usually takes several times the video's length.
How the video is put together. The video is always exactly as long as the speech. We build it from the avatar's own footage: the person keeps their natural head and body movement, and only the mouth is re-synced to the audio. Longer lines need more footage than the avatar clip has, so we add cuts, and we place them in the pauses between phrases (found from word timings, or from silence in the audio), the way a talking-head reel is edited. With emotions, the cuts happen at your segment boundaries instead, and each segment uses the clip with that emotion.
{
"id": "9b1e2c4a-…",
"object": "generation",
"avatar_id": "av_3f9c1e7a2b4d6e80",
"mode": "tts", // tts | audio
"status": "succeeded",
"video_url": "https://…/video.mp4", // signed, valid 24 h; fetch again for a fresh link
"audio_url": "https://…/audio.mp3", // the exact soundtrack of the video
"duration_ms": 5120,
"words": [ // word timings in seconds, e.g. for captions
{ "text": "Hi", "start": 0.0, "end": 0.18 },
{ "text": "Mark,", "start": 0.21, "end": 0.55 },
…
],
"tokens_charged": 8,
"error": null,
"input": { "text": "Hi Mark, …" },
"created_at": "…",
"finished_at": "…"
}Two modes
| text / script | 1.5 tokens / s | We synthesize the speech in the avatar's cloned voice, then render the video. The avatar needs has_voice: true. |
| audio | 1 token / s | You send finished audio, e.g. from your own ElevenLabs account, a recording or another TTS. The avatar speaks it as is. |
Both modes return the same generation object, including words: word-level timings of the final soundtrack. In text/script mode they come from our TTS. In audio mode they come from the alignment you send; without it, words is empty.
Text & script
Send the words one of two ways.
Plain text: the natural choice for most messages.
{ "avatar_id": "av_…", "text": "Hi Mark, saw Acme just raised. Congrats!" }Script: an array of segments, each optionally followed by a pause. Use it when timing matters: a beat after the name, a pause before the call to action.
{
"avatar_id": "av_…",
"script": [
{ "text": "Hi Mark,", "pause_after_ms": 400 },
{ "text": "saw Acme just raised. Congrats!", "pause_after_ms": 800 },
{ "text": "I've got a quick idea for your onboarding." }
]
}| script[].text | string | Required. What to say in this segment. |
| script[].pause_after_ms | integer | Optional. Exact silence after the segment, 0–10000 ms. The person keeps moving naturally during the pause; only the mouth is re-synced. |
Segments between pauses are voiced together, and each part hears its neighbours, so intonation flows across pauses. Up to 200 segments, 50 pauses and 5,000 characters per generation.
Your own audio
Send finished speech and the avatar will speak it. Timings are optional. If you send them, we check them against the audio and return them as words.
{
"avatar_id": "av_…",
"audio": {
"url": "https://your.cdn/line-42.mp3", // or "upload:<file_id>"
"alignment": {
"characters": ["H", "i", " ", "M", "a", "r", "k"],
"start_times": [0.00, 0.09, 0.18, 0.21, 0.30, 0.38, 0.46],
"end_times": [0.09, 0.18, 0.21, 0.30, 0.38, 0.46, 0.55]
}
}
}| audio.url | string | Required. https URL or upload:<file_id>. MP3, WAV, M4A, OGG… up to 10 min. |
| audio.alignment.characters | string[] | Optional. One entry per character, spaces included. |
| audio.alignment.start_times | number[] | Seconds from the start of the audio. Same length as characters. |
| audio.alignment.end_times | number[] | Seconds. Same length as characters. |
ElevenLabs' /with-timestamps output works as is: we also accept character_start_times_seconds and character_end_times_seconds. You pay for the exact length of the audio, charged when the request is accepted.
Emotions (avatars v2)
For a v2 avatar you can choose which emotion the person shows on each part of the audio. We take the matching clip from their call with Lily and cut between clips on your timings.
{
"avatar_id": "av_…",
"audio": { "url": "https://your.cdn/reel-17.mp3" },
"emotions": [
{ "start": 0.0, "end": 2.6, "emotion": "drive" },
{ "start": 2.6, "end": 8.0, "emotion": "neutral" },
{ "start": 8.0, "end": 11.4, "emotion": "smile" },
{ "start": 11.4, "end": 14.0, "emotion": "listen" }
]
}| emotions[].start / end | number | Seconds from the start of your audio. In order, no overlaps, end ≤ audio length. |
| emotions[].emotion | string | neutral | smile | drive | serious | surprise | sad | listen. Must be in the avatar's emotions list. |
neutral is the avatar's base clip. Gaps between segments and the tail after the last one are neutral. Cuts between emotions are hard cuts, like a talking-head reel. Works in audio and text modes; same price. Not available for v1 avatars (emotions_need_v2).
listen is the person silently listening: nodding, reacting, mouth closed. Use it where your audio has no speech (a pause, the other side of a dialogue, a reaction shot) and keep the audio silent on that segment: if there is speech there, the lips will move. Avatars recorded before 2026-10-25 get it too; it's missing only if the call had no listening part.
Webhooks
If you pass webhook_url, we POST the finished generation to it. Respond with any 2xx. Delivery is attempted once; if you miss it, poll GET /generations/:id.
POST https://your.app/hooks/pitchtwin
PitchTwin-Signature: t=1790430000,v1=5f2b…
{ "type": "generation.succeeded", "data": { …generation object… } }
// or "generation.failed", with data.error set and tokens refunded{ "type": "avatar.created", "data": { "session": { … }, "avatar": { …status "processing", preview_image_url, profile… } } }
{ "type": "avatar.ready", "data": { "session": { …capture session… }, "avatar": { …avatar v2 object… } } }
// or "avatar.failed": data.avatar.error is set and the 30 tokens are refundedVerify the signature with the webhook secret from Dashboard → API keys: HMAC-SHA256 of `${t}.${raw_body}`, hex-encoded.
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // 5 min tolerance
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}Tokens & balance
Tokens are charged per second of finished video: 1 token / s with your own audio, 1.5 tokens / s when we synthesize the speech. Audio mode is charged exactly up front. In text/script mode we hold an estimate and settle to the real length once the speech is ready. Failed generations are refunded in full.
Creating an avatar v2 costs 30 tokens, charged when the call is uploaded and refunded if processing fails. Avatars v1 are free.
→ 200 { "balance": 1840, "unit": "second_of_video" }Node.js example
The full flow for a product that already voices its users with ElevenLabs: create an avatar once, then send each line with its timestamps.
const PT = "https://pitchtwin.ai/api/v1";
const headers = { Authorization: `Bearer ${process.env.PITCHTWIN_KEY}`, "Content-Type": "application/json" };
async function pt(path: string, init: RequestInit = {}) {
const res = await fetch(PT + path, { ...init, headers });
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
return body;
}
// 1. once per user look
export async function createAvatar(videoUrl: string) {
let av = await pt("/avatars", { method: "POST", body: JSON.stringify({ video_url: videoUrl }) });
while (av.status === "processing") {
await new Promise((r) => setTimeout(r, 5000));
av = await pt(`/avatars/${av.id}`);
}
if (av.status !== "ready") throw new Error(av.error);
return av.id as string;
}
// 2. per line: pass ElevenLabs /with-timestamps output straight through
export async function renderLine(avatarId: string, audioUrl: string, elevenAlignment: object) {
return pt("/generations", {
method: "POST",
body: JSON.stringify({
avatar_id: avatarId,
audio: { url: audioUrl, alignment: elevenAlignment },
webhook_url: "https://your.app/hooks/pitchtwin",
}),
}); // → { id, status: "queued", … }; result arrives on your webhook
}Errors
Errors use standard HTTP status codes and a consistent body:
{ "error": { "code": "insufficient_tokens", "message": "This generation needs up to 14 tokens. Top up in the dashboard." } }| 400 | invalid_input | Send exactly one of text, script or audio. |
| 400 | invalid_text / invalid_script | Empty text, bad segment, or pause outside 0–10000 ms. |
| 400 | text_too_long / too_many_pauses | Over 5,000 characters or 50 pauses. |
| 400 | invalid_audio_url / unreadable_audio | Audio URL isn't https, can't be downloaded, or isn't decodable audio. |
| 400 | audio_too_long | Audio longer than 10 minutes. |
| 400 | invalid_emotions / emotions_need_v2 | Bad segment, overlap, unknown emotion or one this avatar doesn't have; or a v1 avatar. |
| 400 | invalid_alignment | Arrays differ in length, times go backwards, or run past the end of the audio. |
| 400 | invalid_speed / invalid_language | voice.speed outside 0.7–1.2, or language isn't an ISO 639-1 code. |
| 400 | invalid_video_url / invalid_webhook_url | Must be https (or upload:<id> for media). |
| 400 | unsupported_language / invalid_orientation | Capture sessions: language must be "ru" or "en"; orientation is landscape or portrait. |
| 400 | invalid_context / invalid_goal / brief_too_long | Capture sessions: strings up to 1500 characters. |
| 401 | invalid_api_key | Missing, wrong or revoked key. |
| 402 | insufficient_tokens | Top up in Billing. Capture sessions need 30 tokens on the balance. |
| 404 | not_found / avatar_not_found / upload_not_found | No such object on your account. |
| 409 | avatar_not_ready | Avatar failed, or a v1 avatar is still processing. (v2 avatars in processing accept generations: they wait in queued.) |
| 409 | session_has_avatar | The capture session already produced an avatar: delete the avatar instead. |
| 409 | avatar_has_no_voice | Text/script mode needs a voice sample. Send audio instead, or recreate the avatar with voice_url. |
| 500 | internal_error | Our fault. Safe to retry. |
Every call is visible in Dashboard → Logs.
Limits
- Source clip: 10–120 s, up to 200 MB by URL or 50 MB by upload.
- Voice sample: at least 10 s of clean speech (1–2 min gives the best clone).
- Text/script: up to 5,000 characters, 200 segments, 50 pauses, 10 s per pause.
- Audio: up to 10 minutes.
- Avatar v2 call: about 5 minutes; links live 24 h by default (1–168 h), one avatar per link. Chrome, Safari or Edge on a laptop or phone, with camera and microphone.
- Video and audio links are signed and expire after 24 h. Fetch the generation again for a fresh link.
Changelog
| 2026-11-01 | capture SDK 1.2.0 | Faster call: Lily answers sooner after the person finishes (shorter end-of-turn pause, one round trip per interview turn started during the pause, quick acknowledgements). Interview questions now often include examples from the person's niche. Rebuild or re-download pitchtwin-capture.js to get it; older SDK versions keep working. |
| 2026-10-30 | avatar v2 | No more waiting for the avatar: avatar.created arrives seconds after the call with preview_image_url (a photo) and the profile, and POST /generations is accepted while the avatar is processing (the generation waits in queued, response has waiting_for_avatar: true). |
| 2026-10-25 | emotions | New emotion listen: the person silently listening, for pauses and reaction shots. Voice samples of v2 avatars are now up to 5 min (were 2) for a closer voice clone. |
| 2026-10-25 | avatar v2 | Capture sessions in English: language: "en". Lily runs the whole call, the emotion tasks and the profile in English. |
| 2026-10-22 | headless | Avatars v2 in your own UI: POST /capture_sessions with mode: "headless" returns a client_token; the JS SDK (/sdk/pitchtwin-capture.js) runs the call and emits events (Lily speaking/listening, captions, steps, progress, warnings, upload) and takes commands (pause, resume, repeat, end). |
| 2026-10-22 | emotions | POST /generations accepts emotions[] for v2 avatars: per-segment emotion (smile, drive, serious, surprise, sad, neutral) taken from the person's recording. GET /avatars/:id returns the available emotions. |
| 2026-10-22 | avatar v2 | POST /capture_sessions: a hosted call with AI assistant Lily → avatar, voice sample, text profile (context, goal, orientation, language). Avatars get type v1 | v2. |
| 2026-10-22 | deletion | DELETE /avatars/:id now also deletes all generations of the avatar and, for v2, the recording, profile and transcript. Permanent. |
| 2026-09-26 | audio mode | POST /generations accepts audio + optional character alignment (ElevenLabs format supported), billed at 1 token/s. |
| 2026-09-26 | words | Generations return word timings (words) and the exact soundtrack (audio_url). |
| 2026-09-26 | has_voice | Avatars no longer need a voice sample; has_voice tells you if text/script mode is available. |
| 2026-09-26 | pricing | Text/script mode is billed at 1.5 tokens/s. |
| 2026-09-26 | voice | voice.speed is now 0.7–1.2; voice.language takes ISO 639-1 codes ("en"). |
| 2026-09-26 | v1 | Avatars, uploads, generations (text / script with pauses), webhooks, balance. |