omni-inference

Overview

The core OpenAI-compatible inference endpoints: chat completions, embeddings, images, audio (TTS/STT), moderations, rerank, and the Responses API. The primary integration surface for AI agents.

Authentication

All requests require a valid Bearer token or session cookie. Obtain a token via

POST /api/auth/login

or configure

REQUIRE_API_KEY=false

for local development.

Endpoints

```
POST /api/v1/session-leases
```
```
GET /api/v1/search
```
```
POST /api/v1/search
```
```
POST /api/v1/chat/completions
```
```
GET /api/v1/ws
```

POST /api/v1/providers/{provider}/chat/completions

```
POST /api/v1/api/chat
```
```
POST /api/v1/messages
```
```
POST /api/v1/messages/count_tokens
```
```
POST /api/v1/responses
```
```
POST /api/v1/embeddings
```
```
GET /api/v1/multimodal-embeddings
```
```
POST /api/v1/multimodal-embeddings
```

POST /api/v1/providers/{provider}/embeddings

```
POST /api/v1/images/generations
```

POST /api/v1/providers/{provider}/images/generations

```
POST /api/v1/audio/speech
```
```
POST /api/v1/audio/transcriptions
```
```
POST /api/v1/moderations
```
```
POST /api/v1/rerank
```
```
GET /api/v1
```
```
GET /api/v1/providers/{provider}/models
```

GET /api/v1/management/proxy-subscriptions

POST /api/v1/management/proxy-subscriptions

GET /api/v1/management/proxy-subscriptions/{id}

PATCH /api/v1/management/proxy-subscriptions/{id}

DELETE /api/v1/management/proxy-subscriptions/{id}

GET /api/v1/management/proxy-subscriptions/{id}/nodes

POST /api/v1/management/proxy-subscriptions/{id}/refresh

```
POST /api/v1/ocr
```
```
POST /api/v1/audio/translations
```
```
GET /api/v1/voices
```
```
POST /api/v1/speech-to-text
```
```
POST /api/v1/text-to-speech/{voiceId}
```
```
GET /api/v1/explain/routing
```
```
GET /api/v1/providers/suggested-models
```
```
GET /api/v1/provider-plugin-manifest
```
```
GET /api/v1/{omnirouteCatchAll}
```
```
POST /api/v1/{omnirouteCatchAll}
```
```
PUT /api/v1/{omnirouteCatchAll}
```
```
PATCH /api/v1/{omnirouteCatchAll}
```
```
DELETE /api/v1/{omnirouteCatchAll}
```
```
GET /api/v1/accounts/{id}/limits
```
```
PUT /api/v1/accounts/{id}/limits
```
```
GET /api/v1/agents/credentials
```
```
POST /api/v1/agents/credentials
```
```
GET /api/v1/agents/health
```
```
GET /api/v1/agents/tasks
```
```
POST /api/v1/agents/tasks
```
```
DELETE /api/v1/agents/tasks
```
```
GET /api/v1/agents/tasks/{id}
```
```
POST /api/v1/agents/tasks/{id}
```
```
DELETE /api/v1/agents/tasks/{id}
```
```
POST /api/v1/antigravity
```

GET /api/v1/auto-combo/{channel}/candidates

```
GET /api/v1/batches
```
```
POST /api/v1/batches
```
```
GET /api/v1/batches/{id}
```
```
DELETE /api/v1/batches/{id}
```
```
POST /api/v1/batches/{id}/cancel
```
```
DELETE /api/v1/batches/delete-completed
```
```
POST /api/v1/classify
```
```
GET /api/v1/combos
```
```
POST /api/v1/completions
```
```
GET /api/v1/files
```
```
POST /api/v1/files
```
```
GET /api/v1/files/{id}
```
```
DELETE /api/v1/files/{id}
```
```
GET /api/v1/files/{id}/content
```
```
POST /api/v1/images/edits
```
```
GET /api/v1/images/upscale
```
```
POST /api/v1/images/upscale
```
```
GET /api/v1/media/{id}
```
```
POST /api/v1/issues/report
```
```
GET /api/v1/management/proxies
```
```
POST /api/v1/management/proxies
```
```
PATCH /api/v1/management/proxies
```
```
DELETE /api/v1/management/proxies
```

