# Chat And Inference Endpoints

## Endpoint Summary

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/models` | List aggregated models |
| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completions |
| `POST` | `/realtime` | Text-only voice-adapter brain: transcript text in, short reply text out |
| `POST` | `/v1/realtime` | Auth-scoped alias for `/realtime` |
| `POST` | `/v1/embeddings` | Generate embeddings |
| `POST` | `/v1/chat` | Stateful Omnius chat with optional full agent tools |
| `POST` | `/v1/generate` | Ollama-compatible one-shot generation |
| `POST` | `/api/generate` | Ollama-compatible alias |
| `GET` | `/v1/chat/sessions` | List active chat sessions |
| `POST` | `/v1/chat/check-in` | Send a steering check-in to the active chat session |

## `/v1/models`

Returns an OpenAI-style model list aggregated from enabled endpoints. Model discovery should include local Ollama, configured external endpoints, sponsor endpoints, and COHERE/passthrough models where enabled.

## `/v1/chat/completions`

This is the OpenAI-compatible endpoint. It forwards standard chat-completion fields and adds Omnius controls.

Important body fields:

| Field | Type | Purpose |
| --- | --- | --- |
| `model` | string | Backend model name |
| `messages` | array | OpenAI-style messages |
| `stream` | boolean | SSE streaming when supported |
| `realtime` | boolean | Enable Omnius realtime conversation mode |
| `realtime_options` | object | Realtime history and max-token defaults |
| `tools` | array | OpenAI-shape tools array |
| `tool_choice` | any | OpenAI-shape tool choice |
| `parallel_tool_calls` | boolean | Forwarded to backend |
| `timeout_s` | number | Per-request timeout |
| `agent_loop` | boolean | Run server-side tool loop |
| `include_daemon_tools` | array | Merge daemon tools by scope: `read`, `run`, `admin` |
| `max_turns` | integer | Server-side agent loop turn cap |
| `prompt_template` | string | Optional template such as `factual-first` |

Realtime example:

```json
{
  "model": "qwen3:4b",
  "realtime": true,
  "realtime_options": {
    "max_history_messages": 12,
    "max_tokens": 160
  },
  "messages": [
    { "role": "user", "content": "Make that shorter for voice." }
  ]
}
```

## `/v1/chat`

This is the Omnius stateful chat endpoint. By default it runs the full Omnius agent stack with tools, memory, skills, and multi-agent context. Set `tools: false` to use the fast direct backend path. `realtime: true` also uses the direct backend path.

Body fields:

| Field | Type | Purpose |
| --- | --- | --- |
| `message` | string | User message |
| `model` | string | Optional model override |
| `session_id` | string | Reuse or name a session |
| `stream` | boolean | Stream when supported |
| `tools` | boolean | Full agent stack by default |
| `realtime` | boolean | Short ASR/TTS conversation mode |
| `realtime_options` | object | Realtime settings |

## `/v1/generate` And `/api/generate`

These endpoints provide one-shot Ollama-compatible generation. They are useful for clients that speak Ollama's generate shape rather than OpenAI chat messages. The route has no session history and can still use Omnius' backend routing layer.

Common body fields:

| Field | Type | Purpose |
| --- | --- | --- |
| `model` | string | Optional model override |
| `prompt` | string | Prompt text |
| `stream` | boolean | Stream when supported |

## Realtime Behavior

When `realtime: true`, Omnius:

- Builds a compact system prompt from `SOUL.md` or `.aiwg/SOUL.md`.
- Reads a compact voice profile from `.aiwg/voices/` when present.
- Keeps only recent non-system history.
- Preserves caller system messages under the realtime contract.
- Defaults to short response settings.
- Removes Omnius-only realtime fields before backend proxying.

Use this for live voice clients, not long coding tasks.

For ASR/TTS systems that only need the text brain, use `/realtime` or `/v1/realtime` with `message`, `text`, `recent_turn`, `asr_text`, or `callerText`. Optional `soul_md` supplies adapter-local SOUL.md content. Set `Accept: text/plain` or `format: "text"` to receive only the reply string.

## Server-Side Agent Loop

`/v1/chat/completions` can run an internal tool loop when `agent_loop: true`. This lets clients collapse multiple model/tool round trips into one daemon request. Daemon tool calls execute inline; client-owned tool calls can still be yielded in OpenAI-compatible shape.
