Text-to-Speech

#Use it when

• You need voice playback in an app
• You want narration, announcements, or assistant voice output

#Code examples

1curl -X POST https://api.navy/v1/audio/speech \
2  -H "Authorization: Bearer sk-navy-YOUR_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "gpt-4o-mini-tts",
6    "voice": "alloy",
7    "input": "Welcome to the NavyAI platform."
8  }' \
9  --output speech.mp3

#Parameters

• model (string, required) — tts-1, tts-1-hd, eleven_v3, gpt-4o-mini-tts, gemini-2.5-flash-preview-tts
• input (string, required) — Text to convert (max 4096 chars for ElevenLabs)
• voice (string, required) — Voice ID. OpenAI: alloy, ash, coral, echo, fable, nova, onyx, sage, shimmer. ElevenLabs: alice, aria, bill, brian, callum, charlie, charlotte, chris, daniel, eric, george, jessica, laura, liam, lily, matilda, river, sarah, will. Gemini: Puck, Charon, Kore, Fenrir, Aoede
• speed (number, optional) — 0.25–4.0 (OpenAI models only)
• response_format (string, optional) — mp3, opus, aac, flac (OpenAI only). ElevenLabs always returns audio/mpeg; Gemini always returns audio/wav.
• stability (number, optional) — ElevenLabs only. 0.0–1.0, defaults to 0.5. Lower values are more expressive, higher values are more consistent.
• similarity_boost (number, optional) — ElevenLabs only. 0.0–1.0, defaults to 0.5. Higher values stick closer to the cloned voice.
• with-timestamps (boolean, optional) — ElevenLabs only. If true, returns JSON with per-character timestamps instead of raw audio. Useful for karaoke-style highlights.
• pronunciation_dictionary (array, optional) — Rules controlling how specific words are pronounced. See below.

#Pronunciation dictionaries

Names, acronyms, and loanwords are the usual reason a generation comes out wrong. Pass a pronunciation_dictionary to fix them. NavyAI applies the rules to your text before sending it upstream, so there is nothing to upload, register, or manage — the rules travel with each request.

1curl -X POST https://api.navy/v1/audio/speech \
2  -H "Authorization: Bearer sk-navy-YOUR_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "eleven_flash_v2",
6    "voice": "alice",
7    "input": "Drive through Claughton and buy a tomato.",
8    "pronunciation_dictionary": [
9      { "string_to_replace": "Claughton", "type": "alias", "alias": "Cloffton" },
10      { "string_to_replace": "tomato", "type": "phoneme",
11        "alphabet": "cmu-arpabet", "phoneme": "T AH0 M EY1 T OW2" }
12    ]
13  }' \
14  --output speech.mp3

Each rule is an object:

• string_to_replace (string, required) — The word or phrase to match. Max 200 characters.
• type (string, required) — alias or phoneme.
• alias (string, required for alias rules) — A plain-text respelling, e.g. Cloffton for Claughton. No phonetic knowledge needed.
• phoneme (string, required for phoneme rules) — The pronunciation itself. ph is accepted as an alias for this field.
• alphabet (string, required for phoneme rules) — ipa or cmu-arpabet.
• case_sensitive (boolean, optional) — Defaults to true.
• word_boundaries (boolean, optional) — Defaults to true, so cat will not match inside concatenate.

Max 100 rules per request. When two rules overlap, the longer string_to_replace wins, and a rule never re-matches text that another rule already produced.

#Pronunciation model support

• Alias rules work on every text-to-speech model, including OpenAI and Gemini.
• Phoneme rules work on eleven_flash_v2 and eleven_turbo_v2 (both alphabets) and on eleven_v3 (ipa only).
• On any other model, phoneme rules are skipped, the original word is left exactly as written, and the response carries an X-Navy-Pronunciation-Warnings header naming the reason. The warnings also appear in the JSON body when with-timestamps is set, and on the job object for async requests. Alias rules in the same request still apply.

#Notes

• Response content-type depends on the provider: OpenAI uses the response_format you set, ElevenLabs returns audio/mpeg (or JSON when with-timestamps is true), Gemini returns audio/wav (24 kHz mono PCM in a WAV container).
• ElevenLabs caps input at 4,096 characters. Longer text must be chunked client-side. Phoneme rules expand into inline tags that count toward the same cap.
• Long generations can outlive the connection and return a 524. See the Async Text-to-Speech Jobs page — the audio is generated off the request and kept for you instead of being lost.
• Keep text chunks moderate if you need responsive playback.