GET /api/v1/management/proxies/assignments

PUT /api/v1/management/proxies/assignments

PUT /api/v1/management/proxies/bulk-assign

```
GET /api/v1/management/proxies/health
```
```
GET /api/v1/me/status
```
```
GET /api/v1/muse-code/models
```
```
GET /api/v1/music/generations
```
```
POST /api/v1/music/generations
```
```
GET /api/v1/providers/{provider}/limits
```
```
PUT /api/v1/providers/{provider}/limits
```
```
GET /api/v1/quotas/check
```
```
GET /api/v1/registered-keys
```
```
POST /api/v1/registered-keys
```
```
GET /api/v1/registered-keys/{id}
```
```
DELETE /api/v1/registered-keys/{id}
```

POST /api/v1/registered-keys/{id}/revoke

```
POST /api/v1/relay/chat/completions
```

POST /api/v1/relay/chat/completions/bifrost

```
POST /api/v1/responses/{path}
```
```
GET /api/v1/search/analytics
```
```
POST /api/v1/segment
```
```
GET /api/v1/video-bridge/drilldown
```
```
DELETE /api/v1/video-bridge/drilldown
```
```
GET /api/v1/videos/generations
```
```
POST /api/v1/videos/generations
```
```
GET /api/v1/vscode/{token}
```
```
POST /api/v1/vscode/{token}/api/chat
```
```
POST /api/v1/vscode/{token}/api/show
```
```
GET /api/v1/vscode/{token}/api/tags
```
```
GET /api/v1/vscode/{token}/api/version
```

POST /api/v1/vscode/{token}/chat/completions

```
GET /api/v1/vscode/{token}/combos
```
```
GET /api/v1/vscode/{token}/models
```
```
POST /api/v1/vscode/{token}/responses
```

POST /api/v1/vscode/{token}/v1/chat/completions

```
GET /api/v1/vscode/{token}/v1/models
```

GET /api/v1/vscode/combos/{token}/{{slug}}

POST /api/v1/vscode/combos/{token}/{{slug}}

```
GET /api/v1/vscode/raw/{token}
```

POST /api/v1/vscode/raw/{token}/api/chat

POST /api/v1/vscode/raw/{token}/api/show

```
GET /api/v1/vscode/raw/{token}/api/tags
```

GET /api/v1/vscode/raw/{token}/api/version

POST /api/v1/vscode/raw/{token}/chat/completions

```
GET /api/v1/vscode/raw/{token}/combos
```
```
GET /api/v1/vscode/raw/{token}/models
```

POST /api/v1/vscode/raw/{token}/responses

POST /api/v1/vscode/raw/{token}/v1/chat/completions

GET /api/v1/vscode/raw/{token}/v1/models

```
POST /api/v1/web/fetch
```

Payloads

See the full OpenAPI specification at

GET /api/openapi/spec

docs/openapi.yaml

for detailed request/response schemas.

Chat completions

Requires

OMNIROUTE_URL

and

OMNIROUTE_KEY

. See entry-point SKILL for setup.

Endpoints

```
POST $OMNIROUTE_URL/v1/chat/completions
```
— OpenAI format
```
POST $OMNIROUTE_URL/v1/messages
```
— Anthropic Messages format
```
POST $OMNIROUTE_URL/v1/responses
```
— OpenAI Responses API

Discover

bash

curl $OMNIROUTE_URL/v1/models | jq '.data[].id'

Combos (e.g.

auto

cost-optimized

subscription

) auto-fallback through multiple providers.

OpenAI format example

bash

curl -X POST $OMNIROUTE_URL/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [{"role": "user", "content": "Refactor this function"}],
    "stream": true
  }'

