API Documentation

Complete reference for the TTSFM Text-to-Speech API

Contents
Overview Authentication Text Validation API Endpoints Voices Audio Formats Generate Speech Batch Processing Status & Health Error Handling Code Examples Python Package

Overview

The TTSFM API provides a modern, OpenAI-compatible interface for text-to-speech generation. It supports multiple voices, audio formats, and includes advanced features like text length validation and batch processing.

Base URL: http://ttsfm.cohook.com/api/

Key Features

  • 11 different voice options
  • Multiple audio formats (MP3, WAV, OPUS, etc.)
  • Text length validation (4096 character limit)
  • Automatic text splitting for long content
  • Batch processing capabilities
  • Real-time status monitoring

Authentication

Currently, the API supports optional API key authentication. If configured, include your API key in the request headers. 

Authorization: Bearer YOUR_API_KEY

Text Length Validation

TTSFM includes built-in text length validation to ensure compatibility with TTS models. The default maximum length is 4096 characters, but this can be customized.

Important: Text exceeding the maximum length will be rejected unless validation is disabled or the text is split into chunks.

Validation Options

  • max_length: Maximum allowed characters (default: 4096)
  • validate_length: Enable/disable validation (default: true)
  • preserve_words: Avoid splitting words when chunking (default: true)

API Endpoints

GET /api/voices

Get list of available voices.

Response Example:
{
  "voices": [
    {
      "id": "alloy",
      "name": "Alloy",
      "description": "Alloy voice"
    },
    {
      "id": "echo",
      "name": "Echo", 
      "description": "Echo voice"
    }
  ],
  "count": 6
}

GET /api/formats

Get list of supported audio formats.

Response Example:
{
  "formats": [
    {
      "id": "mp3",
      "name": "MP3",
      "mime_type": "audio/mp3",
      "description": "MP3 audio format"
    }
  ],
  "count": 6
}

POST /api/validate-text

Validate text length and get splitting suggestions.

Request Body:
{
  "text": "Your text to validate",
  "max_length": 4096
}
Response Example:
{
  "text_length": 5000,
  "max_length": 4096,
  "is_valid": false,
  "needs_splitting": true,
  "suggested_chunks": 2,
  "chunk_preview": [
    "First chunk preview...",
    "Second chunk preview..."
  ]
}

POST /api/generate

Generate speech from text.

Request Body:
{
  "text": "Hello, world!",
  "voice": "alloy",
  "format": "mp3",
  "instructions": "Speak cheerfully",
  "max_length": 4096,
  "validate_length": true
}
Parameters:
  • text (required): Text to convert to speech
  • voice (optional): Voice ID (default: "alloy")
  • format (optional): Audio format (default: "mp3")
  • instructions (optional): Voice modulation instructions
  • max_length (optional): Maximum text length (default: 4096)
  • validate_length (optional): Enable validation (default: true)
Response:

Returns audio file with appropriate Content-Type header.

POST /api/generate-batch

Generate speech from long text by automatically splitting into chunks.

Request Body:
{
  "text": "Very long text that exceeds the limit...",
  "voice": "alloy",
  "format": "mp3",
  "max_length": 4096,
  "preserve_words": true
}
Response Example:
{
  "total_chunks": 3,
  "successful_chunks": 3,
  "results": [
    {
      "chunk_index": 1,
      "chunk_text": "First chunk text...",
      "audio_data": "base64_encoded_audio",
      "content_type": "audio/mp3",
      "size": 12345,
      "format": "mp3"
    }
  ]
}