Audio Guide
How to record and submit audio for the speech models.
Supported formats
| Format | Extension | Notes |
|---|---|---|
| WAV (PCM) | .wav | Best quality |
| FLAC | .flac | Lossless, smaller files |
| OGG / Opus | .ogg | Good quality, small size |
| MP3 | .mp3 | Widely supported |
| WebM | .webm | Browser MediaRecorder default; works directly. |
| Raw PCM Int16 | - | Streaming clients only. 16 kHz mono. |
Audio requirements
| Requirement | Value |
|---|---|
| Sample rate | 16 kHz or higher. Models work with 16 kHz audio internally. |
| Channels | Mono preferred. Stereo is accepted but converted to mono. |
| Duration | Up to 300 seconds per request or stream (maxAudioDurationSeconds). Longer recordings, up to 4 hours, go through transcription jobs. |
| File size | Up to 15 MB per request (maxFileSizeBytes). Use POST /v1/asr/upload (multipart) for files; POST /v1/asr (JSON) is best for short clips already in memory. |
Recording tips
| Tip | Why |
|---|---|
| Quiet environment | Background noise significantly reduces accuracy. |
| Consistent distance | Keep 15-30 cm from the microphone. Too close distorts, too far loses clarity. |
| Natural pace | Conversational pace. Rushing or over-slow speech both hurt recognition. |
| Avoid echo | Hard-surfaced rooms reflect sound. Soft furnishings absorb it. |
Common issues
| Issue | Solution |
|---|---|
| Low accuracy despite clear audio | Check the locale parameter matches the spoken language. Mixing languages reduces accuracy. |
| Empty or very short transcript | Ensure the audio contains actual speech, not just silence. |
| 400 with reason asr_unreadable_audio | The audio could not be read as a container, so its length could not be measured. Try re-encoding to WAV 16 kHz mono. |
Reference clips for TTS custom voices
Custom-voice synthesis (POST /v1/tts with voice.reference) clones a speaker from a short clip plus an exact transcript. The same audio quality guidance above applies; the requirements specific to a reference clip are below. Preset voices (voice.preset) skip this entirely. Consent travelled with the voice when it was added.
| Requirement | Value |
|---|---|
| Duration | 5-15 seconds. Shorter clips don’t carry enough timbre; longer ones get truncated. |
| Speakers | Exactly one speaker. Overlapping voices or background dialogue blur the speaker embedding. |
| Format | WAV, MP3, M4A, OGG or WebM, 16 kHz or higher, mono; converted to WAV for the model. A clip that cannot be read as audio is refused with reference_audio_unreadable. |
| Size | Up to maxReferenceAudioBytes on GET /v1/tts/limits; a larger clip is refused with reference_audio_too_large. The model keeps at most 12 s. |
| Transcript | Provide the exact transcript of the reference clip as voice.reference.transcript. NFC-normalize Ge’ez text. Mismatched transcripts distort the output. |
| Source | Use natural speech, not TTS-generated or heavily processed audio. Music or background noise degrades the cloned voice. |
| Language match | Reference speech, reference transcript, and the synthesis target text should all be in the same language. Today only Tigrinya (tir) is deployed. |
Reference-clip common issues
| Issue | Solution |
|---|---|
| 412 attestation_required | Custom-reference TTS needs a one-time per-key custom-voice rights attestation. Accept it on /keys, then retry. |
| Output voice doesn’t match the reference | Most often a transcript mismatch. Re-listen, transcribe again, NFC-normalize. If the reference is < 5 s or contains music, the model can’t lock the voice. Supply a cleaner clip. |
| 400 reference_audio_too_long | For device keys (dk_live_*), the clip runs longer than deviceMaxReferenceAudioSeconds on GET /v1/tts/limits. For any key, the model reads shorter samples (limits.maxReferenceSeconds on GET /v1/models) and the clip could not be cut to fit. Send a shorter clip with its matching transcript, or use a model without that limit. |