# Build with AI — Omi API

Give your coding agent this URL: https://docs.omi.health/agents.md.
For a reusable skill with protocol references and a tested evaluation runner,
install the portable `omi-api` package in your project:

```bash
# Claude Code
npx skills add https://docs.omi.health/skills/omi-api.zip --agent claude-code
# Codex
npx skills add https://docs.omi.health/skills/omi-api.zip --agent codex
```

Install in the project whose agent will use it. Reload the agent session if
the skill does not appear. Use `/omi-api` in Claude Code or `$omi-api` in
Codex. The installer is the open-source Skills CLI; inspect the package before
installation. Download without an installer:
https://docs.omi.health/skills/omi-api.zip. Extract `omi-api/` into
`.claude/skills/` for Claude Code or `.agents/skills/` for Codex. Other agents
that support Agent Skills can use the same folder. For an agent without skill
support, give it this page and https://docs.omi.health/docs.md.
Installation does not create an API key, change billing or send audio.
Desktop/chat products may have a separate skill-upload setting; CLI installation
does not automatically enable a skill there.

## Ask your agent

> Use the Omi API skill to evaluate omi-medical-1 on my WAV files through the
> realtime websocket. Run a dry run and a small smoke first. Use my existing
> OMI_API_KEY environment variable. Keep failures, report first visible text,
> confirmed turns and the closing record separately, and identify the served
> model and client location.

The installed skill includes `scripts/evaluate.py`, requirements and the
manifest/output guide. Read the [evaluation reference](https://docs.omi.health/skills/omi-api/references/evaluation.md).
Default concurrency is 1; increase within the project's available limits.
Runs consume the ordinary audio allowance/pricing. Results contain transcripts
and should stay private.

## Choose the right API

Processing regions (same API key and same features on every host; details in
https://docs.omi.health/docs.md#regions--endpoints). Audio, jobs and results
stay in the region that processes the request.

- `api.eu.omi.health`: EU (Frankfurt) only, never falls back to the US.
- `api.us.omi.health`: US only, never falls back to the EU.
- `api.omi.health`: each request routes to the nearest healthy EU or US
  region with Frankfurt fallback.

If the user's team or users are in the Americas, recommend
`api.us.omi.health` / `wss://api.us.omi.health/v1/stream`. Make the host a
configuration value, never hard-code it, and follow returned `poll_url`s
instead of rebuilding job URLs on another host. Do not change a customer's
region without being asked: the host is their regional processing
instruction under the DPA (https://omi.health/legal/dpa).

| Goal | Route | Model and important distinction |
|---|---|---|
| Live microphone / voice agent | `wss://<host>/v1/stream` (host per region above) | Pin `omi-medical-1` or `omi-general-1`; verify `ready.model.served` before sending PCM |
| Transcribe a recording | `POST /v1/audio/transcriptions` | Always handle 200 result and 202 job; compressed input is accepted |
| Vocabulary on/off comparison | Batch `omi-medical-1` | Use explicit terms and `dictionary=false` on both arms; inspect vocabulary audit |
| Live audio with vocabulary | Not currently supported | Do not put batch vocabulary fields into a start message or call batch chunks realtime |
| Hosted open model | Batch `omi-medical-edge-1` | No realtime or vocabulary |

Realtime has no 60-second **batch** cutoff. The server's `ready.max_session_s`
states the live limit. Live-speaker attribution is optional; separate
participant audio channels may already supply speaker identity.

## Realtime contract

Read https://docs.omi.health/realtime. Authenticate in the first JSON start
message, wait for ready, then send raw mono PCM16/16 kHz at audio speed while
receiving concurrently. Replace draft revisions; score `turn_final` events
separately from the closing `canonical_record` (`final_transcript`).
Use `finalize` only when your application explicitly knows the turn ended;
use `stop` to finish the session. Neither first confirmed text from audio
start nor a closing-record delay means automatic post-speech latency.

## Batch, errors and retention

Read https://docs.omi.health/transcription and https://docs.omi.health/async.
The general inline boundary is 60 seconds of audio. Eligible English Medical
already supports ordinary inline delivery up to 15 minutes / 32 MiB without
privacy opt-in; busy/ineligible long requests can become saved jobs.
Direct uploads accept 100,000,000 bytes; presigned jobs accept up to 1 GiB /
2 hours. Audio duration, uploaded bytes, upload deadlines and HTTP idle timeouts
are different limits.

402 `billing_blocked` needs billing action. Respect temporary capacity
`Retry-After`; preserve deterministic failures rather than looping forever.
Never silently substitute models or drop requested features/privacy.

Standard realtime does not save content. Ordinary sync has no saved result,
but may use temporary disk during processing. Async stores audio during
processing and removes it after completion/terminal failure with cleanup
backstops; result TTL defaults to 24 h, configurable 1–72 h (webhooks 9 h floor).
Download is not deletion. `DELETE /v1/jobs/{job_id}/result` returns 204 removed
or 202 pending, then GET 410. Content-free usage metadata remains.

English Medical batch supports zero retention up to 15 minutes / 32 MiB
on every plan at unchanged pricing. Select `X-Omi-Retention: none` or the
console setting: RAM-only, no saved fallback, `language=en`, `dictionary=false`,
json/text/verbose_json, no speakers or custom hints. Content-free usage and
audit metadata remain. Unsupported requests return 422; busy ones 503.
Do not disable it silently to run a vocabulary test.

Machine-readable HTTP schema: https://docs.omi.health/openapi.yaml.
Complete guide: https://docs.omi.health/docs.md.
Skill source: https://docs.omi.health/skills/omi-api/SKILL.md.
Package version and hashes: https://docs.omi.health/skills/omi-api.json.