PlayHT
Purpose
Generate spoken audio from text with PlayHT voices, browse stock and cloned voices, and create instant voice clones. Reach for this when the user wants narration or voiceovers, a voice library lookup, or a voice cloned from a sample.
Tooling
All commands go through bin/playht.py. PlayHT uses a single uppercase AUTHORIZATION: Bearer <key> header (older dual-header docs are stale); the CLI wires it through the credential surrogate.
bashbin/playht.py auth # {"ok": true, "voices": 120} on success bin/playht.py voices # list stock voices (id, name, language, gender) bin/playht.py tts --text "Welcome to the show." --voice-id <VOICE_ID> --out show.mp3 # streaming synthesis to a local MP3 file; prints the saved path bin/playht.py clones # list your cloned voices bin/playht.py clone --json clone-body.json # create an instant voice clone; body follows the current PlayHT docs # for POST /api/v2/cloned-voices/instant/ (confirmation-gated)
Notes:
ttsreturns audio binary. The CLI writes it to--out(defaultplayht-output.mp3) and prints the resulting path. Max 20,000 characters per request; PlayHT rate-limits to 120 requests/min per key.- Batch synthesis jobs are credit-consuming and confirmation-gated; they are not in this draft CLI.
Auth
- Provider id:
playht(credential is collected ascustom.playht) - Collection: PlayHT API key via the secure credential flow (
credentials.request_api_access); generate one under Settings, then API, in the PlayHT dashboard - Allowed hosts:
api.play.ht - Connect placement:
custom_header:AUTHORIZATION(uppercase; the stored credential value must include theBearerprefix, since the helper places the header value verbatim:AUTHORIZATION: Bearer <key>) - Status check:
bin/playht.py auth
Operating Rules
- Synthesis is credit-metered and rate-limited (120 req/min, 20,000 chars/request). Keep
ttscalls within the character cap; split long scripts before calling. - Voice cloning and batch synthesis are confirmation-gated: confirm with the user before running
cloneor any batch job. Only clone voices the user has the right to clone. - Never log or print the raw key; the CLI only ever handles the surrogate.
- Ignore older PlayHT docs that describe a dual-header scheme (
Authorization+X-USER-ID); the current API uses the single uppercaseAUTHORIZATIONheader.
Files
- SKILL.md
- bin/playht.py
Maturity
🧪 Draft: written from PlayHT's current public docs with paths cross-checked at build time; not yet live-tested end-to-end. TTS jobs (async batch synthesis) are not yet in the CLI.


