canonical: https://jentic.com/apis/play.ht/play # Play.ht Text to Speech API Jentic publishes the only available OpenAPI specification for Play.ht Text to Speech API, keeping it validated and agent-ready. The Play.ht API converts text into spoken audio with a choice of voice, quality, output format, speed, and voice engine, either as an asynchronous job you poll or as a real-time audio stream. Engines include Play3.0-mini, PlayHT2.0, and PlayHT1.0, and output formats include mp3, wav, ogg, flac, and mulaw. The API also creates instant voice clones from an uploaded audio sample, runs batches of up to 50 speech jobs, and produces timestamped transcriptions from an audio URL, alongside legacy v1 conversion operations. ## For AI agents Generate or stream speech from text in a chosen Play.ht voice, clone a voice from an audio sample, batch many speech jobs, and timestamp audio files. Covers voice listing, job status, and legacy v1 conversion. ## Scope Does not handle phone call routing, music generation, or speech translation. Use for text-to-speech, voice cloning, and audio timestamping only. ## Capabilities - Generate speech from text as an asynchronous job with a chosen voice, quality from draft to premium, output_format, speed, and voice_engine - Stream speech audio bytes in real time from text for low-latency playback - Clone a voice instantly from an uploaded sample_file and a voice_name, then list or delete your cloned voices - Submit between 1 and 50 text-to-speech jobs in a single batch request - Create a timestamped transcription job from an audio_url and fetch its result by job id - List the stock Play.ht voices available for synthesis ## Use cases ### Agent-Driven Voiceover via Jentic An AI agent producing narrated content takes a script, picks a voice from the Play.ht voice list, and creates a speech job with the chosen voice_engine and output_format. Through Jentic the agent polls the job by id until the audio is ready and hands back the file, while the bearer token and user id stay with your own instance. Example prompt: List voices, create a generateAudio job for a 1,500-character script with voice_engine PlayHT2.0, quality high, and output_format mp3, then poll getTtsJob until the audio is ready ### Real-Time Voice for Conversational Apps Voice assistants and phone bots need audio as soon as a reply is written. The streamAudio operation returns audio bytes over HTTP as they are generated, and the mulaw output format suits telephony pipelines, so a reply can start playing before the full clip has been synthesised. Example prompt: Stream a 200-character reply with streamAudio using voice_engine Play3.0-mini and output_format mulaw and pipe the bytes to the call ### Custom Brand Voice with Instant Cloning Creators and companies that want audio in a specific voice upload a sample_file with a voice_name to create an instant clone, then use the returned voice in speech jobs. Cloned voices can be listed and deleted when they are no longer needed. Example prompt: Create an instant voice clone from a sample recording with voice_name 'Brand Narrator', then generate an mp3 of a welcome message using the cloned voice ### Bulk Audio for Catalogues and Courses Teams converting many short texts, such as product descriptions or course lessons, submit them together with the batchTts operation, which accepts between 1 and 50 jobs per batch. Text limits per job depend on the engine: up to 20k characters for Play3.0-mini and 2000 characters for other engines. Example prompt: Submit a batchTts request with 30 lesson scripts using the same voice and collect each resulting audio file ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/api/v2/tts` | Create a text-to-speech job | | GET | `/api/v2/tts/{id}` | Get speech job status and audio | | POST | `/api/v2/tts/stream` | Stream audio from text | | POST | `/api/v2/tts/batches` | Submit a batch of speech jobs | | GET | `/api/v2/voices` | List Play.ht voices | | POST | `/api/v2/cloned-voices/instant` | Create an instant voice clone | | POST | `/api/v2/transcriptions` | Create a timestamp transcription job | ## Key resources - **Text-to-Speech** — Create asynchronous speech jobs, stream audio, run batches, and read job status and audio by id. - **Voices** — List the stock Play.ht voices. - **Voice Cloning** — Create instant voice clones from an audio sample, list them, and delete them. - **Transcription** — Create timestamped transcription jobs from an audio URL and fetch the results. - **Legacy** — v1 plain-text conversion, conversion status, and voice listing. ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 64 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 93 / 100 - Developer Experience & Jentic Compatibility: 57 / 100 - AI-Readiness & Agent Experience: 48 / 100 - Agent Usability: 94 / 100 - Security: 55 / 100 - AI Discoverability: 70 / 100 - **View full report:** https://jentic.com/apis/play.ht/play/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring Play.ht by hand means sending both a bearer token and an X-USER-ID header, choosing a voice engine within its text limits, and polling asynchronous jobs or handling a byte stream. Through Jentic you install once, import Play.ht from the API Directory, store the credentials once, and your agent generates speech. - **Permission scoping:** Play.ht puts the cloned voice id in the URL path (`/api/v2/cloned-voices/{voice_id}`), but speech text and voice choice travel in the request body, so rules bound which operations your agent may call rather than which voice it speaks with. You choose the operations it may call, so voice cloning and clone deletion are not included unless you add them. - **Credential handling:** Your Play.ht bearer token and user id are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'convert text to speech' or 'clone a voice', and Jentic returns the matching Play.ht operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **ElevenLabs** — ElevenLabs offers text-to-speech, voice cloning, and dubbing; Play.ht covers speech generation, streaming, cloning, and timestamped transcription. - **Murf** — Murf generates studio-style voiceovers; Play.ht adds real-time streaming and instant cloning through the API. - **Cartesia** — Cartesia focuses on low-latency speech models; Play.ht offers several engines and asynchronous jobs alongside streaming. - **AssemblyAI** — AssemblyAI transcribes and analyses speech; Play.ht turns text back into speech. ## FAQ ### Why is there no official OpenAPI spec for Play.ht Text to Speech API? Play.ht does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Play.ht Text to Speech API via structured tooling. It is validated against the live API and kept up to date. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### What authentication does the Play.ht API use? The Play.ht API declares two security schemes in its OpenAPI spec: a bearer token sent in the Authorization header, and a user id sent as an apiKey in the X-USER-ID header. Both values come from the API access page of your Play.ht account. Through Jentic the token and user id are stored encrypted on your own instance and injected at call time. ### Is there a Play.ht MCP server? You don't need an MCP server to give your agent Play.ht. Jentic connects it directly from the API Directory: import Play.ht, store your credentials once, and your agent can generate speech straight away. Operations are discovered on demand, so no extra server's tool definitions sit in your agent's context. ### Can I limit what my agent is allowed to do with the Play.ht API? Yes. Write a rule that allows only listVoices, generateAudio, and getTtsJob, so the agent can pick a voice, create speech, and fetch the result but cannot create or delete cloned voices, and every call it makes is logged. ### How much text can one Play.ht speech job take? Per the spec, a generateAudio job accepts up to 20k characters with the Play3.0-mini engine and 2000 characters with other engines. For more content, split it into several jobs or submit them together with batchTts, which takes between 1 and 50 jobs. ### What are the rate limits for the Play.ht API? The Play.ht OpenAPI spec does not specify rate limits. Check https://docs.play.ht for the current limits on your plan. ### How do I generate speech with the Play.ht API through Jentic? Search Jentic for an intent like 'convert text to speech', import Play.ht, and store your bearer token and user id once. Your agent then calls generateAudio at `/api/v2/tts` with text and a voice id from listVoices, and polls getTtsJob at `/api/v2/tts/{id}` for the audio.