API Reference

11 operations generated from the canonical OpenAPI contract. When the contract changes, this page changes with it.

Version 2026-05-11Server https://www.puppetry.comRaw OpenAPI JSON

Voices

1 operation

GET/api/v1/voices/puppetry#

List Puppetry voices

Returns the public Puppetry voice catalog available to Developer API keys with the voices:read scope. Each voice includes preview_url for fixed sample audio.

operationId: listPuppetryVoices

Responses

Status	Description	Schema
`200`	Public Puppetry voices	`VoiceListResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`429`	Rate limit or monthly beta quota exceeded	`ErrorResponse`

Puppets

4 operations

GET/api/v1/puppets#

List saved puppets

Returns the authenticated workspace's saved puppet library for use with Developer API video creation. Requires the videos:read scope.

operationId: listPuppets

Parameters

limit query · integer · optional: No description.
cursor query · string · optional: Puppet ID returned as nextCursor by the previous page.

Responses

Status	Description	Schema
`200`	Saved workspace puppets	`PuppetListResponse`
`400`	Invalid request body or unsupported input	`ErrorResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`429`	Rate limit or monthly beta quota exceeded	`ErrorResponse`
`503`	A beta quota, usage lookup, or job counter is temporarily unavailable.	`ErrorResponse`

POST/api/v1/puppets#

Save a puppet

Saves a reachable public portrait image in the authenticated workspace puppet library. Send an Idempotency-Key so a lost response or SDK retry returns the same saved puppet instead of creating a duplicate asset. Reusing the key with different input returns 409. Requires the videos:create scope.

operationId: createPuppet

Parameters

Idempotency-Key header · string · optional: Optional non-blank retry key for video, saved-puppet, and hosted audio upload URL create requests. Keys are scoped to the authenticated workspace and endpoint. Replaying the same accepted request returns the original resource without charging another credit or creating duplicate assets; replaying the same pending hosted audio upload returns a fresh signed PUT URL without reserving duplicate quota. Reusing the key for different input returns 409.

Request JSON · CreatePuppetRequest · 2 fields

application/json · body required

imageUrl string · uri · required: Reachable public portrait image URL.
name string · optional: Optional display name for the saved puppet.

Responses

Status	Description	Schema
`200`	Existing saved puppet returned from an Idempotency-Key replay without creating another library asset.	`Puppet`
`201`	Puppet saved	`Puppet`
`400`	Invalid request body or unsupported input	`ErrorResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`409`	The Idempotency-Key was already used with different puppet input.	`ErrorResponse`
`429`	Rate limit or monthly beta quota exceeded	`ErrorResponse`
`503`	A beta quota, usage lookup, or job counter is temporarily unavailable.	`ErrorResponse`

GET/api/v1/puppets/{puppetId}#

Get a saved puppet

Returns one saved puppet from the authenticated workspace. Requires the videos:read scope.

operationId: getPuppet

Parameters

puppetId path · string · required: Puppet ID returned by GET /api/v1/puppets.

Responses

Status	Description	Schema
`200`	Saved workspace puppet	`Puppet`
`400`	Invalid request body or unsupported input	`ErrorResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`404`	Puppet not found in this workspace	`ErrorResponse`
`429`	Rate limit or monthly beta quota exceeded	`ErrorResponse`
`503`	A beta quota, usage lookup, or job counter is temporarily unavailable.	`ErrorResponse`

DELETE/api/v1/puppets/{puppetId}#

Delete a saved puppet

Permanently removes one saved puppet from the authenticated workspace. Requires the videos:create scope.

operationId: deletePuppet

Parameters

puppetId path · string · required: Puppet ID returned by GET /api/v1/puppets.

Responses

