Puppetry Developer API
Puppetry Voice API access, hosted audio uploads, and credit-backed video jobs — callable from your code, your agent, or your terminal.
Included with the Studio plan. Keys are created in Studio settings and shown once.
$ curl -X POST https://www.puppetry.com/api/v1/videos/text
-d { "image_url": "https://…/portrait.jpg",
"text": "Welcome to the demo!", "voice_id": "puppetry-af_heart" }
202 {"status": "queued", "id": "api_video_8b1d…" }
$ curl https://www.puppetry.com/api/v1/videos/api_video_8b1d…
200 {"status": "processing", "progress": 0.62 }
200 {"status": "completed",
"video_url": "https://assets.puppetry.com/…/take.mp4" }
TypeScript SDK
npm i @puppetry.com/sdkMCP server — Claude Desktop, Codex CLI, Cursor
npx -y @puppetry.com/mcp-serverPlain HTTP
curl https://www.puppetry.com/openapi.jsonCreate is async: you get a job id back in milliseconds, poll until it completes, then download the video. Every response includes retry hints, and an Idempotency-Key makes retries safe.
/api/v1/videos/textPhoto + script → talking-head video job/api/v1/videos/audioPhoto + your audio → lip-synced video job/api/v1/videos/{jobId}Poll a job until video_url is ready/api/v1/tts/puppetryText → hosted WAV speech/api/v1/voices/puppetryBrowse the voice catalog with previews/api/v1/uploads/audio-urlReserve a signed upload for your audio/api/v1/usageCheck credits before you createIncluded with Studio
Video jobs are credit-backed
GET /api/v1/usage before creating — no wasted callsCurrent beta limits: 1 active API key per account · 10 requests per minute · 2 concurrent API jobs · 10 API video credits per month · 100k Puppetry Voice characters per month · 2GB hosted API audio storage · 250 audio uploads per month · 50MB max per uploaded audio file
Every voice below is callable by id from the API. Preview them before you write a line of code.
Puppetry voices
The Developer API returns 45 Puppetry voices from GET /api/v1/voices/puppetry. Each preview_url uses a short localized sample, so Italian voices speak Italian, Japanese voices speak Japanese, and so on.
List voices
GET /api/v1/voices/puppetryResponse is object: "list" with data[] voice objects.
Voice object
{
"id": "puppetry-af_heart",
"object": "voice",
"name": "Heart",
"provider": "puppetry",
"language": "English",
"language_code": "en",
"gender": "Female",
"preview_url": "/api/voices/puppetry-preview?voice=af_heart&language=en"
}Generate speech
POST /api/v1/tts/puppetry{
"voice_id": "puppetry-af_heart",
"text": "This is a free voice preview in Puppetry.",
"speed": 1
}Showing 6 recommended starters
puppetry-af_hearten/api/voices/puppetry-preview?voice=af_heart&language=enpuppetry-am_adamen/api/voices/puppetry-preview?voice=am_adam&language=enpuppetry-bf_emmaen-gb/api/voices/puppetry-preview?voice=bf_emma&language=en-gbpuppetry-ef_doraes/api/voices/puppetry-preview?voice=ef_dora&language=espuppetry-if_sarait/api/voices/puppetry-preview?voice=if_sara&language=itpuppetry-zf_xiaobeizh/api/voices/puppetry-preview?voice=zf_xiaobei&language=zhThree calls from an API key to a finished talking-head video.
Get your API key