# Omi Medical Speech-to-Text documentation

> Public developer documentation for the Omi Medical STT API.

## Start here

- [Overview](https://docs.omi.health): Choose synchronous or asynchronous transcription and run a first request.
- [Synchronous transcription](https://docs.omi.health/transcription): Multipart fields, response formats, models, and examples.
- [Asynchronous transcription](https://docs.omi.health/async): Direct-upload 202 dispatch, presigned large uploads, polling, results, idempotency, and retention.
- [Production checklist](https://docs.omi.health/production): Credential safety, idempotency, retries, observability, retention, model builds, and status.

## Deployment

- [Open-source local runtime](https://docs.omi.health/edge): Run Omi Med STT v1 on Apple Silicon, a CUDA-capable GPU, or Linux/Windows CPU.
- [Realtime API](https://docs.omi.health/realtime): WebSocket start shape, confirmed/final events, optional live speakers, pricing, and capacity.

## Features

- [Languages](https://docs.omi.health/languages): en/es/pt/fr/de/nl/ar/hi, regional aliases, explicit language selection, and per-utterance language=auto.
- [Vocabulary and Patterns](https://docs.omi.health/context): Encounter term lists, stored dictionaries, safety fallback, and request-scoped structured-token patterns.
- [Speakers and timestamps](https://docs.omi.health/speakers): Speaker diarization and acoustic word timestamps without transcript mutation.
- [Webhooks](https://docs.omi.health/webhooks): Standard Webhooks signatures, retries, destination safety, and secret rotation.

## Reference

- [API reference](https://docs.omi.health/reference): Authentication, endpoints, every public field, schemas, limits, errors, retries, and data handling.
- [OpenAPI 3.1](https://console.omi.health/openapi.yaml): Curated customer-facing HTTP contract.
- [Complete Markdown guide](https://docs.omi.health.md): Compact machine-readable documentation.
- [Service status](https://status.omi.health/): Independent service probes.
- [Changelog](https://docs.omi.health/changelog): Dated contract, region, limit, and model-build changes.

## Important contract notes

- Base URL: https://api.omi.health
- Authorization: Bearer <OMI_API_KEY>
- Omi Medical STT is an English-first medical speech model.
- English is the benchmarked and medically evaluated language.
- es/pt/fr/de/nl/ar/hi were included in training and are available for testing and evaluation; they are not medically evaluated and should not be relied on for medical accuracy.
- Omitted language uses bounded dominant-language detection on every plan. Explicit language=auto enables per-utterance routing on every plan.
- Batch transcription is generally available to all API keys.
- The direct-upload front door accepts up to exactly 100,000,000 bytes and returns either inline 200 or async 202.
- Files longer than 60 seconds use the asynchronous-optimized pipeline.
- For long recordings, prefer the presigned job flow and poll with `wait=20&include_result=true`; it returns on state changes and can include terminal JSON up to 4 MiB inline.
- Files above the direct cap use the presigned large-upload path up to 1 GiB.
- Realtime is available on every plan at wss://api.omi.health/v1/stream, shares the monthly 25-hour allowance, and is $0.45/audio-hour afterward on Pay as you go.
- Realtime sessions and live-speaker rooms are admitted from separate bounded pools. Excess starts close with 1013 TOO_MANY_STREAMS (text pool) or SPEAKER_CAPACITY_FULL (speaker pool) before audio.
- Live speaker activity is opt-in and provisional. Use the batch endpoint for word timestamps and canonical speaker labels.
- Realtime drafts are mutable; confirmed events provide stable utterance text and the closing final event assembles the record. Live-speaker labels are provisional and cannot rewrite transcript wording.
- Async jobs accept 1 second to 7,200 seconds (2 hours) of audio; the job envelope is authoritative.
- omi-medical-1 has one authoritative profile: default. Omit profile or send profile=default. Historical standard and turbo values are deprecated aliases with identical behavior.
- omi-medical-1 is the only hosted API model. The downloadable local runtime is a separate deployment option documented at /edge.
- Dutch can return word timestamps. Arabic and Hindi remain segment-timing only.
- Every error response is exactly {"error": {"code": ..., "message": ...}}; branch on error.code.
- 402 billing_blocked, 403 entitlement_denied, 503 capacity_unavailable are explicit, documented outcomes.
- All processing runs in the EU (eu-central-1) on both api.omi.health and api.eu.omi.health.
- Custom vocabulary considers lists of up to 50 terms in full; larger lists (up to 1,000) select the 50 most relevant. In verbose output, delivered_terms reports returned transcript outcome while prompt_status/prompted_chunks report request coverage.
- Patterns are available on every plan.
- Published benchmark claims apply to English.