Status	Description	Schema
`204`	Puppet deleted	—
`400`	Invalid request body or unsupported input	`ErrorResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`404`	Puppet not found in this workspace	`ErrorResponse`
`429`	Rate limit or monthly beta quota exceeded	`ErrorResponse`
`503`	A beta quota, usage lookup, or job counter is temporarily unavailable.	`ErrorResponse`

Text to Speech

1 operation

POST/api/v1/tts/puppetry#

Generate speech with a Puppetry voice

Creates a hosted WAV audio file from text using a public Puppetry voice. Requires the tts:create scope.

operationId: createPuppetrySpeech

Request JSON · TtsRequest · 3 fields

application/json · body required

voice_id string · required: Public voice ID from GET /api/v1/voices/puppetry.
text string · required: Text to synthesize.
speed number · optional: Speech speed multiplier.

Responses

Status	Description	Schema
`200`	Generated audio	`TtsResponse`
`400`	Invalid request body or unsupported input	`ErrorResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`404`	Unknown Puppetry voice	`ErrorResponse`
`429`	Rate limit or monthly beta quota exceeded	`ErrorResponse`
`502`	Puppetry could not create or inspect the requested asset.	`ErrorResponse`
`503`	A beta quota, usage lookup, or job counter is temporarily unavailable.	`ErrorResponse`

Audio Uploads

1 operation

POST/api/v1/uploads/audio-url#

Create a signed hosted audio upload URL

Creates a short-lived signed PUT URL for existing audio and a short-lived read URL for the uploaded asset. Send an Idempotency-Key header, or idempotencyKey/idempotency_key in the JSON body when custom headers are unavailable, so a lost response does not reserve duplicate hosted-upload quota. For audio-to-video workflows, send require_video_readiness=true to fail before reserving upload quota when video credits or active slots are blocked; active-slot blockers and retryable transient failures include Retry-After and X-Puppetry-Next-Poll-At so agents can pace the next reservation attempt. Idempotent replays of an existing pending upload still return a fresh signed URL. Requires the uploads:create scope.

operationId: createHostedAudioUploadUrl

Parameters

Idempotency-Key header · string · optional: Optional non-blank retry key for video, saved-puppet, and hosted audio upload URL create requests. Keys are scoped to the authenticated workspace and endpoint. Replaying the same accepted request returns the original resource without charging another credit or creating duplicate assets; replaying the same pending hosted audio upload returns a fresh signed PUT URL without reserving duplicate quota. Reusing the key for different input returns 409.

Request JSON · AudioUploadRequest · 14 fields

application/json · body required

mime_type audio/wav | audio/x-wav | audio/mpeg | audio/mp3 | audio/mp4 | audio/m4a | audio/x-m4a · one of required aliases: Supported audio MIME type.
mimeType audio/wav | audio/x-wav | audio/mpeg | audio/mp3 | audio/mp4 | audio/m4a | audio/x-m4a · one of required aliases: CamelCase alias for mime_type.
contentType audio/wav | audio/x-wav | audio/mpeg | audio/mp3 | audio/mp4 | audio/m4a | audio/x-m4a · one of required aliases: Agent-friendly alias for mime_type.
content_length integer · one of required aliases: Audio file size in bytes.
contentLength integer · one of required aliases: CamelCase alias for content_length.
sizeBytes integer · one of required aliases: Agent/runtime alias for content_length.
file_size integer · one of required aliases: Upload metadata alias for content_length.
fileSize integer · one of required aliases: Upload metadata alias for content_length.
idempotencyKey string · optional: Optional body alias for the Idempotency-Key retry header when custom headers are unavailable.
idempotency_key string · optional: Snake_case body alias for Idempotency-Key.
require_video_readiness boolean · optional: When true, the route verifies video_generation readiness before creating a new upload reservation and returns 402/429 with video_generation details if credits or active slots are blocked.
requireVideoReadiness boolean · optional: CamelCase alias for require_video_readiness.
video_readiness_required boolean · optional: Snake_case compatibility alias for require_video_readiness.
videoReadinessRequired boolean · optional: CamelCase compatibility alias for require_video_readiness.

Responses

Status	Description	Schema
`200`	Signed upload and read URLs	`AudioUploadUrlResponse`
`400`	Invalid request body or unsupported input	`ErrorResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`402`	The account does not have enough video credits to create the job.	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`409`	Idempotency-Key replay is in progress or conflicts with existing upload metadata.	`ErrorResponse`
`413`	Request body or audio file exceeds the upload limits	`ErrorResponse`
`415`	Request Content-Type must be application/json	`ErrorResponse`
`429`	Video generation active slots are full, or the Developer API rate limit was exceeded.	`ErrorResponse`
`502`	Puppetry could not create or inspect the requested asset.	`ErrorResponse`
`503`	A beta quota, usage lookup, or job counter is temporarily unavailable.	`ErrorResponse`

Usage

1 operation

GET/api/v1/usage#

Get Developer API usage

Returns the authenticated workspace's current video credit balance, monthly credit usage, included and purchased balances, hosted credit checkout availability, and credit-pack catalog for credit-backed Developer API video jobs. Requires the videos:read scope. When video generation is blocked by active job slots or usage data is temporarily unavailable, the response includes Retry-After and X-Puppetry-Next-Poll-At so agents can pace the next create or usage attempt.

operationId: getDeveloperApiUsage

Responses

Status	Description	Schema
`200`	Current Developer API usage	`UsageResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`429`	Rate limit or monthly beta quota exceeded	`ErrorResponse`
`503`	A beta quota, usage lookup, or job counter is temporarily unavailable.	`ErrorResponse`

Videos

3 operations

POST/api/v1/videos/text#

Create a video from text

Queues a credit-backed text-to-video job using a hosted image URL and a Puppetry voice. Requires the videos:create scope. Accepted queued responses and non-terminal Idempotency-Key replays include Retry-After, X-Puppetry-Next-Poll-At, plus absolute Location/Content-Location, Puppetry-Operation-Id, Puppetry-Request-Id, and X-Puppetry-Credits-* headers when debit metadata is available so clients can pace, locate, trace, and reconcile the first status poll.

operationId: createVideoFromText

Parameters

Idempotency-Key header · string · optional: Optional non-blank retry key for video, saved-puppet, and hosted audio upload URL create requests. Keys are scoped to the authenticated workspace and endpoint. Replaying the same accepted request returns the original resource without charging another credit or creating duplicate assets; replaying the same pending hosted audio upload returns a fresh signed PUT URL without reserving duplicate quota. Reusing the key for different input returns 409.

Request JSON · TextVideoRequest · 22 fields

application/json · body required

image_url string · uri · one of required aliases: HTTPS image URL for the portrait or puppet source.
imageUrl string · uri · one of required aliases: CamelCase alias for image_url.
image string · uri · one of required aliases: Agent-friendly alias for image_url.
portrait string · uri · one of required aliases: Portrait image alias for image_url.
portrait_url string · uri · one of required aliases: Snake_case portrait alias for image_url.
portraitUrl string · uri · one of required aliases: CamelCase portrait alias for image_url.
avatar string · uri · one of required aliases: Avatar image alias for image_url.
avatarUrl string · uri · one of required aliases: CamelCase avatar alias for image_url.
avatar_url string · uri · one of required aliases: Snake_case avatar alias for image_url.
photo string · uri · one of required aliases: Photo image alias for image_url.
photoUrl string · uri · one of required aliases: CamelCase photo alias for image_url.
photo_url string · uri · one of required aliases: Snake_case photo alias for image_url.
text string · one of required aliases: Script text to speak in the generated video.
script string · one of required aliases: Agent-friendly alias for text.
prompt string · one of required aliases: Agent-friendly alias for text.
voice_id string · optional: Public Puppetry voice ID from GET /api/v1/voices/puppetry. Defaults to the Puppetry default voice.
voiceId string · optional: CamelCase alias for voice_id.
voice string · optional: Agent-friendly alias for voice_id.
language string · optional: No description.
expressiveness number · optional: LivePortrait expression scale for the generated talking-head motion.
idempotencyKey string · optional: Optional request-body alias for the Idempotency-Key header. If both header and body aliases are provided, they must match.
idempotency_key string · optional: Snake_case request-body alias for Idempotency-Key. If both body aliases are provided, they must match.

