Skip to main content
POST
/
v1
/
TextToSpeech
Convert text to speech using a specified voice
curl --request POST \
  --url https://api.musicgpt.com/api/public/v1/TextToSpeech \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "<string>",
  "sample_audio_url": "<string>",
  "voice_id": "<string>",
  "gender": "<string>",
  "webhook_url": "<string>"
}
'
{
  "success": true,
  "task_id": "72eed5b0-8652-4bb4-9a95-eb0ad4850f12",
  "conversion_id": "648a6823-b2a4-47b3-801e-f452c567ae6f",
  "eta": 19
}

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.

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

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 to try your own text samples.
💡 Tip: Set a webhook_url to receive results automatically when your audio is ready.

​
Request Parameters

ParameterTypeRequiredDescription
textStringYesThe text content to convert to speech
voice_idStringOptionalVoice model to apply for synthesis. Either voice_id or sample_audio_url must be provided
sample_audio_urlStringOptionalURL of Voice you want. Either voice_id or sample_audio_url must be provided
genderStringYesGender of the voice (“male”, “female”)
webhook_urlStringNoURL 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

import requests

url = 'https://api.musicgpt.com/api/public/v1/TextToSpeech'
api_key = '<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)

{
  "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: 
{
  "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

Authorizations

​
Authorization
string
header
required

Body

application/json
​
text
string
required

Text to convert to speech

​
sample_audio_url
string
required

An audio URL containing a voice sample of the target speaker without music or overlapping voices. Recommended over voice_id for better output quality.

​
voice_id
string

Voice model ID

​
gender
string

Gender preference for the voice (e.g., "male", "female")

​
webhook_url
string

Callback URL for async processing

Response

Successfully initiated TTS conversion

​
success
boolean
​
task_id
string
​
conversion_id
string
​
eta
integer