> ## Documentation Index > Fetch the complete documentation index at: https://docs.musicgpt.com/llms.txt > Use this file to discover all available pages before exploring further. # Text To Speech > Synthesize speech from text with voice and gender customization, plus optional webhook callback. Give priority to the sample audio first, then to the voice ID, and lastly to gender. Convert any given text into realistic speech using your chosen voice and gender. **TextToSpeech** enables you to instantly bring written content to life. Perfect for: * Creating dynamic audio narrations or voiceovers * Choosing gender-specific voice stylings for different contexts * Using webhooks for real-time integration with your workflows *** ## Endpoint ```http theme={null} POST /TextToSpeech ``` Use this endpoint to initiate a new text-to-speech audio generation. *** ## Sample Output Prompt: When I think of superheroes I think of super humans. I think of Superman, Wolverine and Wonder Woman. Usually they have a cape, or a mask to hide their face just in case. They have X-ray vision and super-human strength. Some can even breathe in outer space. They fly around a while, but always come back to keep our cities safe. They’re here to save humanity from itself. It’s a metaphor for how we look outside ourselves for help, and while the fantasies are fun, I choose to look for me and you. Download Audio *** ## Try it Yourself Visit the [TextToSpeech Endpoint Explorer](/api-documentation/endpoint/TextToSpeech) to try your own text samples. > 💡 Tip: Set a `webhook_url` to receive results automatically when your audio is ready. *** ## Request Parameters | Parameter | Type | Required | Description | | ------------------ | ------ | -------- | -------------------------------------------------------------------------------------------- | | `text` | String | Yes | The text content to convert to speech | | `voice_id` | String | Optional | Voice model to apply for synthesis. Either `voice_id` or `sample_audio_url` must be provided | | `sample_audio_url` | String | Optional | URL of Voice you want. Either `voice_id` or `sample_audio_url` must be provided | | `gender` | String | Yes | Gender of the voice ("male", "female") | | `webhook_url` | String | No | URL to receive a callback with generated audio | > 💡**Note**: You must provide either `voice_id` or `audio_url` — not both as `None`. > **content-type:** application/json *** ## Sample Request ### Python ```python theme={null} import requests url = 'https://api.musicgpt.com/api/public/v1/TextToSpeech' api_key = '' headers = { "accept": "application/json", "Authorization": api_key, "Content-Type": "application/json" } data = { 'text': "The character Sherlock Holmes first appeared in print in 1887's A Study in Scarlet...", 'voice_id': 'Drake', 'gender': 'string', 'webhook_url': 'http://abc.requestcatcher.com/test' } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` *** ## Sample Response ### Success (200 OK) ```json theme={null} { "success":true, "task_id":"0a65cbb6-2ab8-4949-9ee0-0e8c138ac2cf", "conversion_id":"6542baa6-d61f-4d90-b832-ed929d9c0996", "eta":17, "credit_estimate":0.68, "message":"", "status":"IN_QUEUE" } ``` *** ## Webhook Response Once audio is ready, your webhook will receive: ```json theme={null} { "success": true, "conversion_type": "Text To Speech", "task_id": "037a9a09-3fc6-4a90-8748-d3406ff712eb", "conversion_id": "f1970224-ab06-4aa6-a832-0f3fd23212b7", "audio_url": "https://lalals.s3.amazonaws.com/projects/f1970224-ab06-4aa6-a832-0f3fd23212b7.mp3", "audio_url_wav": "https://lalals.s3.amazonaws.com/projects/f1970224-ab06-4aa6-a832-0f3fd23212b7.wav", "conversion_cost": "0.68", "conversion_duration": 27.78 } ``` > 🎧 Use the `audio_url` to listen or download your synthesized speech. *** ## Error Codes * **402 Payment Required**: Not enough credits to process the request * **422 Unprocessable Entity**: Invalid or missing fields * **500 Internal Server Error**: Server-side failure during processing *** ## Payload and Request Formation ## OpenAPI ````yaml POST /v1/TextToSpeech openapi: 3.1.0 info: title: Musicgpt API version: 1.0.0 description: API for retrieving conversion details by ID. servers: - url: https://api.musicgpt.com/api/public description: Production server security: [] paths: /v1/TextToSpeech: post: summary: Convert text to speech using a specified voice description: >- Synthesize speech from text with voice and gender customization, plus optional webhook callback. Give priority to the sample audio first, then to the voice ID, and lastly to gender. requestBody: required: true content: application/json: schema: type: object properties: text: type: string description: Text to convert to speech voice_id: type: string description: Voice model ID gender: type: string description: Gender preference for the voice (e.g., "male", "female") sample_audio_url: type: string description: >- An audio URL containing a voice sample of the target speaker without music or overlapping voices. Recommended over voice_id for better output quality. webhook_url: type: string description: Callback URL for async processing required: - text anyOf: - required: - sample_audio_url - required: - voice_id responses: '200': description: Successfully initiated TTS conversion content: application/json: schema: type: object properties: success: type: boolean task_id: type: string conversion_id: type: string eta: type: integer example: success: true task_id: 72eed5b0-8652-4bb4-9a95-eb0ad4850f12 conversion_id: 648a6823-b2a4-47b3-801e-f452c567ae6f eta: 19 '402': description: Payment Required content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Insufficient credit balance '422': description: Validation Error content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: 'Missing required field: text' '500': description: Server Error content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Internal Server Error security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ````