Overview

TTSFM is a free Text-to-Speech API service that provides OpenAI-compatible endpoints using the openai.fm service. It supports multiple voices, audio formats, speed adjustment, and automatic text splitting for long content.

Key Features

• 🎤 Multiple Voices: 6 voices (alloy, echo, fable, onyx, nova, shimmer)
• 🎵 Audio Formats: MP3, WAV (always available) + OPUS, AAC, FLAC, PCM (requires ffmpeg)
• 🤖 OpenAI-Compatible API: Drop-in replacement for OpenAI's TTS API
• ⚡ Speed Adjustment: 0.25x to 4.0x playback speed (requires ffmpeg)
• 🔄 Format Conversion: Real ffmpeg-based audio format conversion
• ✨ Auto-Combine: Automatic splitting and combining for long text
• 🐳 Docker Images: Full (with ffmpeg) and Slim (without ffmpeg) variants
• 📊 Capabilities API: Runtime feature detection and availability checking

Docker Image Variants

TTSFM provides two Docker image variants to suit different needs:

Authentication

API key authentication is optional and disabled by default. When enabled, include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Set REQUIRE_API_KEY=true environment variable to enable API key protection.

OpenAI-Compatible API

TTSFM provides a drop-in replacement for OpenAI's Text-to-Speech API. Use the /v1/audio/speech endpoint with the same request format.

{
  "model": "tts-1",
  "input": "Hello, world!",
  "voice": "alloy",
  "response_format": "mp3",
  "speed": 1.0
}

System Capabilities

Check which features are available in the current Docker image variant using the capabilities endpoint.

{
  "ffmpeg_available": true,
  "image_variant": "full",
  "features": {
    "speed_adjustment": true,
    "format_conversion": true,
    "mp3_auto_combine": true,
    "basic_formats": true
  },
  "supported_formats": ["mp3", "wav", "opus", "aac", "flac", "pcm"]
}

Speed Adjustment

Adjust audio playback speed from 0.25x (slower) to 4.0x (faster). This feature requires ffmpeg and is only available in the full Docker image.

curl -X POST http://p.789ai.top/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello!",
    "voice": "alloy",
    "speed": 1.5
  }' --output speech.mp3

Format Conversion

TTSFM supports 6 audio formats with real ffmpeg-based conversion for high-quality output.

Long Text Handling

TTSFM automatically handles long text by splitting it into chunks and combining the audio output. The openai.fm service has a limit of approximately 1000 characters per request.

Python Package Options

• max_length: Maximum characters per chunk (default: 1000)
• validate_length: Raise error if text exceeds limit (default: False)
• preserve_words: Split at word boundaries (default: True)
• auto_combine: Automatically combine chunks (default: True)

Python Package

Install the TTSFM Python package for easy integration into your Python applications.

pip install ttsfm

Basic Usage

from ttsfm import TTSClient, Voice, AudioFormat

# Create client
client = TTSClient()

# Generate speech
response = client.generate_speech(
    text="Hello, world!",
    voice=Voice.ALLOY,
    response_format=AudioFormat.MP3,
    speed=1.0
)

# Save to file
response.save_to_file("output.mp3")

Long Text Support

Automatically split and combine long text:

# Auto-combine mode (single file output)
response = client.generate_speech(
    text="Very long text...",
    voice=Voice.ALLOY,
    response_format=AudioFormat.MP3,
    auto_combine=True  # Default
)
response.save_to_file("combined.mp3")

# Manual chunks mode (multiple files)
responses = client.generate_speech_long_text(
    text="Very long text...",
    voice=Voice.ALLOY,
    response_format=AudioFormat.MP3
)
for i, resp in enumerate(responses, 1):
    resp.save_to_file(f"part_{i:03d}.mp3")

Async Client

from ttsfm import AsyncTTSClient, Voice, AudioFormat
import asyncio

async def main():
    client = AsyncTTSClient()
    response = await client.generate_speech(
        text="Hello, async world!",
        voice=Voice.ALLOY,
        response_format=AudioFormat.MP3
    )
    response.save_to_file("async_output.mp3")

asyncio.run(main())

WebSocket Streaming

Stream audio generation in real-time using WebSocket for better user experience with long text.

WebSocket Endpoint

ws://p.789ai.top/ws/generate

Message Format

{
  "text": "Your text here",
  "voice": "alloy",
  "format": "mp3",
  "speed": 1.0
}

Response Events

• start: Generation started
• chunk: Audio chunk ready (base64 encoded)
• complete: All chunks sent
• error: Error occurred

Error Handling

TTSFM provides clear error messages with helpful hints for troubleshooting.

Common Error Codes

Example Error Response

{
  "error": {
    "message": "Format 'opus' requires ffmpeg. Available formats: mp3, wav",
    "type": "feature_unavailable_error",
    "code": "ffmpeg_required",
    "hint": "Use the full Docker image (dbcccc/ttsfm:latest) instead of the slim variant.",
    "available_formats": ["mp3", "wav"]
  }
}