API Reference

Build with Puppetry’s REST API. Create talking head videos programmatically, manage assets, and integrate AI video generation into your workflows.

Base URLhttps://api.puppetry.com/v1

Authentication

All API requests require an API key passed via the Authorization header using Bearer token authentication. You can generate API keys from your account settings.

Request header

Authorization: Bearer pk_live_your_api_key_here

Keep your API keys secret. Do not expose them in client-side code, public repositories, or browser requests.

Create Video

Create a new talking head video from a script and puppet.

POST/videos

Request body

Parameter	Type	Required	Description
script	string	Yes	The text the puppet will speak (max 5000 chars)
puppet_id	string	Yes	ID of the puppet to use
voice_id	string	No	Voice ID (defaults to puppet’s default voice)
resolution	string	No	"720p" or "1080p" (default: "1080p")
webhook_url	string	No	URL to receive a POST when the video is ready

curl

curl -X POST https://api.puppetry.com/v1/videos \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Welcome to our product demo!",
    "puppet_id": "ppt_abc123",
    "voice_id": "voice_sarah",
    "resolution": "1080p",
    "webhook_url": "https://example.com/webhooks/puppetry"
  }'

Response · 201 Created

{
  "id": "vid_abc123def456",
  "status": "processing",
  "puppet_id": "ppt_abc123",
  "voice_id": "voice_sarah",
  "resolution": "1080p",
  "duration_estimate_sec": 12,
  "created_at": "2026-02-24T10:30:00Z"
}

List Videos

Retrieve a paginated list of your videos.

GET/videos

Query parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Results per page, 1–100 (default: 20)
status	string	Filter by status: processing, completed, failed

curl

curl https://api.puppetry.com/v1/videos?page=1&limit=10 \
  -H "Authorization: Bearer pk_live_your_api_key"

Response · 200 OK

{
  "data": [
    {
      "id": "vid_abc123def456",
      "status": "completed",
      "puppet_id": "ppt_abc123",
      "duration_sec": 12,
      "created_at": "2026-02-24T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "total_pages": 5
  }
}

Get Video Status

Retrieve the current status and details of a specific video.

GET/videos/:id

curl

curl https://api.puppetry.com/v1/videos/vid_abc123def456 \
  -H "Authorization: Bearer pk_live_your_api_key"

Response · 200 OK

{
  "id": "vid_abc123def456",
  "status": "completed",
  "puppet_id": "ppt_abc123",
  "voice_id": "voice_sarah",
  "resolution": "1080p",
  "duration_sec": 12,
  "download_url": "https://cdn.puppetry.com/videos/vid_abc123def456.mp4",
  "thumbnail_url": "https://cdn.puppetry.com/thumbs/vid_abc123def456.jpg",
  "created_at": "2026-02-24T10:30:00Z",
  "completed_at": "2026-02-24T10:31:15Z"
}

Video statuses

Status	Description
processing	Video is being generated
completed	Video is ready to download
failed	Generation failed — check the error field for details

Download Video

Get a temporary signed download URL for a completed video. The URL expires after 1 hour.

GET/videos/:id/download

curl

curl https://api.puppetry.com/v1/videos/vid_abc123def456/download \
  -H "Authorization: Bearer pk_live_your_api_key"

Response · 200 OK

{
  "download_url": "https://cdn.puppetry.com/videos/vid_abc123def456.mp4?token=signed_token",
  "expires_at": "2026-02-24T11:31:15Z"
}

List Voices

Retrieve all available voices for video generation.

GET/voices

curl

curl https://api.puppetry.com/v1/voices \
  -H "Authorization: Bearer pk_live_your_api_key"

Response · 200 OK

{
  "data": [
    {
      "id": "voice_sarah",
      "name": "Sarah",
      "gender": "female",
      "language": "en-US",
      "preview_url": "https://cdn.puppetry.com/voices/sarah_preview.mp3"
    },
    {
      "id": "voice_james",
      "name": "James",
      "gender": "male",
      "language": "en-US",
      "preview_url": "https://cdn.puppetry.com/voices/james_preview.mp3"
    }
  ]
}

List Puppets

Retrieve all available puppets (face models) for your account, including stock puppets and any custom uploads.

GET/puppets

curl

curl https://api.puppetry.com/v1/puppets \
  -H "Authorization: Bearer pk_live_your_api_key"

Response · 200 OK

{
  "data": [
    {
      "id": "ppt_abc123",
      "name": "Professional Woman",
      "type": "stock",
      "thumbnail_url": "https://cdn.puppetry.com/puppets/ppt_abc123.jpg"
    },
    {
      "id": "ppt_custom_001",
      "name": "My Custom Avatar",
      "type": "custom",
      "thumbnail_url": "https://cdn.puppetry.com/puppets/ppt_custom_001.jpg"
    }
  ]
}

Rate Limits

API requests are rate limited per API key. The current limits are returned in response headers:

X-RateLimit-Limit — Max requests per minute
X-RateLimit-Remaining — Remaining requests in the current window
X-RateLimit-Reset — Unix timestamp when the window resets