Anthropic format example

bash

curl -X POST $OMNIROUTE_URL/v1/messages \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "Hi"}]
  }'

Tool use

Supports OpenAI

tools

array and Anthropic

tools

block. Tool results auto-compressed via RTK (47 filters: git-diff, grep, test-jest, terraform-plan, docker-logs, etc.) — 20-40% token savings. Disable per-request with

X-Omniroute-Rtk: off

header.

Reasoning / thinking

Anthropic extended thinking and OpenAI Responses reasoning blocks are forwarded verbatim. Cached automatically via reasoning cache.

Errors

```
401
```
→ invalid API key
```
400 invalid_model
```
→ model not in registry; check
```
/v1/models
```
```
503 circuit_open
```
→ provider circuit breaker tripped; retry later or use combo
```
429 rate_limited
```
→ honor
```
Retry-After
```
; consider using a combo for auto-fallback

Image generation

Requires

OMNIROUTE_URL

and

OMNIROUTE_KEY

. See entry-point SKILL for setup.

Endpoints

POST $OMNIROUTE_URL/v1/images/generations

— Text-to-image

```
POST $OMNIROUTE_URL/v1/images/edits
```
— Image edit (mask)

POST $OMNIROUTE_URL/v1/images/variations

— Variations

Discover

bash

curl $OMNIROUTE_URL/v1/models/image | jq '.data[]'

Returns

{ id, owned_by, sizes:[...], capabilities:[...] }

per model.

Generate example

bash

curl -X POST $OMNIROUTE_URL/v1/images/generations \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "a red bicycle on a wet street, photoreal",
    "n": 1,
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

Response:

{ created, data: [{ url? or b64_json, revised_prompt }] }

Errors

```
400 invalid_size
```
→ not supported by this model; check
```
/v1/models/image
```
```
400 content_policy_violation
```
→ blocked by provider safety
```
503
```
→ provider unavailable; try another model in
```
/v1/models/image
```

Text-to-speech

Requires

OMNIROUTE_URL

and

OMNIROUTE_KEY

. See entry-point SKILL for setup.

Endpoint

```
POST $OMNIROUTE_URL/v1/audio/speech
```
— returns binary audio (mp3/opus/wav/flac)

Discover

bash

curl $OMNIROUTE_URL/v1/models/tts | jq '.data[]'

Each entry includes

voices:[...]

for the available voice names per provider.

Example

bash

curl -X POST $OMNIROUTE_URL/v1/audio/speech \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello from OmniRoute.",
    "voice": "alloy",
    "response_format": "mp3"
  }' --output speech.mp3

Voices

Voice names vary by provider. Check

/v1/models/tts

— each entry has

voices:[...]

. Common OpenAI voices:

alloy

echo

fable

onyx

nova

shimmer

Errors

```
400 invalid_voice
```
→ voice not supported by this model
```
400 input_too_long
```
→ input exceeds model character limit
```
503
```
→ provider unavailable; try another model in
```
/v1/models/tts
```

Speech-to-text

Requires

OMNIROUTE_URL

and

OMNIROUTE_KEY

. See entry-point SKILL for setup.

Endpoints

POST $OMNIROUTE_URL/v1/audio/transcriptions

— multipart upload, returns text

POST $OMNIROUTE_URL/v1/audio/translations

— transcribe + translate to English

Discover

bash

curl $OMNIROUTE_URL/v1/models/stt | jq '.data[]'

Example

bash

curl -X POST $OMNIROUTE_URL/v1/audio/transcriptions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -F "file=@audio.mp3" \
  -F "model=whisper-1" \
  -F "response_format=verbose_json"

Response:

{ text, language, duration, segments?:[{ start, end, text }] }

Supported formats

Audio:

mp3

mp4

mpeg

mpga

m4a

wav

webm

. Response formats:

json

text

srt

verbose_json

vtt

Errors

