---
name: omi-api
description: >-
  Integrate or evaluate Omi speech-to-text APIs: choose realtime versus batch,
  pin medical or general models, handle async results and retention, and run
  reproducible transcription evaluations. Use when working with api.omi.health,
  api.eu.omi.health, api.us.omi.health or an Omi API integration.
---

# Omi API

Use the customer's requested transport and model. For live audio use
`wss://api.omi.health/v1/stream`, not repeated batch uploads. For recorded
audio use `POST https://api.omi.health/v1/audio/transcriptions` and handle both
200 (result) and 202 (job). `omi-medical-edge-1` is batch-only.

## Regions and hosts

The hostname selects the processing region; one API key and the same features
work on all three. Audio, jobs and results stay in the processing region. Make
the host a configuration value and do not switch a customer's region unless
they ask, because it is their regional instruction under the DPA.

- `api.eu.omi.health`: EU (Frankfurt) only.
- `api.us.omi.health`: US only. Recommend it for teams or users in the Americas.
- `api.omi.health`: each request routes to the nearest healthy EU or US region
  with Frankfurt fallback.

Follow returned `poll_url`s; never rebuild job URLs on another host. The
evaluation runner takes `--url https://api.us.omi.health` (batch) or
`--url wss://api.us.omi.health/v1/stream` (realtime). Record the host used.
Details: https://docs.omi.health/docs.md#regions--endpoints

Read [realtime.md](references/realtime.md) for streaming and its clocks, or
[batch.md](references/batch.md) for files, vocabulary, jobs and privacy.
The maintained public guide is https://docs.omi.health/agents.md;
the HTTP schema is https://docs.omi.health/openapi.yaml.
Check current docs before assuming a new feature or a limit.

## Integration decisions that matter

- Explicitly select `omi-medical-1` or `omi-general-1`. On streaming, verify
  `ready.model.served` matches the request before sending audio; do not silently
  substitute a model or transport.
- Realtime vocabulary is **not currently supported**. Batch Medical supports
  vocabulary; General and hosted Edge do not. A request that includes an
  undocumented streaming field does not prove that it was applied. Explain
  this when asked for streaming vocabulary on/off comparisons.
- Replace mutable partial revisions for each turn; never append them as new
  words. Keep confirmed turns separate from the closing session record.
- Live speaker attribution is optional. If the application already knows
  participants through separate audio channels, it may not need diarization.
- Keep API keys in `OMI_API_KEY` or a secret store, not in generated code,
  transcripts, source control, browser bundles or reports. Do not create keys
  or change billing/settings unless the customer asks for that action.
- A 402 billing error needs billing action, not repeated retries. Respect
  `Retry-After` on temporary capacity errors. Do not silently remove requested
  speakers, vocabulary or privacy requirements to obtain a success.

## Evaluations

Use [evaluation.md](references/evaluation.md) and the packaged
`scripts/evaluate.py` instead of improvising a streaming harness. Python 3.10+
and `pip install -r scripts/requirements.txt` are required. The runner takes
mono PCM16/16 kHz WAVs; convert other formats locally first.

Run `--dry-run` first to inspect audio hours and the request configuration.
Then run a small smoke before the full set. Preserve failures and attempt
history, identify client location, report coverage, and score confirmed text
and closing records separately. Local result files contain transcripts; keep
them private. Never publish patient audio or transcripts without permission.
Resume only matching input/configuration hashes; failed requests remain
failures unless `--retry-failed` is explicitly requested.

For vocabulary comparisons use paired **batch Medical** runs with
`dictionary=false`, one without terms and one with the encounter list. Inspect
the vocabulary audit, distinguishing `prompt_status` from `delivered_terms`.
Do not label that experiment realtime. Do not claim a vocabulary benefit from
a successful HTTP response alone.