Speech (Text-to-Speech) API Usage Guide

Generate lifelike speech audio from text using Radient's Speech API. Ideal for assistants, IVR systems, accessibility features, and any application that needs high-quality audio output on demand.

This guide shows how to call the endpoint, control the voice, format, and speed, and save the audio result.

#Core Concepts

The Speech API uses the /v1/speech endpoint and returns an audio file stream.

Key features:

• Multiple voices and quality levels (models tts-1, tts-1-hd, gpt-4o-mini-tts).
• Choose audio format (mp3, opus, aac, flac, wav, pcm) and playback speed.
• Provider-aware (currently OpenAI-compatible).

#Text-to-Speech

Convert text to speech and save the resulting audio file locally.

Endpoint: POST /v1/speech

• Consumes: application/json
• Produces: audio/mpeg (when response_format is mp3; content type may vary by format)

Example Request (Python using requests):

import requests

RADIENT_API_KEY = "YOUR_RADIENT_API_KEY"
RADIENT_BASE_URL = "https://api.radient.com/v1"  # Or your specific Radient API endpoint

headers = {
    "Authorization": f"Bearer {RADIENT_API_KEY}",
    "Content-Type": "application/json",
    # "Accept": "audio/mpeg"  # Optional; server will stream audio back
}

payload = {
    "input": "Hello! This is a test of Radient's text-to-speech service.",
    "model": "tts-1",               # or "tts-1-hd", "gpt-4o-mini-tts"
    "voice": "alloy",               # "alloy", "ash", "ballad", "coral", "echo", "fable", "onyx", "nova", "sage", "shimmer", "verse"
    "response_format": "mp3",       # "mp3", "opus", "aac", "flac", "wav", "pcm"
    "speed": 1.0,                   # between 0.25 and 4.0
    "provider": "openai"            # optional, currently "openai"
}

response = requests.post(f"{RADIENT_BASE_URL}/speech", headers=headers, json=payload, stream=True)

if response.status_code == 200:
    # Save the streamed audio to a file
    output_filename = "speech_output.mp3"  # match response_format
    with open(output_filename, "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            if chunk:
                f.write(chunk)
    print(f"Saved audio to {output_filename}")
else:
    # If not 200, the endpoint returns JSON error details
    try:
        print("Error:", response.status_code, response.json())
    except Exception:
        print("Error:", response.status_code, response.text)

#Request Body (JSON)

#Responses

• 200 OK: Audio stream (file). Content type corresponds to the chosen response_format (e.g., audio/mpeg for mp3).
• 400 Bad Request: Invalid fields or missing parameters (JSON body with error details).
• 500 Internal Server Error: Unexpected server issue.

#Tips and Best Practices

• Use tts-1-hd for higher fidelity when latency is less critical; tts-1 for lower-latency needs.
• Select mp3 for broad compatibility; consider opus for very low bitrate/high quality in supported clients.
• Keep input under ~4k characters per request; chunk longer text and combine outputs client-side.
• Cache or reuse generated clips if the same text is requested frequently to reduce latency and cost.

For a full list of API endpoints and schemas, see the main API Reference.