```
400 invalid_file_format
```
→ unsupported audio format
```
400 file_too_large
```
→ exceeds provider limit (usually 25MB)
```
503
```
→ provider unavailable; try another model in
```
/v1/models/stt
```

Embeddings

Requires

OMNIROUTE_URL

and

OMNIROUTE_KEY

. See entry-point SKILL for setup.

Endpoint

```
POST $OMNIROUTE_URL/v1/embeddings
```

Discover

bash

curl $OMNIROUTE_URL/v1/models/embedding | jq '.data[]'

Each entry:

{ id, owned_by, dimensions, max_input_tokens }

Example

bash

curl -X POST $OMNIROUTE_URL/v1/embeddings \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-large",
    "input": ["first text", "second text"],
    "encoding_format": "float"
  }'

Response:

{ data:[{ embedding:[...], index }], usage:{ prompt_tokens, total_tokens } }

Batch input

input

accepts a string or array of strings (up to provider batch limit, typically 2048 items).

Errors

```
400 input_too_long
```
→ input exceeds
```
max_input_tokens
```
for this model
```
400 invalid_encoding_format
```
→ use
```
float
```
or
```
base64
```
```
503
```
→ provider unavailable; try another model in
```
/v1/models/embedding
```

Web search

Requires

OMNIROUTE_URL

and

OMNIROUTE_KEY

. See entry-point SKILL for setup.

Endpoint

```
POST $OMNIROUTE_URL/v1/web/search
```
— unified search format

Discover

bash

curl $OMNIROUTE_URL/v1/models/web | jq '.data[] | select(.kind == "webSearch")'

Example

bash

curl -X POST $OMNIROUTE_URL/v1/web/search \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tavily/search",
    "query": "OmniRoute github latest release",
    "max_results": 5,
    "include_answer": true
  }'

Response:

{ answer?, results:[{ url, title, content, score }] }

Parameters

Field	Type	Description
`model`	string	Provider model from `/v1/models/web`
`query`	string	Search query
`max_results`	number	Max results (default: 5)
`include_answer`	boolean	Include AI-synthesized answer
`search_depth`	string	`basic` or `advanced` (Tavily)

Errors

```
400 query_too_long
```
→ shorten the search query
```
503
```
→ provider unavailable; try another model in
```
/v1/models/web
```

Web fetch

Requires

OMNIROUTE_URL

and

OMNIROUTE_KEY

. See entry-point SKILL for setup.

Endpoint

```
POST $OMNIROUTE_URL/v1/web/fetch
```

Discover

bash

curl $OMNIROUTE_URL/v1/models/web | jq '.data[] | select(.kind == "webFetch")'

Example

bash

curl -X POST $OMNIROUTE_URL/v1/web/fetch \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina/reader",
    "url": "https://anthropic.com",
    "format": "markdown"
  }'

Response:

{ url, title, markdown, links?:[...], images?:[...] }

Parameters

Field	Type	Description
`model`	string	Provider from `/v1/models/web` (e.g. `jina/reader` , `firecrawl/scrape` )
`url`	string	URL to fetch
`format`	string	`markdown` (default), `html` , `text`

Errors

```
400 invalid_url
```
→ URL must be http/https
```
403 blocked
```
→ provider blocked by target site; try a different model
```
503
```
→ provider unavailable; try another model in
```
/v1/models/web
```

omni-inference

NPX Install

Tags

SKILL.md Content

Overview

Authentication

Endpoints

Payloads

Chat completions

Endpoints

Discover

OpenAI format example

Anthropic format example

Tool use

Reasoning / thinking

Errors

Image generation

Endpoints

Discover

Generate example

Errors

Text-to-speech

Endpoint

Discover

Example

Voices

Errors

Speech-to-text

Endpoints

Discover

Example

Supported formats

Errors

Embeddings

Endpoint

Discover

Example

Batch input

Errors

Web search

Endpoint

Discover

Example

Parameters

Errors

Web fetch

Endpoint

Discover

Example

Parameters

Errors