Responses

Status	Description	Schema
`200`	Terminal video job returned from an Idempotency-Key replay without charging another credit. Includes absolute Location/Content-Location, Puppetry-Operation-Id, Puppetry-Request-Id, and X-Puppetry-Credits-* headers when debit metadata is available for the replayed job; retryable failed replays also include Retry-After and X-Puppetry-Next-Poll-At.	`VideoJobReplayResponse`
`202`	Video job queued, or a non-terminal Idempotency-Key replay returned without charging another credit. Includes Retry-After, X-Puppetry-Next-Poll-At, plus absolute Location/Content-Location, Puppetry-Operation-Id, Puppetry-Request-Id, and X-Puppetry-Credits-* headers when debit metadata is available so clients can pace, locate, trace, and reconcile the first status poll.	`VideoJobQueuedResponse`
`400`	Invalid request body or unsupported input	`ErrorResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`402`	The account does not have enough video credits to create the job.	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`404`	Unknown Puppetry voice for text-to-video	`ErrorResponse`
`409`	The Idempotency-Key is already creating a video job or hosted upload URL, or it was reused with different input. Video create conflicts include Location/Content-Location, Puppetry-Operation-Id, and Puppetry-Request-Id headers for the existing API video job when one is known.	`ErrorResponse`
`413`	Request body exceeds the video create limit.	`ErrorResponse`
`415`	The request body media type is not supported.	`ErrorResponse`
`429`	Rate limit or monthly beta quota exceeded	`ErrorResponse`
`502`	Puppetry could not create or inspect the requested asset.	`ErrorResponse`
`503`	A beta quota, usage lookup, or job counter is temporarily unavailable.	`ErrorResponse`

POST/api/v1/videos/audio#

Create a video from audio

Queues a credit-backed audio-to-video job using hosted image and audio URLs. Requires the videos:create scope. Accepted queued responses and non-terminal Idempotency-Key replays include Retry-After, X-Puppetry-Next-Poll-At, plus absolute Location/Content-Location, Puppetry-Operation-Id, Puppetry-Request-Id, and X-Puppetry-Credits-* headers when debit metadata is available so clients can pace, locate, trace, and reconcile the first status poll.

operationId: createVideoFromAudio

Parameters

Idempotency-Key header · string · optional: Optional non-blank retry key for video, saved-puppet, and hosted audio upload URL create requests. Keys are scoped to the authenticated workspace and endpoint. Replaying the same accepted request returns the original resource without charging another credit or creating duplicate assets; replaying the same pending hosted audio upload returns a fresh signed PUT URL without reserving duplicate quota. Reusing the key for different input returns 409.

Request JSON · AudioVideoRequest · 18 fields

application/json · body required

image_url string · uri · one of required aliases: HTTPS image URL for the portrait or puppet source.
imageUrl string · uri · one of required aliases: CamelCase alias for image_url.
image string · uri · one of required aliases: Agent-friendly alias for image_url.
portrait string · uri · one of required aliases: Portrait image alias for image_url.
portrait_url string · uri · one of required aliases: Snake_case portrait alias for image_url.
portraitUrl string · uri · one of required aliases: CamelCase portrait alias for image_url.
avatar string · uri · one of required aliases: Avatar image alias for image_url.
avatarUrl string · uri · one of required aliases: CamelCase avatar alias for image_url.
avatar_url string · uri · one of required aliases: Snake_case avatar alias for image_url.
photo string · uri · one of required aliases: Photo image alias for image_url.
photoUrl string · uri · one of required aliases: CamelCase photo alias for image_url.
photo_url string · uri · one of required aliases: Snake_case photo alias for image_url.
audio_url string · uri · one of required aliases: HTTPS audio URL. Use /api/v1/uploads/audio-url when the audio is not already hosted; Puppetry-hosted API uploads must belong to the same API key that queues the video job. Rotated or expired signed read URL query params for the same hosted upload are treated as the same idempotent create input, and the stored key is re-signed before validation and queueing.
audioUrl string · uri · one of required aliases: CamelCase alias for audio_url.
audio string · uri · one of required aliases: Agent-friendly alias for audio_url.
expressiveness number · optional: LivePortrait expression scale for the generated talking-head motion.
idempotencyKey string · optional: Optional request-body alias for the Idempotency-Key header. If both header and body aliases are provided, they must match.
idempotency_key string · optional: Snake_case request-body alias for Idempotency-Key. If both body aliases are provided, they must match.

Responses

Status	Description	Schema
`200`	Terminal video job returned from an Idempotency-Key replay without charging another credit. Includes absolute Location/Content-Location, Puppetry-Operation-Id, Puppetry-Request-Id, and X-Puppetry-Credits-* headers when debit metadata is available for the replayed job; retryable failed replays also include Retry-After and X-Puppetry-Next-Poll-At.	`VideoJobReplayResponse`
`202`	Video job queued, or a non-terminal Idempotency-Key replay returned without charging another credit. Includes Retry-After, X-Puppetry-Next-Poll-At, plus absolute Location/Content-Location, Puppetry-Operation-Id, Puppetry-Request-Id, and X-Puppetry-Credits-* headers when debit metadata is available so clients can pace, locate, trace, and reconcile the first status poll.	`VideoJobQueuedResponse`
`400`	Invalid request body or unsupported input	`ErrorResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`402`	The account does not have enough video credits to create the job.	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`409`	The Idempotency-Key is already creating a video job or hosted upload URL, or it was reused with different input. Video create conflicts include Location/Content-Location, Puppetry-Operation-Id, and Puppetry-Request-Id headers for the existing API video job when one is known.	`ErrorResponse`
`413`	Request body exceeds the video create limit.	`ErrorResponse`
`415`	The request body media type is not supported.	`ErrorResponse`
`429`	Rate limit or monthly beta quota exceeded	`ErrorResponse`
`502`	Puppetry could not create or inspect the requested asset.	`ErrorResponse`
`503`	A beta quota, usage lookup, or job counter is temporarily unavailable.	`ErrorResponse`

