> ## Documentation Index > Fetch the complete documentation index at: https://docs.play.ht/llms.txt > Use this file to discover all available pages before exploring further. # Text to speech HTTP streaming Streams the audio bytes with out ultra-fast text-in, audio-out API. > ℹ️ **Turbo Model** > For our newest `PlayDialog-turbo` engine powered by Groq, see the [Turbo get started guide](https://docs.play.ht/reference/groq). It uses the same endpoint but has accepts different voice inputs. Our HTTP streaming endpoint allows you to send text and receive audio bytes in real-time. You can also use our [Python SDK](ref:python-sdk) or [Nodejs SDK](ref:nodejs-sdk) streaming. ## Get your Credentials To use the HTTP API you will need an API Key and a User Id, you can easily generate those, [check this guide for a how-to](doc:api-authentication). ## Example For code examples, see the interactive code snippets to the right. The provided examples will return an audio buffer stream that you can use to save locally or stream over the network to a browser, app, or telephony system. For the complete list of supported parameters, see below. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "API", "version": "2.0", "description": "API documentation for Play.ht's Standard & Premium, and PlayHT Voices\n" }, "servers": [ { "url": "https://api.play.ht" } ], "security": [ { "ApiKeyAuth": [], "XUserIdAuth": [] } ], "paths": { "/api/v2/tts/stream": { "post": { "tags": [ "Hidden" ], "operationId": "api-generate-tts-audio-stream", "summary": "Text to speech HTTP streaming", "description": "Streams the audio bytes with out ultra-fast text-in, audio-out API. \n\n> ℹ️ **Turbo Model**\n> For our newest `PlayDialog-turbo` engine powered by Groq, see the [Turbo get started guide](https://docs.play.ht/reference/groq). It uses the same endpoint but has accepts different voice inputs.\n\nOur HTTP streaming endpoint allows you to send text and receive audio bytes in real-time. You can also use our [Python SDK](https://docs.play.ht/reference/python-sdk) or [Nodejs SDK](https://docs.play.ht/reference/nodejs-sdk) streaming.\n\n## Get your Credentials\n\nTo use the HTTP API you will need an API Key and a User Id, you can easily generate those, [check this guide for a how-to](https://docs.play.ht/docs/api-authentication).\n\n## Example\n\nFor code examples, see the interactive code snippets to the right. The provided examples will return an audio buffer stream that you can use to save locally or stream over the network to a browser, app, or telephony system.\n\nFor the complete list of supported parameters, see below.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStreamingJobParams" } } } }, "responses": { "200": { "$ref": "#/components/responses/TextToSpeechStreamAudioBytes" }, "400": { "$ref": "#/components/responses/InvalidParametersError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "415": { "$ref": "#/components/responses/UnsupportedMediaTypeError" }, "429": { "$ref": "#/components/responses/RateLimitedError" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "AUTHORIZATION", "description": "API key required for this endpoint. Use `Bearer YOUR_SECRET_API_KEY`. Get your key from ." }, "XUserIdAuth": { "type": "apiKey", "in": "header", "name": "X-USER-ID", "description": "User ID required for this endpoint. Get it from ." } }, "schemas": { "ErrorResponseObject": { "type": "object", "properties": { "error_message": { "type": "string" }, "error_id": { "type": "string" } } }, "VoiceId": { "description": "The unique ID for a PlayHT or Cloned Voice.", "type": "string", "example": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json", "default": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json" }, "CreateJobParams": { "type": "object", "properties": { "text": { "type": "string", "description": "The text to be converted to speech. Limited to 20k characters when `voice_engine` is set to `Play3.0-mini`, or 2000 characters otherwise.", "example": "Hello Play!", "default": "Hello Play!" }, "voice": { "$ref": "#/components/schemas/VoiceId" }, "quality": { "type": "string", "enum": [ "draft", "low", "medium", "high", "premium" ] }, "output_format": { "type": "string", "enum": [ "mp3", "wav", "ogg", "flac", "mulaw" ], "default": "mp3" }, "speed": { "description": "Control how fast the generated audio should be. A number greater than 0 and less than or equal to 5.0", "type": "number", "example": 1, "minimum": 0.1, "maximum": 5 }, "sample_rate": { "description": "A number greater than or equal to 8000, and must be less than or equal to 48000", "type": "number", "example": 24000, "minimum": 8000, "maximum": 48000 }, "seed": { "description": "An integer number greater than or equal to 0. If equal to `null` or not provided, a random seed will be used. Useful to control the reproducibility of the generated audio. Assuming all other properties didn't change, a fixed seed should always generate the exact same audio file.", "type": "number", "nullable": true, "example": null, "minimum": 0 }, "temperature": { "description": "A floating point number between 0, inclusive, and 2, inclusive. If equal to `null` or not provided, the model's default temperature will be used. The temperature parameter controls variance. Lower temperatures result in more predictable results, higher temperatures allow each run to vary more, so the voice may sound less like the baseline voice.", "type": "number", "nullable": true, "example": null, "minimum": 0, "maximum": 2 }, "voice_engine": { "type": "string", "enum": [ "PlayHT2.0", "PlayHT1.0" ], "default": "PlayHT2.0", "example": "PlayHT2.0", "nullable": true, "description": "The voice engine used to synthesize the voice." }, "emotion": { "type": "string", "enum": [ "female_happy", "female_sad", "female_angry", "female_fearful", "female_disgust", "female_surprised", "male_happy", "male_sad", "male_angry", "male_fearful", "male_disgust", "male_surprised" ], "nullable": true, "description": "An emotion to be applied to the speech. Only supported when `voice_engine` is set to `PlayHT2.0`, and `voice` uses that engine." }, "voice_guidance": { "type": "number", "minimum": 1, "maximum": 6, "nullable": true, "example": 3, "description": "A number between 1 and 6. Use lower numbers to reduce how unique your chosen voice will be compared to other voices. Higher numbers will maximize its individuality. Only supported when `voice_engine` is set to `PlayHT2.0`, and `voice` uses that engine." }, "style_guidance": { "type": "number", "minimum": 1, "maximum": 30, "example": 20, "nullable": true, "description": "A number between 1 and 30. Use lower numbers to to reduce how strong your chosen emotion will be. Higher numbers will create a very emotional performance. Only supported when `voice_engine` is set to `PlayHT2.0`, and `voice` uses that engine." } }, "required": [ "text", "voice" ] }, "CreateStreamingJobParams": { "type": "object", "properties": { "text": { "$ref": "#/components/schemas/CreateJobParams/properties/text" }, "voice": { "$ref": "#/components/schemas/VoiceId" }, "quality": { "type": "string", "enum": [ "draft", "low", "medium", "high", "premium" ], "description": "The quality level of the audio. Not supported when `voice_engine` is set to `PlayDialog-turbo`." }, "output_format": { "type": "string", "enum": [ "mp3", "mulaw", "wav", "ogg", "flac" ], "default": "wav", "nullable": true, "description": "The format for the output audio. Note that `PlayHT1.0` engine voices and JSON output format only support 'mp3' and 'mulaw'. Currently, `PlayDialog-turbo` only supports `wav`." }, "speed": { "$ref": "#/components/schemas/CreateJobParams/properties/speed" }, "sample_rate": { "$ref": "#/components/schemas/CreateJobParams/properties/sample_rate", "description": "The sample rate of the audio in Hz. Not supported when `voice_engine` is set to `PlayDialog-turbo`." }, "seed": { "$ref": "#/components/schemas/CreateJobParams/properties/seed", "description": "A seed value for reproducible results. Not supported when `voice_engine` is set to `PlayDialog-turbo`." }, "temperature": { "$ref": "#/components/schemas/CreateJobParams/properties/temperature", "description": "Controls the randomness of the output. Not supported when `voice_engine` is set to `PlayDialog-turbo`." }, "voice_engine": { "type": "string", "enum": [ "PlayDialog-turbo", "PlayDialog", "Play3.0-mini", "PlayHT2.0-turbo", "PlayHT2.0", "PlayHT1.0" ], "example": "PlayDialog", "default": "PlayHT2.0", "nullable": true, "description": "The voice engine used to synthesize the voice." }, "emotion": { "type": "string", "enum": [ "female_happy", "female_sad", "female_angry", "female_fearful", "female_disgust", "female_surprised", "male_happy", "male_sad", "male_angry", "male_fearful", "male_disgust", "male_surprised" ], "nullable": true, "description": "An emotion to be applied to the speech. Only supported when `voice_engine` is set to `Play3.0-mini`, `PlayHT2.0` or `PlayHT2.0-turbo`, and `voice` uses that engine." }, "voice_guidance": { "type": "number", "minimum": 1, "maximum": 6, "nullable": true, "example": 3, "description": "A number between 1 and 6. Use lower numbers to reduce how unique your chosen voice will be compared to other voices. Higher numbers will maximize its individuality. Only supported when `voice_engine` is set to `Play3.0-mini`, `PlayHT2.0` or `PlayHT2.0-turbo`, and `voice` uses that engine." }, "style_guidance": { "type": "number", "minimum": 1, "maximum": 30, "example": 20, "nullable": true, "description": "A number between 1 and 30. Use lower numbers to to reduce how strong your chosen emotion will be. Higher numbers will create a very emotional performance. Only supported when `voice_engine` is set to `Play3.0-mini`, `PlayHT2.0` or `PlayHT2.0-turbo`, and `voice` uses that engine." }, "text_guidance": { "type": "number", "minimum": 1, "maximum": 2, "example": 1, "nullable": true, "description": "A number between 1 and 2. This number influences how closely the generated speech adheres to the input text. Use lower values to create more fluid speech, but with a higher chance of deviating from the input text. Higher numbers will make the generated speech more accurate to the input text, ensuring that the words spoken align closely with the provided text. Only supported when `voice_engine` is set to `Play3.0-mini` or `PlayHT2.0`, and `voice` uses that engine." }, "language": { "type": "string", "enum": [ "afrikaans", "albanian", "amharic", "arabic", "bengali", "bulgarian", "catalan", "croatian", "czech", "danish", "dutch", "english", "french", "galician", "german", "greek", "hebrew", "hindi", "hungarian", "indonesian", "italian", "japanese", "korean", "malay", "mandarin", "polish", "portuguese", "russian", "serbian", "spanish", "swedish", "tagalog", "thai", "turkish", "ukrainian", "urdu", "xhosa" ], "nullable": true, "description": "The language of the voice. Only supported when `voice_engine` is set to `Play3.0-mini` or `PlayDialog`, and `voice` has 2.0 engine or later. When `voice_engine` is set to `PlayDialog-turbo`, only `english` and `arabic` are supported.", "example": "english" }, "voice_2": { "description": "Only supported when `voice_engine` is set to `PlayDialog`. The unique ID for a Voice to be used as second character on multi-turn dialogue generations.", "type": "string", "example": "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json", "nullable": true }, "turn_prefix": { "type": "string", "nullable": true, "description": "Only supported when `voice_engine` is set to `PlayDialog`. The prefix to indicate the start of a turn in a multi-turn dialogue with `voice`.", "example": "Country Mouse:" }, "turn_prefix_2": { "type": "string", "nullable": true, "description": "Only supported when `voice_engine` is set to `PlayDialog`. The prefix to indicate the start of a turn in a multi-turn dialogue with `voice_2`.", "example": "Town Mouse:" }, "voice_conditioning_seconds": { "type": "number", "nullable": true, "example": 20, "description": "Only supported when `voice_engine` is set to `PlayDialog`. The number of seconds of conditioning to use from the selected `voice`. Lower values generate audio less similar to the cloned voice, but lead to more model stability and expressiveness. Higher values create output more similar to the cloned voice, but can lead to model instability and reduced expressiveness. Defaults to 20." }, "voice_conditioning_seconds_2": { "type": "number", "nullable": true, "example": 20, "description": "Only supported when `voice_engine` is set to `PlayDialog`. The number of seconds of conditioning to use from the selected `voice_2`. Lower values generate audio less similar to the cloned voice, but lead to more model stability and expressiveness. Higher values create output more similar to the cloned voice, but can lead to model instability and reduced expressiveness. Defaults to 20." } }, "required": [ "text", "voice" ] } }, "responses": { "InvalidParametersError": { "description": "The provided payload contains one or more invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "example": { "error_message": "The 'text' parameter must be provided.", "error_id": "INVALID_PARAMETERS" } } } }, "UnauthorizedError": { "description": "The request was not authorized. Please verity your authorization headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "example": { "error_message": "The authorization header must be provided in the format 'Bearer '", "error_id": "UNAUTHORIZED" } } } }, "ForbiddenError": { "description": "The provided API key's plan does not have access to the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "example": { "error_message": "API access is not available on your current plan.", "error_id": "UNSUPPORTED_PLAN" } } } }, "UnsupportedMediaTypeError": { "description": "The server could not process your request because the format of the data you sent is not supported.\n\nCheck `Content-Type` header of your request and ensure that it is set to a supported media type. You may also need to update your request payload to match the expected media type for the resource you are trying to access.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "example": { "error_message": "Requests to this endpoint must be in example/media-type.", "error_id": "UNSUPPORTED_MEDIA_TYPE" } } } }, "RateLimitedError": { "description": "The server has received too many requests from your IP address within a certain time frame and has temporarily blocked your access to this resource. This error is used to prevent abuse of the server. Please refer to the [Rate-Limits](https://docs.play.ht/reference/api-rate-limits) section for more information.", "content": { "application/json": { "schema": { "type": "string" }, "example": "Rate limit exceeded. Please wait a few moments and try again." } } }, "UnexpectedError": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "error": { "type": "string" } } } } } }, "TextToSpeechStreamAudioBytes": { "description": "A stream of audio bytes.", "x-responseType": "stream", "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```