Engineering

Integrate a video API with Claude Code or Cursor

Integrate a video API with Claude Code or Cursor: give the agent the right context, set project rules, and review the webhook and auth code it writes.

PitchTwin team, , 6 min read

Coding agents can wire an API into your app in minutes, but only as well as the context you give them. Left alone, an agent guesses field names from similar APIs, verifies webhooks against re-serialized JSON, or calls the API from the browser with your secret key. The fix is not to type more code yourself. Give the agent the exact contract up front, keep it in the repo, and review the few places where integrations usually break.

This post walks through that process for a video API, using PitchTwin with Claude Code or Cursor. The approach carries over to any async REST API.

What the agent needs to know

An avatar video integration has more moving parts than a typical CRUD API:

  • Async jobs. POST /generations returns 202 with status: "queued". The video arrives later.
  • Webhooks. Results are POSTed to your webhook_url with a PitchTwin-Signature: t=…,v1=… header, where v1 is the hex HMAC-SHA256 of ${t}.${raw_body}. Each webhook is delivered once, so polling GET /generations/:id is the fallback.
  • Exactly one input. A generation takes exactly one of text, script (an array of { text, pause_after_ms }) or audio ({ url, alignment? }).
  • Expiring links. video_url and audio_url are signed and expire after 24 hours.
  • Server-side keys. The pt_live_… key goes in an Authorization: Bearer header from your server only.

Each item is a place where a reasonable guess is wrong. Put them in front of the agent before it writes anything.

Step 1: start from the integration prompt

The PitchTwin dashboard has a Copy prompt button that copies a ready-made integration prompt for coding agents. It points the agent at the docs, names the base URL and auth header, and asks for four pieces:

  1. A server function that creates an avatar and stores its id.
  2. A server function that starts a generation with a webhook_url.
  3. A webhook route that verifies the PitchTwin-Signature header and saves the result.
  4. Error handling for the API's { error: { code, message } } shape, especially 402 insufficient_tokens and 409 avatar_not_ready.

It also tells the agent to follow your project's existing framework and folder structure, and to read the key from a PITCHTWIN_KEY environment variable. Paste it into Claude Code or Cursor as your first message. If you'd rather see raw requests first, the dashboard Playground generates a test video without code and shows the equivalent cURL and Node request.

Step 2: keep the contract in the repo

A prompt lasts one session. Rules files last as long as the repo, so the next change to the integration starts with the same facts.

Claude Code

Claude Code reads project instructions from CLAUDE.md (or .claude/CLAUDE.md) at the start of every session, as described in its memory documentation. Running /init generates a starting file from your codebase, and a CLAUDE.md can pull in other files with @path/to/file imports, so the integration notes can live in their own file:

# CLAUDE.md
@docs/integrations/pitchtwin.md

If your repository already uses AGENTS.md, Claude Code reads it when there is no CLAUDE.md; the same page explains how the two interact.

Cursor

Cursor project rules live in .cursor/rules as .mdc files with frontmatter, according to the Cursor rules docs. globs attaches a rule when matching files are in context, and alwaysApply: true includes it in every chat. Cursor also reads AGENTS.md in the project root and subdirectories.

---
description: PitchTwin avatar video API integration
globs: src/lib/pitchtwin/**,src/app/hooks/**
alwaysApply: false
---
See docs/integrations/pitchtwin.md before changing this code.

The shared notes file

Both tools can then point at one file. Keep it short and specific:

# PitchTwin integration

- Base URL: https://pitchtwin.ai/api/v1
- Auth: `Authorization: Bearer $PITCHTWIN_KEY`. Server only. Never import the
  client module from browser code.
- POST /generations takes `avatar_id` and exactly one of `text`, `script`
  ([{ text, pause_after_ms }]) or `audio` ({ url, alignment? }).
  Returns 202 { id, status: "queued" }.
- Results: signed webhook to `webhook_url` (once, no retries) plus a reconciler
  that polls GET /generations/:id for jobs still pending.
- Webhook signature: header `PitchTwin-Signature: t=<unix>,v1=<hex>`.
  v1 = hex HMAC-SHA256 of `${t}.${raw_body}` with PITCHTWIN_WEBHOOK_SECRET.
  Verify on the raw bytes, constant-time compare, 5-minute timestamp window.
- `video_url` expires after 24 h. Copy the MP4 to our bucket; store the key,
  not the URL.
- Errors are { error: { code, message } }. Handle 402 insufficient_tokens and
  409 avatar_not_ready explicitly.

Step 3: ask for a plan, then small diffs

Before the agent edits files, ask it to describe the plan: which files it will add, where the webhook route goes in your router, how it gets the raw body in your framework, and where job state is stored. Fixing a wrong plan takes one message. Fixing a wrong 400-line diff takes much longer.

Then let it work in pieces you can review: the API client, the job table migration, the webhook route, the reconciler. Each piece is small enough to read in full.

Step 4: review the parts agents get wrong

Generated integration code usually looks right. These are the spots worth reading line by line:

AreaWhat to check
Webhook bodySignature computed on the raw request bytes, not on JSON.stringify(req.body)
Comparecrypto.timingSafeEqual (Node) or hmac.compare_digest (Python), with a length check first in Node
Timestampt checked against the current time, so old requests are rejected
SecretWebhook secret from Dashboard → API keys, not the API key
Key exposureNo NEXT_PUBLIC_/VITE_ prefix on PITCHTWIN_KEY; client module never imported into browser code
Request bodyExactly one of text, script, audio; voice.speed only between 0.7 and 1.2
IdempotencyA second webhook or a reconciler run for the same generation changes nothing
StorageMP4 copied to your storage; the 24-hour link is not saved as permanent
FallbackSomething polls generations that stayed pending

If any row fails, tell the agent which rule in the notes file it broke. That fixes the code and checks that the notes are clear enough. How to verify HMAC webhook signatures has reference implementations to compare against, and Async video generation with webhooks covers the job table and reconciler.

Step 5: test end to end

Ask the agent to add two tests, then run them yourself:

  1. Signature test. Sign a sample body locally and POST it to the webhook route. Change one byte and expect a 400.
t=$(date +%s)
body='{"type":"generation.succeeded","data":{"id":"test"}}'
sig=$(printf '%s.%s' "$t" "$body" \
  | openssl dgst -sha256 -hmac "$PITCHTWIN_WEBHOOK_SECRET" \
  | sed 's/^.* //')
curl -i http://localhost:3000/hooks/pitchtwin \
  -H "Content-Type: application/json" \
  -H "PitchTwin-Signature: t=$t,v1=$sig" \
  --data-raw "$body"
  1. Real generation. Create an avatar in the dashboard, then trigger a short generation through your new code with a tunnel URL as webhook_url. Check the job row, the stored MP4 and the logs in Dashboard → Logs.

A short text keeps the test cheap: tokens are charged per second of video, and failed generations are refunded in full automatically.

Where agents help most after launch

Once the contract is in the repo, follow-up work goes faster: adding captions from the words array, switching a feature to audio mode with your own ElevenLabs audio, or adding a script editor with pauses. Each is a small change against a contract the agent can already read. The API surface is small (uploads, avatars, generations, balance), which keeps the notes file short. See the AI avatar API overview for what the API covers.

Try it

Sign up for 60 free tokens with no card, press Copy prompt in the dashboard, and paste it into Claude Code or Cursor. The quickstart shows the three calls the agent will build on.

Keep reading