GET/api/v1/videos/{jobId}#

Get video job status

Polls a Developer API video job created by the same API key. Requires the videos:read scope. Jobs created with another key, user, or org return 404. Status responses include absolute Location, Content-Location, Puppetry-Operation-Id, and Puppetry-Request-Id headers with the same poll target; queued or processing 200 responses also include Retry-After and X-Puppetry-Next-Poll-At so clients can pace polling.

operationId: getVideoJob

Parameters

jobId path · string · required: No description.

Responses

Status	Description	Schema
`200`	Video job status	`VideoJobStatusResponse`
`400`	Invalid request body or unsupported input	`ErrorResponse`
`401`	Missing, malformed, invalid, or revoked API key	`ErrorResponse`
`403`	The API key does not include the required endpoint scope.	`ErrorResponse`
`404`	Video job not found, or not visible to the authenticated API key	`ErrorResponse`
`429`	Rate limit or monthly beta quota exceeded	`ErrorResponse`
`502`	Puppetry could not inspect an accepted video job. Retry-After, X-Puppetry-Next-Poll-At, Location, Content-Location, Puppetry-Operation-Id, and Puppetry-Request-Id identify and pace the same status poll target.	`ErrorResponse`
`504`	Puppetry timed out while checking an accepted video job. Retry-After, X-Puppetry-Next-Poll-At, Location, Content-Location, Puppetry-Operation-Id, and Puppetry-Request-Id identify and pace the same status poll target.	`ErrorResponse`