Feature guide
Speaker diarization and word timestamps
Attach who-spoke-when metadata to the final transcript. Speaker labels and timestamps never change transcript wording.
Request diarization
curl https://api.omi.health/v1/audio/transcriptions \
-H "Authorization: Bearer $OMI_API_KEY" \
-F file=@consultation.wav \
-F model=omi-medical-1 \
-F language=en \
-F response_format=verbose_json \
-F diarize=trueUse response_format=verbose_json and diarize=true. Async job JSON accepts the same Boolean plus max_speakers from 1 through 4. The synchronous endpoint uses the service default speaker maximum.
Response shape
{
"text": "Where does it hurt? My chest, mostly.",
"segments": [
{"id":"seg_0001","speaker":"A","text":"Where does it hurt?","start":0.32,"end":1.44},
{"id":"seg_0002","speaker":"B","text":"My chest, mostly.","start":1.76,"end":2.93}
],
"words": [
{"word":"Where","start":0.32,"end":0.58,"speaker":"A"},
{"word":"My","start":1.76,"end":1.91,"speaker":"B"}
],
"speakers": [{"speaker":"A"},{"speaker":"B"}],
"speaker_timing": {"granularity":"word","word_timing":true}
}| Field | Meaning |
|---|---|
segments[].speaker | Anonymous session-local label on a text segment. |
words[].speaker | Speaker mapped to an acoustic word boundary when available. |
speaker_segments[] | Acoustic speaker intervals when word alignment is unavailable for the language. |
speaker_timing | Declares word or segment granularity; clients must not infer word ownership when word_timing is false. |
start / end | Seconds from the start of the input audio. |
Languages without word alignment
Arabic and Hindi currently receive segment speaker labels but no word timestamps. Dutch can return word timestamps. When word timing is unavailable or ambiguous, the transcript is retained and Omi does not guess word ownership from a coarse interval.
{
"text": "مرحبا. كيف حالك؟",
"segments": [
{"id":"seg_0001","text":"Goedemorgen. Hoe gaat het?","start":0.4,"end":3.2}
],
"speaker_segments": [
{"id":"speaker_seg_0001","speaker":"A","start":0.4,"end":1.3},
{"id":"speaker_seg_0002","speaker":"B","start":1.5,"end":3.2}
],
"speaker_timing": {"granularity":"segment","word_timing":false}
}Important semantics
- Speaker labels such as A and B identify clusters within one recording; they are not names or inferred clinical roles.
- Word timestamps are acoustic boundaries and may not exactly match subtitle-style display timing.
- Very short interjections, overlapping speech, strong reverberation, and background speech can reduce attribution quality.
- Consumers should tolerate an unattributed word or speaker transition near overlap.
- Use the same speaker label only within the response that produced it; labels are not stable identities across jobs.
Readable turns and acoustic evidence
Complete sentences in
segments[] are grouped for readable display using the strongest speaker evidence across the sentence. words[] retains the lower-level acoustic timing and speaker evidence. Around overlap, a short acknowledgement can remain ambiguous; clients should prefer segments for reading and words for detailed inspection.Long recordings need no client-side speaker chunking
Upload the complete recording. Omi bounds alignment internally and preserves the final transcript across the complete recording. If optional speaker or timestamp metadata cannot be produced reliably, an async result retains the transcript and marks decoration unavailable for review instead of returning guessed speaker labels.
Global identities are resolved after the recording
The completed-record path reconciles voice evidence across the whole recording, which prevents one person from becoming a new label at a long-audio seam and estimates up to four speakers without forcing a two-person result. Live labels remain provisional until that pass.
Zero text mutation is a product invariant
Diarization, word alignment, and speaker reconciliation can fail explicitly, but they cannot rewrite the final
text field.