Reference

API reference

The public HTTP and WebSocket contract in one place. This reference lists customer-facing endpoints; internal and administrative endpoints are not part of the public contract.

Download OpenAPI 3.1 llms.txt Docs as Markdown

Authentication

Use Authorization: Bearer <OMI_API_KEY> on every HTTP request and native WebSocket handshake. API keys are tenant credentials; keep them server-side and rotate them from the console.

Do not ship API keys in browser bundles

Browser applications should call a trusted backend or use a scoped access mechanism. The realtime demo’s preview ticket/query path is for controlled access, not for publishing a long-lived tenant key.

Public endpoints

POST/v1/audio/transcriptions

Direct upload: inline result or async job

POST/v1/jobs

Create a presigned large-upload slot

POST/v1/jobs/{job_id}/complete

Freeze upload and enqueue

GET/v1/jobs/{job_id}

Poll job and obtain result URL

DELETE/v1/jobs/{job_id}

Reserved; cancellation is unsupported in v1

WSSwss://rt.omi.health/v1/realtime

Invited realtime preview

Synchronous multipart fields

Field	Type	Default / limit	Availability
`file`	binary	required · exactly ≤100,000,000 bytes	Inline below 30.000 s; otherwise async
`model`	string	required	omi-medical-1, omi-medical-edge-1
`response_format`	enum	diarized_json	text, json, verbose_json, diarized_json
`language`	BCP-47 / auto	stored default, then en	Eight supported families; auto on omi-medical-1
`language_hints`	JSON array string	1–8	Only with language=auto
`dictionary`	boolean	true	Suppress stored terms with false
`vocabulary`	JSON array string	≤1,000 terms	Auto/AR/HI ≤30; ≤96 chars per term
`patterns`	string	≤32 expressions	Invited preview; omi-medical-1
`diarize`	boolean	false	Speaker and word decoration
`webhook_url`	HTTPS URL	optional · port 443	Forces async; requires signing secret

Optional header Idempotency-Key applies only when this request creates an async job. Inline 200 requests accept and ignore it.

Verbose response

{
  "text": "The patient takes metformin 500 mg twice daily.",
  "language": "en",
  "duration": 4.82,
  "model": "omi-medical-1",
  "request_id": "0b0e…",
  "segments": [
    {
      "id": "seg_0001",
      "speaker": "A",
      "text": "The patient takes metformin 500 mg twice daily.",
      "start": 0.22,
      "end": 4.60,
      "confidence": null,
      "language": "en"
    }
  ],
  "words": [
    {"word":"The","start":0.22,"end":0.36,"speaker":"A"}
  ],
  "speakers": [{"speaker":"A"}],
  "metadata": {
    "api_version": "2026-07-01",
    "runtime": "omi-runtime",
    "processing_ms": {"asr": 640, "diarization": 0}
  }
}

Field	Present when	Meaning
`text`	always	Final normalized transcript.
`language`	non-text JSON	Effective language; mixed for multilingual auto; und for silence.
`duration`	verbose_json	Input duration in seconds.
`request_id`	verbose_json	Also available as x-request-id; include it in support requests.
`segments`	verbose_json / diarized_json	Time-ordered transcript segments.
`words`	alignment available	Acoustic word boundaries; speaker included when diarized.
`language_detection`	verbose auto response	Candidates, selected languages, utterance count, and fallbacks.
`vocabulary`	vocabulary used	Public context mode and safety audit.
`patterns`	patterns used	Requested/applied counts and writer evidence.
`metadata`	verbose_json	API version, public runtime label, and processing timing.

Async job objects

{
  "id": "job_…",
  "object": "transcription.job",
  "status": "accepted",
  "created_at": "2026-07-26T01:02:03Z",
  "model": "omi-medical-1",
  "poll_url": "https://api.omi.health/v1/jobs/job_…",
  "webhook": {"requested": false}
}

Direct-upload jobs use accepted, running, succeeded, or failed. The presigned large-upload path also starts in awaiting_upload. A succeeded job contains result.download_url; a failed job contains a stable error.code and safe message.

Limits

Surface	Duration	Upload / capacity	Notes
Direct upload	Up to 30 minutes	100,000,000 bytes	200 below 30.000 s without webhook; otherwise 202 through the asynchronous-optimized pipeline.
Presigned large upload	Up to 30 minutes	1 GiB	Result URL expires after 15 minutes.
Realtime (invited preview)	30 minutes/session	Strict concurrency cap	Capacity rejection includes retry_after.
Vocabulary	per request	1,000 terms	5–30 recommended; auto/AR/HI max 30.
Patterns	per request	32 expressions	Never stored globally.
Auto hints	per request	1–8 candidates	Supported families only.

HTTP errors and retry behavior

Status	Meaning	What your client should do
`400`	Malformed request, unsupported model option, or mismatched content type.	Fix the request; do not retry unchanged.
`401`	Missing or invalid API key.	Verify the bearer token and replace or rotate the credential if needed.
`404`	Unknown or non-owned job.	Check the job ID and the key that created it.
`413`	File or duration exceeds this route.	Move to async or split at a natural silence.
`422`	Unsupported/detected language, invalid vocabulary, pattern, hints, or speaker count.	Correct the field value or candidate set.
`429`	Rate, queue, or capacity limit.	Honor Retry-After with exponential backoff and jitter.
`503`	Temporary backend, detector, storage, or processing-capacity issue.	Honor Retry-After. Do not silently switch language or processing path.
`410`	An Omi-served result surface has expired.	The transcript must be regenerated; an expired signed storage URL uses the storage provider’s native response.

Data handling

Direct uploads that resolve inline are deleted immediately on completion or failure.
Job audio, results, and metadata are owner-scoped and retained for 72 hours.
Operational telemetry stores non-content usage and safety counters, not transcript text.
Use de-identified/test audio during the research preview unless a separate production data agreement is in place.

Availability and support

View independently hosted service probes on the Omi status page. For support, email [email protected] and include the request_id.