Skip to main content

Overview

The NanoGPT TTS API allows you to convert text into natural-sounding speech using various models from different providers. The API supports multiple languages, voices, and customization options including speed control, voice instructions, and audio format selection. For voice cloning (create a reusable custom voice from a reference clip), see api-reference/endpoint/voice-cloning.mdx.

Music generation

NanoGPT also supports text-to-music generation via the OpenAI-compatible POST /v1/audio/speech endpoint when you use a music model. See api-reference/music-generation.mdx.

Available Models

  • Kokoro-82m: High-quality multilingual model with 44 voices ($0.001/1k chars)
  • Elevenlabs-Turbo-V2.5: Premium quality with 46 voices and style controls ($0.06/1k chars)
  • Elevenlabs-V3: ElevenLabs expressive model family
  • tts-1: OpenAI’s standard quality model with low latency ($0.015/1k chars)
  • tts-1-hd: OpenAI’s high definition model ($0.030/1k chars)
  • gpt-4o-mini-tts: Ultra-low cost OpenAI model ($0.0006/1k chars)
  • MiniMax Speech models: Supports cloned voices via custom voice IDs
  • Qwen-3-TTS-1.7B: Supports cloned voices via speaker embeddings

Gemini preview TTS retirement (December 18, 2026)

Google shuts down three preview speech models on December 18, 2026: Both replacements are available now. Gemini 3.8 Flash TTS costs $0.05 and Gemini 3.8 Flash-Lite TTS costs $0.03 per 1,000 spoken characters, with no per-request minimum. Voice instructions are not billed. What happens on the retirement date. We keep serving each old model ID for as long as Google does. Once that ID can no longer be served, requests to it return HTTP 410 with code TTS_MODEL_UNAVAILABLE and an error message that names the replacements (POST /api/tts also returns them in a replacements array; POST /v1/audio/speech uses the OpenAI error envelope). These requests are not charged. We never switch a request to a different model without telling you. Switch to a 3.8 model yourself, before or after the date.

Moving a request to Gemini 3.8

Most narration requests only need a new model value. The same 30 voices are available (for example Kore and Puck), though a voice can sound slightly different on the new model. Check these points:
  1. Keep directions out of input. Gemini 3.8 reads input word for word. Directions written into the text (such as “Say cheerfully: …”) will be spoken aloud. Send them in instructions instead. They control tone, emotion, accent and pace, and they are never spoken or billed.
  2. Use angle-bracket vocal tags. Inline events such as <laugh>, <sigh>, <breath> and <short pause> go directly in input.
  3. Send dialogue as turns. Instead of Speaker: line prefixes in one string, send input as an array of turns with exactly two distinct voices (Gemini 3.8 Flash TTS only; Flash-Lite is single-speaker):
  1. WAV output, no speed control. Gemini 3.8 returns WAV audio. response_format, if sent, must be wav, and speed must be 1 (use instructions such as “speak slowly” to change pace).
  2. Input limit. The complete input is limited to 8,192 tokens; turn-array input is also limited to 8,192 bytes after normalization and 100 turns.
Narration example:

Streaming support in POST /v1/audio/speech

Set stream: true to request chunked audio streaming. Default remains buffered (stream: false). Other TTS models (for example Kokoro, Gemini, Qwen, MiniMax, Inworld) ignore stream and return buffered audio.

Authentication

All requests require authentication via API key:

Synchronous vs Asynchronous

  • Synchronous: POST /v1/audio/speech returns audio bytes directly. Best for UI playback and short prompts. See api-reference/endpoint/speech.mdx.
  • Asynchronous: POST /tts returns a ticket; poll GET /tts/status for completion. Best for long audio, batch jobs, and webhook workflows.

Basic Text-to-Speech

Simple TTS Request

Async Status & Polling

Some TTS models (e.g., Elevenlabs family) run asynchronously. If POST /api/tts returns HTTP 202 with status: "pending", poll GET /api/tts/status?runId=...&model=... until you receive status: "completed" with an audioUrl. See endpoint details in GET /api/tts/status.

Model-Specific Examples

Kokoro-82m - Multilingual Voices

Kokoro supports 44 voices across 13 language groups:

Elevenlabs-Turbo-V2.5 - Premium Quality with Controls

Elevenlabs offers advanced voice control options:

OpenAI Models - Multiple Formats and Instructions

OpenAI models support various audio formats and voice instructions:

Complete TTS Class Implementation

Here’s a comprehensive TTS class with all model support:

Best Practices and Tips

Character Limits and Costs

Voice Selection Guide

Error Handling and Troubleshooting

Pricing Summary