API reference

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, … }

Authorization: Bearer pt_live_…

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.mp4

{
  "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": "latentsync@fal",
  "created_at": "2026-09-26T12:00:00Z",
  "ready_at": "2026-09-26T12:01:10Z"
}

{
  "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": "…"
}

{ "avatar_id": "av_…", "text": "Hi Mark, saw Acme just raised. Congrats!" }

{
  "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." }
  ]
}

{
  "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]
    }
  }
}

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

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));
}

→ 200 { "balance": 1840, "unit": "second_of_video" }

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
}

{ "error": { "code": "insufficient_tokens", "message": "This generation needs up to 14 tokens. Top up in the dashboard." } }