--- updatedAt: 2026-06-27T03:28:31.000Z agentTools: projectIndex: https://docs.wellsaidlabs.com/llms.txt --- # Render text to speech This method turns text input into a consumable audio stream. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "version": "1.0.0", "title": "WellSaid TTS API", "description": "This API provides access to WellSaid Labs text-to-speech rendering service.", "termsOfService": "https://wellsaidlabs.com/legal?document=terms_of_service", "contact": { "email": "support@wellsaidlabs.com" } }, "servers": [ { "url": "https://api.wellsaidlabs.com/v1/tts" } ], "tags": [ { "name": "tts", "description": "Render text to speech" } ], "security": [ { "api_key": [] } ], "paths": { "/stream": { "post": { "tags": [ "tts" ], "summary": "Render text to speech", "description": "This method turns text input into a consumable audio stream.", "operationId": "ttsStream", "parameters": [ { "in": "header", "name": "X-Enable-SSML", "schema": { "type": "boolean" }, "description": "Enables limited SSML translation for input text" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TTSInputs" } } } }, "responses": { "200": { "description": "Audio stream from a successful text to speech render", "headers": { "Content-Type": { "schema": { "type": "string" }, "description": "audio/mpeg" }, "Content-Length": { "schema": { "type": "integer" }, "description": "audio file length in bytes" }, "x-quota-limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests available in the current time frame." }, "x-quota-remaining": { "schema": { "type": "integer" }, "description": "The number of requests remaining in the current time frame." }, "x-quota-reset": { "schema": { "type": "integer" }, "description": "A UNIX timestamp of the expected time when the quota limit will reset." }, "x-rate-limit-limit": { "schema": { "type": "integer" }, "description": "The maximum number of requests available in the current time frame." }, "x-rate-limit-remaining": { "schema": { "type": "integer" }, "description": "The number of requests available in the current time frame." }, "x-rate-limit-reset": { "schema": { "type": "integer" }, "description": "A UNIX timestamp of the expected time when the rate limit will reset." } }, "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/InvalidInputs" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "508": { "$ref": "#/components/responses/RenderLoop" } } } } }, "components": { "securitySchemes": { "api_key": { "type": "apiKey", "name": "X-API-KEY", "in": "header" } }, "responses": { "Unauthorized": { "description": "API key is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_key": { "summary": "API key not provided", "value": { "message": "No API key found in request", "code": "UNAUTHORIZED" } }, "invalid_key": { "summary": "API key is invalid or revoked", "value": { "message": "API key is invalid or has been revoked", "code": "UNAUTHORIZED" } } } } } }, "RateLimited": { "description": "Rate limit or concurrency limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limit": { "summary": "Too many requests in the current time window", "value": { "message": "Rate limit exceeded. Please retry after the reset time.", "code": "RATE_LIMITED" } } } } } }, "InvalidInputs": { "description": "Request failed input validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_argument": { "summary": "Required field is missing", "value": { "message": "speaker_id is required", "code": "MISSING_ARGUMENT" } }, "invalid_text": { "summary": "Text contains disallowed content", "value": { "message": "Invalid text argument", "code": "INVALID_TEXT" } }, "text_too_long": { "summary": "Text exceeds the 1000 character maximum", "value": { "message": "Invalid text argument, length must be less than 1000 characters", "code": "INVALID_TEXT_LENGTH_EXCEEDED" } }, "invalid_speaker": { "summary": "speaker_id is not a recognized voice", "value": { "message": "Invalid speaker_id: 999 is not a recognized voice", "code": "INVALID_SPEAKER_ID" } }, "content_not_allowed": { "summary": "Text contains policy-violating content", "value": { "message": "The provided text contains content that is not allowed", "code": "CONTENT_NOT_ALLOWED" } } } } } }, "RenderLoop": { "description": "Request render loop detected. This is likely a result of unusual phrasing, characters, and/or punctuation. The recommended action is to modify the input and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderLoopResponse" }, "example": { "message": "Failed to render, try again.", "code": "RENDER_FAILED" } } } } }, "schemas": { "TTSInputs": { "type": "object", "required": [ "speaker_id", "text" ], "properties": { "speaker_id": { "type": "integer", "enum": [ 3, 4, 5, 7, 8, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 65, 66, 67, 68, 69, 71, 72, 73, 75, 76, 77, 78, 79, 80, 82, 83, 84, 85, 86, 89, 90, 91, 93, 94, 95, 96, 97, 99, 81, 87, 88, 92, 98, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155 ] }, "text": { "type": "string", "maxLength": 1000, "minLength": 1 }, "model": { "type": "string", "enum": [ "legacy", "caruso" ], "description": "Which model to use. Note that not all voices are available on all models." }, "library_ids": { "type": "array", "items": { "type": "string" }, "description": "List of ids of replacement libraries to use when processing" }, "audio_configs": { "type": "object", "properties": { "file_format": { "type": "string", "enum": [ "mp3", "wav", "s16le" ], "description": "File format for the streamed data. Use s16le for raw PCM data" }, "sample_rate": { "type": "number", "description": "Sample rate for the generated audio. Please note that not all sample rates are available for all formats", "enum": [ 8000, 16000, 22050, 24000, 44100, 48000, 96000 ] } } } } }, "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "MISSING_ARGUMENT", "INVALID_TEXT", "INVALID_TEXT_LENGTH_EXCEEDED", "INVALID_SPEAKER_ID", "CONTENT_NOT_ALLOWED", "UNAUTHORIZED", "RATE_LIMITED" ] } } }, "RenderLoopResponse": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "RENDER_FAILED" ] } } } } } } ```