Transcript errors
Are you joining transcripts correctly?
Are you joining transcripts correctly?
Each Include every Don’t trim Don’t join
transcript event carries a delta: only the text since the last final transcript, not the full transcript for the audio. Append the text from every event where is_final is true:transcript event where is_final is true:text:text with a space in between:Did you drain all events?
Did you drain all events?
When you’re done sending audio for a session, send
"close". The model then flushes any buffered audio and sends the remaining transcript events. Once all audio is processed, the server sends { "type": "done" } and then closes the socket for you.The server buffers some audio to improve transcription accuracy. If you don’t send "close", or you stop reading messages early, that buffered audio isn’t processed. That’s fine if you don’t care about the last second of audio.Are you using a supported language?
Are you using a supported language?
ink-2 supports English, French, Hindi, Japanese, and Spanish. ink-preview supports 44 languages. Both detect the language automatically. With ink-preview, you can also pass language hints to steer it toward the languages you expect.Did you pass the right language hints?
Did you pass the right language hints?
With
ink-preview, we recommend passing language hints whenever you know which languages to expect. Hints improve accuracy, especially on short or noisy audio and on closely related languages. They also keep the transcript in the right script. Only ink-preview takes hints. Other models return an error if you pass them.Are you using the right sample rate and encoding?
Are you using the right sample rate and encoding?
The model decodes your bytes using the If the playback sounds wrong, your
encoding and sample_rate you declared in the connection. If these parameters are wrong, the server might not return an error.To check them, save your audio data and play it back with ffplay:encoding or sample_rate doesn’t match the data. The difference is usually obvious. Correct the values until your audio plays back cleanly, then send those same values to the API.See Audio Input for help finding the right parameters.Are you finalizing too often?
Are you finalizing too often?
Send
finalize only after the user has finished speaking. Finalizing mid-speech produces transcription errors.High latency
Are you sending the finalize command?
Are you sending the finalize command?
The Without it, the model falls back to silence-based auto-finalization. That’s slower by design, because it waits out a pause to be sure the user is done.Send
finalize command triggers transcription. To finalize the turn, send it after your user signals they’re done speaking, or after your VAD detects they stopped:finalize as many times as you need. Don’t confuse it with close, which closes the session permanently.Only send finalize at sensible moments in the audio stream. Finalizing mid-speech produces transcription errors.Are you using the right endpoint?
Are you using the right endpoint?
If you don’t know when your user starts and stops speaking, try Realtime STT (Auto). Our model detects turn boundaries and sends the final transcript as soon as your user is done speaking.Switching from Realtime STT (Manual) to Realtime STT (Auto) improves final transcript latency out of the box. That’s because Realtime STT (Manual) holds on to the last transcript chunk of user speech, expecting your client to send
finalize.Realtime STT (Auto) expects nothing from your client except audio. It sends the final transcript in a turn.end event as soon as it’s ready.Did you stop sending audio?
Did you stop sending audio?
The API expects a continuous stream of audio, so send silence (all zeros) while your audio input is muted.If you stop sending audio, the server waits for more audio chunks to arrive rather than assuming the user is silent. This is normally what you want, because it handles network lag.
Server errors
Are you chunking audio?
Are you chunking audio?
The realtime WebSocket endpoints expect audio to arrive at roughly the rate it’s spoken. If you push a large batch of audio into the socket at once, you can overload the server-side buffer. This may show up as an internal server error.Stream audio in small chunks of about 100 ms each, and pace them to realtime. On average, send one second of audio per second of wall-clock time. Here’s a JavaScript example.To transcribe a complete file in one go, use Batch STT, which takes the whole file in a single request.