Flow TTS API Documentation

🔐 Authentication

All API requests require authentication using a JWT (JSON Web Token). You can obtain a JWT token by logging into your account at app.realtime-ai.chat.

Getting Your JWT Token

To authenticate your API requests:

1. Log in to your account at app.realtime-ai.chat
2. Open browser DevTools (F12) and run: console.log(window.SupabaseAuthInject.getSession()?.access_token)
3. Copy the JWT token from the console output
4. Include the token in all API requests using the Authorization header

Request Headers

Include the following headers in all authenticated requests:

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Token Expiration

JWT tokens expire after 1 hour. If you receive a 401 Unauthorized error, refresh your browser and obtain a new token.

📡 API Endpoints

The Flow TTS API provides four main endpoints for text-to-speech synthesis and voice management.

Base URL

https://api.realtime-ai.chat

{
  "code": "success",
  "message": "TTS synthesis completed successfully",
  "data": {
    "audio": "base64_encoded_audio_data...",
    "format": "wav",
    "sampleRate": 24000,
    "duration": 3.5
  },
  "quota": {
    "daily": 100,
    "used": 42,
    "remaining": 58
  }
}

curl -X POST https://api.realtime-ai.chat/api/tts/synthesize \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a test.",
    "ttsConfig": {
      "TTSType": "flow",
      "VoiceId": "v-female-R2s4N9qJ",
      "Model": "flow_01_turbo",
      "Speed": 1.0,
      "Volume": 5.0,
      "Language": "en"
    }
  }'

data: {
  "Type": "audio",
  "ChunkId": 1,
  "Audio": "base64_audio_chunk...",
  "IsEnd": false
}

data: {
  "Type": "audio",
  "ChunkId": 2,
  "Audio": "base64_audio_chunk...",
  "IsEnd": true
}

const response = await fetch('https://api.realtime-ai.chat/api/tts/synthesize-stream', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Hello, this is streaming TTS.',
    ttsConfig: {
      TTSType: 'flow',
      VoiceId: 'v-female-R2s4N9qJ',
      Model: 'flow_01_turbo',
      Language: 'en'
    }
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  // Process SSE events
  console.log(chunk);
}

{
  "code": "success",
  "message": "Voice cloned successfully",
  "data": {
    "voiceId": "clone-abc123xyz",
    "name": "My Custom Voice",
    "duration": 8.5,
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "quota": {
    "daily": 100,
    "used": 52,
    "remaining": 48
  }
}

{
  "voices": [
    {
      "id": "v-female-R2s4N9qJ",
      "name": "小芮",
      "description": "女声客服",
      "language": "zh-CN",
      "gender": "female"
    },
    {
      "id": "male-qn-qingse",
      "name": "青涩青年音色",
      "description": "男声",
      "language": "zh-CN",
      "gender": "male"
    }
  ]
}

curl https://api.realtime-ai.chat/api/tts/voices

🚀 TTS Model: flow_01_turbo

Flow TTS is powered by the flow_01_turbo model, specifically optimized for conversational scenarios.

Key Features

• Ultra-Low Latency: As low as 300ms, ideal for real-time conversations and live dubbing
• High Quality: Natural, human-like speech with strong expressiveness and colloquial tone
• Multi-Language Support: Chinese (zh), English (en), Japanese (ja), Korean (ko), Cantonese (yue)
• Streaming Support: SSE-based streaming for edge-to-edge playback with minimal delay
• Voice Cloning: Create custom voices from 4-12 second audio samples

Configuration Parameters

The flow_01_turbo model supports the following configuration options:

{
  "TTSType": "flow",          // Required: Fixed value "flow"
  "VoiceId": "xxxx",          // Required: Premium voice ID or cloned voice ID
  "Model": "flow_01_turbo",   // Optional: Default is flow_01_turbo
  "Speed": 1.0,               // Optional: Speech speed [0.5, 2.0], default 1.0
  "Volume": 1.0,              // Optional: Volume (0, 10], default 1.0
  "Pitch": 0,                 // Optional: Pitch [-12, 12], default 0
  "Language": "zh"            // Strongly recommended: ISO 639-1 language code
}

💡 Tip: Always specify the Language parameter to ensure optimal pronunciation and natural pauses. Use "yue" for Cantonese.

🎙️ Voice Library

Flow TTS offers a diverse collection of high-quality neural voices across multiple languages and speaking styles. All voices are powered by the flow_01_turbo model for natural, expressive speech.

Featured Voices

Our most popular voices for common use cases:

To explore the complete voice library with audio samples, visit the TTS Studio or call the GET /api/tts/voices endpoint.

💎 Quota & Pricing

Flow TTS uses a quota-based pricing model. Each API request consumes quota points based on the operation type.

Quota Consumption

Pricing Tiers

Contact Sales for Enterprise

⚠️ Error Handling

The API uses standard HTTP status codes and returns detailed error information in JSON format.

Common Error Codes

Error Response Format

{
  "code": "quota_exceeded",
  "message": "Daily quota limit reached. Resets at 00:00 UTC.",
  "quota": {
    "daily": 100,
    "used": 100,
    "remaining": 0,
    "resetAt": "2025-01-16T00:00:00Z"
  }
}

🚦 Rate Limits

To ensure fair usage and system stability, the following rate limits apply:

• Requests per minute: 60 requests
• Concurrent requests: 5 simultaneous connections
• Daily quota: Based on your pricing tier (100/500/2000)
• Maximum text length: 5000 characters per request
• Voice clone audio: 4-12 seconds duration

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642348800

📦 SDKs & Libraries

Official SDKs and community libraries to accelerate your development:

More SDKs and examples available in our GitHub repository. Complete examples for multiple languages and scenarios are provided.

✨ Best Practices

Performance Optimization

• Use streaming TTS (/api/tts/synthesize-stream) for long texts to reduce latency
• Cache generated audio files to avoid redundant API calls
• Implement exponential backoff for retries on 429/500 errors
• Use connection pooling for high-volume applications

Voice Cloning Tips

• Provide clear, noise-free audio samples (4-12 seconds)
• Use single-speaker recordings without background music
• Ensure consistent audio quality (16kHz mono recommended)
• Test cloned voices with diverse text before production use

Security

• Never expose JWT tokens in client-side code or public repositories
• Rotate tokens regularly (every 24 hours recommended)
• Use HTTPS for all API requests
• Implement proper error handling to avoid leaking sensitive information

💬 Support

Need help with integration? Our support team is here to assist you.