Text-to-Speech (TTS) API Documentation

API Overview

This API allows you to convert text into natural-sounding speech. You can specify the voice and model for the TTS generation. It is ideal for use cases such as games, tutorials, and accessibility applications.

API Endpoint

To generate speech, send a POST request to the following URL:

https://imseldrith-tts-openai-free.hf.space/v1/audio/speech

Request Example

Here’s an example of the JSON payload you’ll need to send in your POST request:

{
    "model": "tts-1",
    "input": "Today is a wonderful day to build something people love!",
    "voice": "echo"
}
        

Voice Options

Choose from the following voices for speech synthesis:

• alloy: A deep and rich voice.
• echo: A soft, echoing voice.
• fable: A calm, neutral voice.
• onyx: A slightly robotic, futuristic voice.
• nova: A bright and clear voice.
• shimmer: A soft, dreamy voice.

Audio Quality Options

You can choose between two models based on the quality of the audio and latency requirements:

• tts-1: The standard model that provides low latency but may have some static or lower quality in certain situations. Ideal for real-time applications.
• tts-1-hd: A high-definition model that produces better quality audio at the cost of higher latency. Recommended for non-realtime applications where quality is a priority.

How to Use the API

Use the following code examples to make requests to the API. You can copy and modify the code as needed.

Python Code Example

This Python example demonstrates how to send a POST request to the API and save the generated speech as an MP3 file:

import requests

# API URL and Headers
url = "https://imseldrith-tts-openai-free.hf.space/v1/audio/speech"
headers = {
    "Content-Type": "application/json"
}

# Payload with input text and desired voice
data = {
    "model": "tts-1",  # Use "tts-1-hd" for higher quality audio
    "input": "Today is a wonderful day to build something people love!",
    "voice": "echo"  # Choose a voice (e.g., "alloy", "echo", "fable", etc.)
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Save the response content to an MP3 file if the request is successful
if response.status_code == 200:
    with open("speech.mp3", "wb") as f:
        f.write(response.content)
    print("Speech file saved as 'speech.mp3'")
else:
    print(f"Failed to generate speech: {response.status_code}, {response.text}")
        

cURL Command Example

If you prefer using cURL, you can make the request like this:

curl -X POST https://imseldrith-tts-openai-free.hf.space/v1/audio/speech \
     -H "Content-Type: application/json" \
     -d '{
         "model": "tts-1",
         "input": "Today is a wonderful day to build something people love!",
         "voice": "echo"
     }' --output speech.mp3
        

JavaScript (Fetch) Example

Here’s how you can make a POST request to the TTS API using JavaScript (for example, in a web application):

fetch("https://imseldrith-tts-openai-free.hf.space/v1/audio/speech", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        model: "tts-1",  // Use "tts-1-hd" for higher quality audio
        input: "Today is a wonderful day to build something people love!",
        voice: "echo"  // Choose a voice (e.g., "alloy", "echo", "fable", etc.)
    })
})
.then(response => response.blob())
.then(blob => {
    const link = document.createElement("a");
    link.href = URL.createObjectURL(blob);
    link.download = "speech.mp3";
    link.click();
})
.catch(error => console.error("Error:", error));