local-lemonade 1.0.0

package/docs/openai.md

@@ -0,0 +1,1192 @@
+# OpenAI-Compatible API
+
+This spec defines Lemonade's implementation of the [OpenAI API](https://developers.openai.com/api/docs).
+
+| Method | Endpoint | Description | Modality |
+|--------|----------|-------------|----------|
+| `POST` | [`/v1/chat/completions`](#post-v1chatcompletions) | Chat Completions | messages -> completion |
+| `POST` | [`/v1/completions`](#post-v1completions) | Text Completions | prompt -> completion |
+| `POST` | [`/v1/embeddings`](#post-v1embeddings) | Embeddings | text -> vector representations |
+| `POST` | [`/v1/responses`](#post-v1responses) | Responses API | prompt/messages -> event |
+| `POST` | [`/v1/audio/transcriptions`](#post-v1audiotranscriptions) | Audio Transcription | audio file -> text |
+| `POST` | [`/v1/audio/speech`](#post-v1audiospeech) | Text to speech | text -> audio |
+| `WS` | [`/realtime`](#ws-realtime) | Realtime Audio Transcription, OpenAI SDK compatible | streaming audio -> text |
+| `POST` | [`/v1/images/generations`](#post-v1imagesgenerations) | Image Generation | prompt -> image |
+| `POST` | [`/v1/images/edits`](#post-v1imagesedits) | Image Editing | image + prompt -> edited image |
+| `POST` | [`/v1/images/variations`](#post-v1imagesvariations) | Image Variations | image -> varied image |
+| `POST` | [`/v1/images/upscale`](#post-v1imagesupscale) | Image Upscaling | image + ESRGAN model -> upscaled image |
+| `GET` | [`/v1/models`](#get-v1models) | List models available locally | n/a |
+| `GET` | [`/v1/models/{model_id}`](#get-v1modelsmodel_id) | Retrieve a specific model by ID | n/a |
+
+## `POST /v1/chat/completions`
+<sub>![Status](https://img.shields.io/badge/status-partially_available-green)</sub>
+
+Chat Completions API. You provide a list of messages and receive a completion. This API will also load the model if it is not already loaded.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `messages` | Yes | Array of messages in the conversation. Each message should have a `role` ("user" or "assistant") and `content` (the message text). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `model` | Yes | The model to use for the completion. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `stream` | No | If true, tokens will be sent as they are generated. If false, the response will be sent as a single message once complete. Defaults to false. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `stop` | No | Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence. Can be a string or an array of strings. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `logprobs` | No | Include log probabilities of the output tokens. If true, returns the log probability of each output token. Defaults to false. | <sub>![Status](https://img.shields.io/badge/not_available-red)</sub> |
+| `temperature` | No | What sampling temperature to use. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `repeat_penalty` | No | Number between 1.0 and 2.0. 1.0 means no penalty. Higher values discourage repetition. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `top_k` | No | Integer that controls the number of top tokens to consider during sampling. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `top_p` | No | Float between 0.0 and 1.0 that controls the cumulative probability of top tokens to consider during nucleus sampling. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `tools`       | No | A list of tools the model may call. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `max_tokens` | No | An upper bound for the number of tokens that can be generated for a completion. Mutually exclusive with `max_completion_tokens`. This value is now deprecated by OpenAI in favor of `max_completion_tokens` | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `max_completion_tokens` | No | An upper bound for the number of tokens that can be generated for a completion. Mutually exclusive with `max_tokens`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/chat/completions" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{
+        "model": "Qwen3-0.6B-GGUF",
+        "messages": [
+          {
+            "role": "user",
+            "content": "What is the population of Paris?"
+          }
+        ],
+        "stream": false
+      }'
+    ```
+=== "Bash"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/chat/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "Qwen3-0.6B-GGUF",
+            "messages": [
+              {"role": "user", "content": "What is the population of Paris?"}
+            ],
+            "stream": false
+          }'
+    ```
+
+### Response format
+
+=== "Non-streaming responses"
+
+    ```json
+    {
+      "id": "0",
+      "object": "chat.completion",
+      "created": 1742927481,
+      "model": "Qwen3-0.6B-GGUF",
+      "choices": [{
+        "index": 0,
+        "message": {
+          "role": "assistant",
+          "content": "Paris has a population of approximately 2.2 million people in the city proper."
+        },
+        "finish_reason": "stop"
+      }]
+    }
+    ```
+=== "Streaming responses"
+    For streaming responses, the API returns a stream of server-sent events (however, Open AI recommends using their streaming libraries for parsing streaming responses):
+
+    ```json
+    {
+      "id": "0",
+      "object": "chat.completion.chunk",
+      "created": 1742927481,
+      "model": "Qwen3-0.6B-GGUF",
+      "choices": [{
+        "index": 0,
+        "delta": {
+          "role": "assistant",
+          "content": "Paris"
+        }
+      }]
+    }
+    ```
+
+### Image understanding input format (OpenAI-compatible)
+
+To send images to `chat/completions`, pass a `messages[*].content` array that mixes `text` and `image_url` items. The image can be provided as a base64 data URL (for example, from `FileReader.readAsDataURL(...)` in web apps).
+
+#### Example request
+
+```bash
+curl -X POST http://localhost:13305/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+        "model": "Qwen2.5-VL-7B-Instruct",
+        "messages": [
+          {
+            "role": "user",
+            "content": [
+              {"type": "text", "text": "What is in this image?"},
+              {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."}}
+            ]
+          }
+        ],
+        "stream": false
+      }'
+```
+
+#### Example response
+
+```json
+{
+  "id": "0",
+  "object": "chat.completion",
+  "created": 1742927481,
+  "model": "Qwen2.5-VL-7B-Instruct",
+  "choices": [{
+    "index": 0,
+    "message": {
+      "role": "assistant",
+      "content": "The image shows a red apple resting on a wooden table."
+    },
+    "finish_reason": "stop"
+  }]
+}
+```
+
+### Server-side tools
+
+> **Note:** Omni collection orchestration is a Lemonade-specific extension to the Chat Completions API; it is not part of the OpenAI specification. Requests that target ordinary (non-collection) models are unaffected and are fully OpenAI-compatible.
+
+When `model` names an Omni **collection** model (`recipe: "collection.omni"`, e.g., `LMX-Omni-52B-Halo`), this endpoint runs an internal tool-calling loop instead of a plain completion. The server injects the reference system prompt and tools, routes to the collection's chat component, executes the omni tools (image generation/editing, text-to-speech) against the matching components, and returns one OpenAI-compatible response. Generated media is embedded in the assistant `content`:
+
+- **images** → markdown `![generated image](data:image/png;base64,…)`
+- **speech** → `<audio>data:audio/mpeg;base64,…</audio>`
+
+Both non-streaming and `stream: true` are supported. In streaming mode the media arrives as a content delta on a `chat.completion.chunk` frame the moment its tool finishes.
+
+**Merge semantics.** A client-provided system prompt is prepended by the built-in omni system prompt. Client-provided `tools` are merged with the built-in omni tools. The server resolves omni tool calls internally; calls to client-provided tools are returned in a `finish_reason: "tool_calls"` response for the client to execute and resume. Targeting a collection name invokes the server-side loop; targeting a component LLM name bypasses it and returns a plain completion. See [Lemonade Omni Models](../dev/lemonade-omni.md) for details.
+
+#### Example request
+
+```bash
+curl -X POST http://localhost:13305/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+        "model": "LMX-Omni-52B-Halo",
+        "messages": [{"role": "user", "content": "Draw a red apple on a table."}],
+        "stream": false
+      }'
+```
+
+#### Example response
+
+The image tool runs during the loop and its output is embedded as a markdown image in the assistant `content`:
+
+```json
+{
+  "id": "0",
+  "object": "chat.completion",
+  "created": 1742927481,
+  "model": "LMX-Omni-52B-Halo",
+  "choices": [{
+    "index": 0,
+    "message": {
+      "role": "assistant",
+      "content": "Here is a red apple on a table.\n\n![generated image](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...)"
+    },
+    "finish_reason": "stop"
+  }]
+}
+```
+
+
+## `POST /v1/completions`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Text Completions API. You provide a prompt and receive a completion. This API will also load the model if it is not already loaded.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `prompt` | Yes | The prompt to use for the completion.  | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `model` | Yes | The model to use for the completion.  | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `stream` | No | If true, tokens will be sent as they are generated. If false, the response will be sent as a single message once complete. Defaults to false. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `stop` | No | Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence. Can be a string or an array of strings. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `echo` | No | Echo back the prompt in addition to the completion. Available on non-streaming mode. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `logprobs` | No | Include log probabilities of the output tokens. If true, returns the log probability of each output token. Defaults to false. Only available when `stream=False`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `temperature` | No | What sampling temperature to use. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `repeat_penalty` | No | Number between 1.0 and 2.0. 1.0 means no penalty. Higher values discourage repetition. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `top_k` | No | Integer that controls the number of top tokens to consider during sampling. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `top_p` | No | Float between 0.0 and 1.0 that controls the cumulative probability of top tokens to consider during nucleus sampling. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `max_tokens` | No | An upper bound for the number of tokens that can be generated for a completion, including input tokens. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest -Uri "http://localhost:13305/v1/completions" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{
+        "model": "Qwen3-0.6B-GGUF",
+        "prompt": "What is the population of Paris?",
+        "stream": false
+      }'
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "Qwen3-0.6B-GGUF",
+            "prompt": "What is the population of Paris?",
+            "stream": false
+          }'
+    ```
+
+### Response format
+
+The following format is used for both streaming and non-streaming responses:
+
+```json
+{
+  "id": "0",
+  "object": "text_completion",
+  "created": 1742927481,
+  "model": "Qwen3-0.6B-GGUF",
+  "choices": [{
+    "index": 0,
+    "text": "Paris has a population of approximately 2.2 million people in the city proper.",
+    "finish_reason": "stop"
+  }],
+}
+```
+
+
+
+## `POST /v1/embeddings`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Embeddings API. You provide input text and receive vector representations (embeddings) that can be used for semantic search, clustering, and similarity comparisons. This API will also load the model if it is not already loaded.
+
+> **Note:** This endpoint is only available for models using the `llamacpp` or `flm` recipes. ONNX models (OGA recipes) do not support embeddings.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `input` | Yes | The input text or array of texts to embed. Can be a string or an array of strings. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `model` | Yes | The model to use for generating embeddings. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `encoding_format` | No | The format to return embeddings in. Supported values: `"float"` (default), `"base64"`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/embeddings" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{
+        "model": "nomic-embed-text-v1-GGUF",
+        "input": ["Hello, world!", "How are you?"],
+        "encoding_format": "float"
+      }'
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/embeddings \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "nomic-embed-text-v1-GGUF",
+            "input": ["Hello, world!", "How are you?"],
+            "encoding_format": "float"
+          }'
+    ```
+
+### Response format
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "object": "embedding",
+      "index": 0,
+      "embedding": [0.0234, -0.0567, 0.0891, ...]
+    },
+    {
+      "object": "embedding",
+      "index": 1,
+      "embedding": [0.0456, -0.0678, 0.1234, ...]
+    }
+  ],
+  "model": "nomic-embed-text-v1-GGUF",
+  "usage": {
+    "prompt_tokens": 12,
+    "total_tokens": 12
+  }
+}
+```
+
+**Field Descriptions:**
+
+- `object` - Type of response object, always `"list"`
+- `data` - Array of embedding objects
+  - `object` - Type of embedding object, always `"embedding"`
+  - `index` - Index position of the input text in the request
+  - `embedding` - Vector representation as an array of floats
+- `model` - Model identifier used to generate the embeddings
+- `usage` - Token usage statistics
+  - `prompt_tokens` - Number of tokens in the input
+  - `total_tokens` - Total tokens processed
+
+## `POST /v1/responses`
+<sub>![Status](https://img.shields.io/badge/status-partially_available-green)</sub>
+
+Responses API. You provide an input and receive a response. This API will also load the model if it is not already loaded.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `input` | Yes | A list of dictionaries or a string input for the model to respond to. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `model` | Yes | The model to use for the response. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `max_output_tokens` | No | The maximum number of output tokens to generate. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `temperature` | No | What sampling temperature to use. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `repeat_penalty` | No | Number between 1.0 and 2.0. 1.0 means no penalty. Higher values discourage repetition. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `top_k` | No | Integer that controls the number of top tokens to consider during sampling. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `top_p` | No | Float between 0.0 and 1.0 that controls the cumulative probability of top tokens to consider during nucleus sampling. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `stream` | No | If true, tokens will be sent as they are generated. If false, the response will be sent as a single message once complete. Defaults to false. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+
+### Streaming Events
+
+The Responses API uses semantic events for streaming. Each event is typed with a predefined schema, so you can listen for events you care about. Our initial implementation only offers support to:
+
+- `response.created`
+- `response.output_text.delta`
+- `response.completed`
+
+For a full list of event types, see the [API reference for streaming](https://platform.openai.com/docs/api-reference/responses-streaming).
+
+### Example request
+
+=== "PowerShell"
+
+    ```powershell
+    Invoke-WebRequest -Uri "http://localhost:13305/v1/responses" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{
+        "model": "Llama-3.2-1B-Instruct-Hybrid",
+        "input": "What is the population of Paris?",
+        "stream": false
+      }'
+    ```
+
+=== "Bash"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/responses \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "Llama-3.2-1B-Instruct-Hybrid",
+            "input": "What is the population of Paris?",
+            "stream": false
+          }'
+    ```
+
+
+### Response format
+
+=== "Non-streaming responses"
+
+    ```json
+    {
+      "id": "0",
+      "created_at": 1746225832.0,
+      "model": "Llama-3.2-1B-Instruct-Hybrid",
+      "object": "response",
+      "output": [{
+        "id": "0",
+        "content": [{
+          "annotations": [],
+          "text": "Paris has a population of approximately 2.2 million people in the city proper."
+        }]
+      }]
+    }
+    ```
+
+=== "Streaming Responses"
+    For streaming responses, the API returns a series of events. Refer to [OpenAI streaming guide](https://platform.openai.com/docs/guides/streaming-responses?api-mode=responses) for details.
+
+
+
+## `POST /v1/audio/transcriptions`
+<sub>![Status](https://img.shields.io/badge/status-partial-yellow)</sub>
+
+Audio Transcription API. You provide an audio file and receive a text transcription. This API will also load the model if it is not already loaded.
+
+> **Note:** This endpoint uses [whisper.cpp](https://github.com/ggerganov/whisper.cpp) as the backend. Whisper models are automatically downloaded when first used.
+>
+> **Limitations:** Only `wav` audio input is currently supported. The `response_format` field supports `json`, `verbose_json`, `text`, `srt`, and `vtt`. On the FastFlowLM (FLM) backend, `srt` and `vtt` are rejected with a `400` because FLM returns no segment timestamps, and `verbose_json` returns the compact shape without a `segments` field.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `file` | Yes | The audio file to transcribe. Supported formats: wav. | <sub>![Status](https://img.shields.io/badge/partial-yellow)</sub> |
+| `model` | Yes | The Whisper model to use for transcription (e.g., `Whisper-Tiny`, `Whisper-Base`, `Whisper-Small`). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `language` | No | The language of the audio (ISO 639-1 code, e.g., `en`, `es`, `fr`). Defaults to `auto`, which tells whisper.cpp to detect the source language instead of using whisper-server's English default. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `response_format` | No | The response format. Supported values: `json`, `verbose_json`, `text`, `srt`, `vtt`. `srt` and `vtt` require a backend that reports segment timestamps (whisper.cpp). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+=== "Windows"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/audio/transcriptions ^
+      -F "file=@C:\path\to\audio.wav" ^
+      -F "model=Whisper-Tiny"
+    ```
+
+=== "Linux"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/audio/transcriptions \
+      -F "file=@/path/to/audio.wav" \
+      -F "model=Whisper-Tiny"
+    ```
+
+### Response format
+
+```json
+{
+  "text": "Hello, this is a sample transcription of the audio file."
+}
+```
+
+**Field Descriptions:**
+
+- `text` - The transcribed text from the audio file
+
+
+
+## `WS /realtime`
+<sub>![Status](https://img.shields.io/badge/status-partial-yellow)</sub>
+
+Realtime Audio Transcription API via WebSocket (OpenAI SDK compatible). Stream audio from a microphone and receive transcriptions in real-time with Voice Activity Detection (VAD).
+
+> **Limitations:** Only 16kHz mono PCM16 audio format is supported. Uses the same Whisper models as the HTTP transcription endpoint.
+
+### Connection
+
+WebSocket upgrades are accepted **directly on the main HTTP port** (default 13305) — the same port as all REST endpoints. Connect with the model name:
+
+```
+ws://localhost:13305/v1/realtime?model=Whisper-Tiny
+```
+
+Accepted paths are `/realtime` and `/logs/stream`, bare or under any of the standard prefixes (`/v1`, `/v0`, `/api/v1`, `/api/v0`), so OpenAI Realtime SDK clients (`/v1/realtime`) connect as-is. When `LEMONADE_API_KEY` is set, pass `?api_key=KEY` as a query parameter.
+
+A dedicated WebSocket port also remains for backward compatibility; it is OS-assigned and reported by the [`/v1/health`](./lemonade.md#get-v1health) endpoint (`websocket_port` field). New clients should prefer the main port:
+
+```
+ws://localhost:<websocket_port>/realtime?model=Whisper-Tiny
+```
+
+Upon connection, the server sends a `session.created` message with a session ID.
+
+### Client → Server Messages
+
+| Message Type | Description |
+|--------------|-------------|
+| `session.update` | Configure the session (set model, VAD settings, or disable turn detection) |
+| `input_audio_buffer.append` | Send audio data (base64-encoded PCM16) |
+| `input_audio_buffer.commit` | Force transcription of buffered audio |
+| `input_audio_buffer.clear` | Clear audio buffer without transcribing |
+
+### Server → Client Messages
+
+| Message Type | Description |
+|--------------|-------------|
+| `session.created` | Session established, contains session ID |
+| `session.updated` | Session configuration updated |
+| `input_audio_buffer.speech_started` | VAD detected speech start |
+| `input_audio_buffer.speech_stopped` | VAD detected speech end, transcription triggered |
+| `input_audio_buffer.committed` | Audio buffer committed for transcription |
+| `input_audio_buffer.cleared` | Audio buffer cleared |
+| `conversation.item.input_audio_transcription.delta` | Interim/partial transcription (replaceable) |
+| `conversation.item.input_audio_transcription.completed` | Final transcription result |
+| `error` | Error message |
+
+### Example: Configure Session
+
+```json
+{
+  "type": "session.update",
+  "session": {
+    "model": "Whisper-Tiny"
+  }
+}
+```
+
+### Example: Send Audio
+
+```json
+{
+  "type": "input_audio_buffer.append",
+  "audio": "<base64-encoded PCM16 audio>"
+}
+```
+
+Audio should be:
+- 16kHz sample rate
+- Mono (single channel)
+- 16-bit signed integer (PCM16)
+- Base64 encoded
+- Sent in chunks (~85ms recommended)
+
+### Example: Transcription Result
+
+```json
+{
+  "type": "conversation.item.input_audio_transcription.completed",
+  "transcript": "Hello, this is a test transcription."
+}
+```
+
+### VAD Configuration
+
+VAD settings can be configured via `session.update`:
+
+```json
+{
+  "type": "session.update",
+  "session": {
+    "model": "Whisper-Tiny",
+    "turn_detection": {
+      "threshold": 0.01,
+      "silence_duration_ms": 800,
+      "prefix_padding_ms": 250
+    }
+  }
+}
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `threshold` | 0.01 | RMS energy threshold for speech detection |
+| `silence_duration_ms` | 800 | Silence duration to trigger speech end |
+| `prefix_padding_ms` | 250 | Minimum speech duration before triggering |
+
+Set `turn_detection` to `null` to disable server-side VAD and use explicit commits instead:
+
+```json
+{
+  "type": "session.update",
+  "session": {
+    "model": "Whisper-Tiny",
+    "turn_detection": null
+  }
+}
+```
+
+### Code Examples
+
+A complete, runnable example:
+
+- **[`realtime_transcription.py`](https://github.com/lemonade-sdk/lemonade/blob/main/examples/realtime_transcription.py)** - Python CLI for microphone streaming
+
+```bash
+# Stream from microphone
+python examples/realtime_transcription.py --model Whisper-Tiny
+```
+
+### Integration Notes
+
+- **Audio Format**: Server expects 16kHz mono PCM16. Higher sample rates must be downsampled client-side.
+- **Chunk Size**: Send audio in ~85-256ms chunks for optimal latency/efficiency.
+- **VAD Behavior**: Server automatically detects speech boundaries and triggers transcription on speech end.
+- **Manual Commit**: Set `turn_detection` to `null`, then use `input_audio_buffer.commit` to force transcription. In this mode the server buffers audio but does not emit VAD or interim transcription events.
+- **Clear Buffer**: Use `input_audio_buffer.clear` to discard audio without transcribing.
+- **Chunking**: We are still tuning the chunking to balance latency vs. accuracy.
+- **Migrating off the dedicated port**: Clients that discover `websocket_port` via `/v1/health` and connect there can switch to `ws://HOST:13305/v1/realtime?model=...` — the protocol (events, audio format, auth) is identical on both ports, so it is a URL change only. This also simplifies remote setups (one port to expose) and works through reverse proxies that pass `Upgrade: websocket`. Keep the `websocket_port` fallback only if you must support servers older than this release.
+
+
+## `POST /v1/images/generations`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Image Generation API. You provide a text prompt and receive a generated image.
+
+> **Performance:** CPU inference takes ~4-5 minutes per image. GPU (ROCm) is significantly faster.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `prompt` | Yes | The text description of the image to generate. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `model` | Yes | The diffusion model to use (e.g., `SD-Turbo`, `Krea-2-Turbo`). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `size` | No | The size of the generated image. Format: `WIDTHxHEIGHT` (e.g., `512x512`, `256x256`). Default: `512x512`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `n` | No | Number of images to generate. Currently only `1` is supported. | <sub>![Status](https://img.shields.io/badge/partial-yellow)</sub> |
+| `response_format` | No | Format of the response. Only `b64_json` (base64-encoded image) is supported. | <sub>![Status](https://img.shields.io/badge/partial-yellow)</sub> |
+| `steps` | No | Number of inference steps. SD-Turbo works well with 4 steps. Default varies by model. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `cfg_scale` | No | Classifier-free guidance scale. SD-Turbo uses low values (~1.0). Default varies by model. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `seed` | No | Random seed for reproducibility. If not specified, a random seed is used. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+=== "Bash"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/images/generations \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "SD-Turbo",
+            "prompt": "A serene mountain landscape at sunset",
+            "size": "512x512",
+            "steps": 4,
+            "response_format": "b64_json"
+          }'
+    ```
+
+## `POST /v1/images/edits`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Image Editing API. You provide a source image and a text prompt describing the desired change, and receive an edited image.
+
+> **Note:** This endpoint accepts `multipart/form-data` requests (not JSON). Use editing-capable models such as `Flux-2-Klein-4B` or `SD-Turbo`.
+>
+> **Performance:** CPU inference takes several minutes per image. GPU (ROCm) is significantly faster.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `model` | Yes | The diffusion model to use (e.g., `Flux-2-Klein-4B`, `SD-Turbo`). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `image` / `image[]` | Yes | The source image file to edit (PNG). Sent as a file in multipart/form-data. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `prompt` | Yes | A text description of the desired edit. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `mask` | No | An optional mask image (PNG). White areas indicate regions to edit; black areas are preserved. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `size` | No | The size of the output image. Format: `WIDTHxHEIGHT` (e.g., `512x512`). Default: `512x512`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `n` | No | Number of images to generate. Allowed range: `1`–`10`. Default: `1`. Values outside this range are rejected with `400 Bad Request`. | <sub>![Status](https://img.shields.io/badge/partial-yellow)</sub> |
+| `response_format` | No | Format of the response. Only `b64_json` (base64-encoded image) is supported. | <sub>![Status](https://img.shields.io/badge/partial-yellow)</sub> |
+| `steps` | No | Number of inference steps. Default varies by model. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `cfg_scale` | No | Classifier-free guidance scale. Default varies by model. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `seed` | No | Random seed for reproducibility. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `user` | No | OpenAI API compatibility field. Accepted but not forwarded to the backend. | <sub>![Status](https://img.shields.io/badge/not_available-red)</sub> |
+| `background` | No | OpenAI API compatibility field. Accepted but not forwarded to the backend. | <sub>![Status](https://img.shields.io/badge/not_available-red)</sub> |
+| `quality` | No | OpenAI API compatibility field. Accepted but not forwarded to the backend. | <sub>![Status](https://img.shields.io/badge/not_available-red)</sub> |
+| `input_fidelity` | No | OpenAI API compatibility field. Accepted but not forwarded to the backend. | <sub>![Status](https://img.shields.io/badge/not_available-red)</sub> |
+| `output_compression` | No | OpenAI API compatibility field. Accepted; silently ignored by the backend. | <sub>![Status](https://img.shields.io/badge/not_available-red)</sub> |
+
+### Example request
+
+=== "Bash"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/images/edits \
+      -F "model=Flux-2-Klein-4B" \
+      -F "prompt=Add a red barn and mountains in the background, photorealistic" \
+      -F "size=512x512" \
+      -F "n=1" \
+      -F "response_format=b64_json" \
+      -F "image=@/path/to/source_image.png"
+    ```
+
+=== "Python (OpenAI client)"
+
+    ```python
+    from openai import OpenAI
+    client = OpenAI(base_url="http://localhost:13305/api/v1", api_key="not-needed")
+    with open("source_image.png", "rb") as image_file:
+        response = client.images.edit(
+            model="Flux-2-Klein-4B",
+            image=image_file,
+            prompt="Add a red barn and mountains in the background, photorealistic",
+            size="512x512",
+        )
+    import base64
+    image_data = base64.b64decode(response.data[0].b64_json)
+    open("edited_image.png", "wb").write(image_data)
+    ```
+
+---
+
+## `POST /v1/images/variations`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Image Variations API. You provide a source image and receive a variation of it.
+
+> **Note:** This endpoint accepts `multipart/form-data` requests (not JSON). Unlike `/images/edits`, a `prompt` parameter is not supported and will be ignored — the model generates a variation based solely on the input image.
+>
+> **Performance:** CPU inference takes several minutes per image. GPU (ROCm) is significantly faster.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `model` | Yes | The Stable Diffusion model to use (e.g., `Flux-2-Klein-4B`, `SD-Turbo`). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `image` | Yes | The source image file (PNG). Sent as a file in multipart/form-data. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `size` | No | The size of the output image. Format: `WIDTHxHEIGHT` (e.g., `512x512`). Default: `512x512`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `n` | No | Number of variations to generate. Integer between 1 and 10 inclusive. Default: `1`. Values outside this range result in a 400 Bad Request error. | <sub>![Status](https://img.shields.io/badge/partial-yellow)</sub> |
+| `response_format` | No | Format of the response. Only `b64_json` (base64-encoded image) is supported. | <sub>![Status](https://img.shields.io/badge/partial-yellow)</sub> |
+| `user` | No | OpenAI API compatibility field. Accepted but not forwarded to the backend. | <sub>![Status](https://img.shields.io/badge/not_available-red)</sub> |
+
+### Example request
+
+=== "Bash"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/images/variations \
+      -F "model=Flux-2-Klein-4B" \
+      -F "size=512x512" \
+      -F "n=1" \
+      -F "response_format=b64_json" \
+      -F "image=@/path/to/source_image.png"
+    ```
+
+=== "Python (OpenAI client)"
+
+    ```python
+    from openai import OpenAI
+    client = OpenAI(base_url="http://localhost:13305/api/v1", api_key="not-needed")
+    with open("source_image.png", "rb") as image_file:
+        response = client.images.create_variation(
+            model="Flux-2-Klein-4B",
+            image=image_file,
+            size="512x512",
+            n=1,
+        )
+    import base64
+    image_data = base64.b64decode(response.data[0].b64_json)
+    open("variation.png", "wb").write(image_data)
+    ```
+
+---
+
+## `POST /v1/images/upscale`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Image Upscaling API. You provide a base64-encoded image and a Real-ESRGAN model name, and receive an upscaled image. The upscale factor depends on the selected model, and it is usually reflected in its name.
+
+> **Note:** Unlike `/images/edits` and `/images/variations`, this endpoint accepts a JSON body (not multipart/form-data). The image must be provided as a base64-encoded string.
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `image` | Yes | Base64-encoded PNG image to upscale. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `model` | Yes | The ESRGAN model to use (e.g., `RealESRGAN-x4plus`, `Remacri-4x-TheNoise`). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+
+### Example request
+
+A typical workflow is to generate an image first, then upscale it:
+
+=== "Bash"
+
+    ```bash
+    # Step 1: Generate an image and save the base64 response
+    RESPONSE=$(curl -s -X POST http://localhost:13305/v1/images/generations \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "SD-Turbo",
+            "prompt": "A serene mountain landscape at sunset",
+            "size": "512x512",
+            "steps": 4,
+            "response_format": "b64_json"
+          }')
+
+    # Step 2: Build the upscale JSON payload and pipe it to curl via stdin
+    # (base64 images are too large for command-line interpolation)
+    echo "$RESPONSE" | python3 -c "
+    import sys, json
+    b64 = json.load(sys.stdin)['data'][0]['b64_json']
+    print(json.dumps({'image': b64, 'model': 'RealESRGAN-x4plus'}))
+    " | curl -X POST http://localhost:13305/v1/images/upscale \
+      -H "Content-Type: application/json" \
+      -d @-
+    ```
+
+=== "PowerShell"
+
+    ```powershell
+    # Step 1: Generate an image
+    $genResponse = Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/images/generations" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body '{
+        "model": "SD-Turbo",
+        "prompt": "A serene mountain landscape at sunset",
+        "size": "512x512",
+        "steps": 4,
+        "response_format": "b64_json"
+      }'
+
+    # Step 2: Extract the base64 image
+    $imageB64 = ($genResponse.Content | ConvertFrom-Json).data[0].b64_json
+
+    # Step 3: Upscale the image with Real-ESRGAN
+    $body = @{ image = $imageB64; model = "RealESRGAN-x4plus" } | ConvertTo-Json
+    Invoke-WebRequest `
+      -Uri "http://localhost:13305/v1/images/upscale" `
+      -Method POST `
+      -Headers @{ "Content-Type" = "application/json" } `
+      -Body $body
+    ```
+
+=== "Python (requests)"
+
+    ```python
+    import requests
+    import base64
+
+    BASE_URL = "http://localhost:13305/api/v1"
+
+    # Step 1: Generate an image
+    gen_response = requests.post(f"{BASE_URL}/images/generations", json={
+        "model": "SD-Turbo",
+        "prompt": "A serene mountain landscape at sunset",
+        "size": "512x512",
+        "steps": 4,
+        "response_format": "b64_json",
+    })
+    image_b64 = gen_response.json()["data"][0]["b64_json"]
+
+    # Step 2: Upscale the image with Real-ESRGAN (512x512 -> 2048x2048)
+    upscale_response = requests.post(f"{BASE_URL}/images/upscale", json={
+        "image": image_b64,
+        "model": "RealESRGAN-x4plus",
+    })
+
+    # Step 3: Save the upscaled image to a file
+    upscaled_b64 = upscale_response.json()["data"][0]["b64_json"]
+    with open("upscaled.png", "wb") as f:
+        f.write(base64.b64decode(upscaled_b64))
+    ```
+
+### Response format
+
+```json
+{
+  "created": 1742927481,
+  "data": [
+    {
+      "b64_json": "<base64-encoded upscaled PNG>"
+    }
+  ]
+}
+```
+
+**Field Descriptions:**
+
+- `created` - Unix timestamp of when the upscaled image was generated
+- `data` - Array containing the upscaled image
+  - `b64_json` - Base64-encoded PNG of the upscaled image
+
+### Error responses
+
+| Status Code | Condition | Example |
+|-------------|-----------|---------|
+| 400 | Missing `image` field | `{"error": {"message": "Missing 'image' field (base64 encoded)", "type": "invalid_request_error"}}` |
+| 400 | Missing `model` field | `{"error": {"message": "Missing 'model' field", "type": "invalid_request_error"}}` |
+| 404 | Unknown model name | `{"error": {"message": "Upscale model not found: bad-model", "type": "invalid_request_error"}}` |
+| 500 | Upscale failed | `{"error": {"message": "ESRGAN upscale failed", "type": "server_error"}}` |
+
+---
+
+## `POST /v1/audio/speech`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Speech Generation API. You provide a text input and receive an audio file. Which engine serves the request depends on the model.
+
+> **Note:** Supported models are `kokoro-v1` (fixed voices, [Kokoros](https://github.com/lucasjinreal/Kokoros) backend) and the OpenMOSS family — `OpenMOSS-TTS` and `MOSS-TTS-Local` support cloning and integrated voice design. `MOSS-VoiceGen` remains available as a legacy compatibility model while existing GUI/settings paths migrate to the integrated design flow.
+>
+> **Limitations:** Which `response_format` values are accepted depends on the model's backend: `kokoro-v1` encodes `mp3`, `wav`, `opus`, and `pcm`; OpenMOSS v0.3 encodes buffered `wav` or `pcm`. Native streaming is narrower for both backends and uses `pcm` only, so an explicit non-PCM `response_format` on a streaming request is rejected rather than mislabeled or silently transcoded. OpenMOSS raw PCM is returned as `audio/pcm` with `X-MOSS-Sample-Rate` and `X-MOSS-Channels`, because its native format is model-dependent (24 kHz mono for OpenMOSS-TTS and 48 kHz stereo for MOSS-TTS-Local).
+
+### Parameters
+
+| Parameter | Required | Description | Status |
+|-----------|----------|-------------|--------|
+| `input` | Yes | The text to speak. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `model` | Yes | The model to use (e.g., `kokoro-v1`). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `speed` | No | Speaking speed. Default: `1.0`. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `voice` | No | The voice to use. All OpenAI-defined voices can be used (`alloy`, `ash`, ...), as well as those defined by the kokoro model (`af_sky`, `am_echo`, ...). Default: `shimmer` | <sub>![Status](https://img.shields.io/badge/partial-yellow)</sub> |
+| `voice` (OpenMOSS) | No | For OpenMOSS models the field is a free-text voice/style instruction instead of a fixed voice name (e.g. `a calm, deep male narrator voice`). | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `reference_wav_b64` | No | Lemonade extension (OpenMOSS voice cloning): base64-encoded WAV sample of the voice to clone. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `voice_design_description` | No | Lemonade extension (OpenMOSS voice design): a description of the voice to invent, e.g. `a warm low female voice with a British accent`. Lemonade renders a short sample in that voice and uses it as the reference, so the effect is the same as supplying `reference_wav_b64` yourself. Ignored when `reference_wav_b64` is also present. Design is opt-in through this field only — `voice` never triggers it. | <sub>![Status](https://img.shields.io/badge/available-green)</sub> |
+| `response_format` | No | Container for the returned audio. Which values are accepted depends on the model's backend (see Limitations above). Default: `mp3` when buffered and `pcm` when streaming, falling back to the backend's first supported format when it cannot encode that default. | <sub>![Status](https://img.shields.io/badge/partial-yellow)</sub> |
+| `stream_format` | No | If set, the response is streamed. Only `audio` is supported. This selects the transport only — the container still comes from `response_format`, and an explicit one is honored on both transports. Default: not set| <sub>![Status](https://img.shields.io/badge/partial-yellow)</sub> |
+
+### Example request
+
+=== "Bash"
+
+    ```bash
+    curl -X POST http://localhost:13305/v1/audio/speech \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "kokoro-v1",
+            "input": "Lemonade can speak!",
+            "speed": 1.0,
+            "steps": 4,
+            "response_format": "mp3"
+          }'
+    ```
+
+### Response format
+
+The generated audio file is returned as-is.
+
+
+## `GET /v1/models`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Returns a list of models available on the server in an OpenAI-compatible format. Each model object includes extended fields like `checkpoint`, `recipe`, `size`, `downloaded`, `labels`, `context_length`, and, when known, `max_context_window`.
+
+By default, only models available locally (downloaded) are shown, matching OpenAI API behavior.
+
+When `lemond` is configured with cloud providers, cloud-routed models appear here alongside local ones with `recipe: "cloud"` and a `cloud_provider` field. They are dot-namespaced by provider (e.g. `fireworks.kimi-k2p5`) and accept the standard chat-completions / completions requests below — see [Cloud Offload](../guide/configuration/cloud.md).
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `show_all` | No | If set to `true`, returns all models from the catalog including those not yet downloaded. Defaults to `false`. |
+
+### Example request
+
+```bash
+# Show only downloaded models (OpenAI-compatible)
+curl http://localhost:13305/v1/models
+
+# Show all models including not-yet-downloaded (extended usage)
+curl http://localhost:13305/v1/models?show_all=true
+```
+
+### Response format
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "Qwen3-0.6B-GGUF",
+      "created": 1744173590,
+      "object": "model",
+      "owned_by": "lemonade",
+      "checkpoint": "unsloth/Qwen3-0.6B-GGUF:Q4_0",
+      "recipe": "llamacpp",
+      "size": 0.38,
+      "max_context_window": 40960,
+      "context_length": 8192,
+      "downloaded": true,
+      "suggested": true,
+      "update_available": false,
+      "labels": ["reasoning"]
+    },
+    {
+      "id": "Gemma-3-4b-it-GGUF",
+      "created": 1744173590,
+      "object": "model",
+      "owned_by": "lemonade",
+      "checkpoint": "ggml-org/gemma-3-4b-it-GGUF:Q4_K_M",
+      "recipe": "llamacpp",
+      "size": 3.61,
+      "downloaded": true,
+      "suggested": true,
+      "labels": ["hot", "vision"]
+    },
+    {
+      "id": "SD-Turbo",
+      "created": 1744173590,
+      "object": "model",
+      "owned_by": "lemonade",
+      "checkpoint": "stabilityai/sd-turbo:sd_turbo.safetensors",
+      "recipe": "sd-cpp",
+      "size": 5.2,
+      "downloaded": true,
+      "suggested": true,
+      "labels": ["image"],
+      "image_defaults": {
+        "steps": 4,
+        "cfg_scale": 1.0,
+        "width": 512,
+        "height": 512
+      }
+    }
+  ]
+}
+```
+
+**Field Descriptions:**
+
+- `object` - Type of response object, always `"list"`
+- `data` - Array of model objects with the following fields:
+  - `id` - Model identifier (used for loading and inference requests)
+  - `created` - Unix timestamp of when the model entry was created
+  - `object` - Type of object, always `"model"`
+  - `owned_by` - Owner of the model, always `"lemonade"`
+  - `checkpoint` - Full checkpoint identifier on Hugging Face
+  - `recipe` - Backend/device recipe used to load the model (e.g., `"ryzenai-llm"`, `"llamacpp"`, `"flm"`)
+  - `size` - Model size in GB (omitted for models without size information)
+  - `max_context_window` - Optional integer indicating the maximum model-supported text context discovered from local static metadata. Currently populated for downloaded GGUF/llama.cpp models and installed FLM text-context models.
+  - `context_length` - Number of tokens the model can handle in one request. Uses the loaded value when the model is running and the configured `ctx_size` otherwise (omitted when neither is known).
+  - `downloaded` - Boolean indicating if the model is downloaded and available locally
+  - `update_available` - Boolean indicating a newer commit exists on HuggingFace for this model. Only set for downloaded HF-backed models. `false` otherwise.
+  - `suggested` - Boolean indicating if the model is recommended for general use
+  - `labels` - Array of tags describing the model's capabilities and characteristics. See [Model Labels](#model-labels) for the full list.
+  - `image_defaults` - (Image models only) Default generation parameters for the model:
+    - `steps` - Number of inference steps (e.g., 4 for turbo models, 20 for standard models)
+    - `cfg_scale` - Classifier-free guidance scale (e.g., 1.0 for turbo models, 7.5 for standard models)
+    - `width` - Default image width in pixels
+    - `height` - Default image height in pixels
+  - `components` - (Omni collections only, `recipe: "collection.omni"`) Ordered array of the component model names that make up the collection
+  - `models` - (Omni collections only) Ordered array embedding each component's full model object (same shape as the entries in this list), parallel to `components`. This makes a collection's `/v1/models/{model_id}` response self-contained — exporting it produces a file that can be imported elsewhere via [`/v1/pull`](./lemonade.md#post-v1pull)
+
+
+### Model Labels
+
+Labels describe what a model can do. A model may carry multiple labels.
+
+**Deployment labels** — determine which backend endpoint the model is routed to.
+Every model names exactly one deployment mode, and a model is never given two
+labels that name different modes:
+
+| Label | Endpoint | Description |
+|-------|----------|-------------|
+| `chat` | `/chat/completions`, `/completions`, `/responses` | Text-generating LLM. This label is what makes a model an LLM — it is not inferred from `reasoning`/`vision`/`tool-calling`/`chat-transcription`, which are characteristics rather than deployment modes. |
+| `transcription` | `/audio/transcriptions` | Speech-to-text transcription model (e.g. Whisper). An omni LLM that accepts audio in a chat turn is not one of these — it carries `chat` and the `chat-transcription` capability below. |
+| `embeddings` | `/embeddings` | Produces text embedding vectors. Also accepted as `embedding`. |
+| `reranking` | `/rerank` | Scores and reranks a list of passages given a query. Also reachable at the aliases `/reranking` and `/reranker`. |
+| `image` | `/images/generations`, `/images/edits`, `/images/variations` | Text-to-image generation model. |
+| `tts` | `/audio/speech` | Text-to-speech synthesis model. |
+| `audio-generation` | `/audio/generations` | Text-to-audio generation model (e.g. music, sound effects). |
+| `classification` | `/classify` | Text classification model. Also accepted as `classifier`. |
+| `3d` | `/3d/generations` | Text- or image-to-3D mesh generation model. |
+
+When a model declares no deployment label at all, it inherits its recipe's
+default — `chat` for `llamacpp`, `flm`, `ryzenai-llm`, `vllm` and `cloud`,
+`transcription` for `whispercpp`, `image` for `sd-cpp`, `tts` for `kokoro`, and
+so on.
+
+Two label sets describe a model that cannot exist, and are refused rather than
+repaired:
+
+- **A mode the recipe's backend does not serve.** `/classify` is served only by
+  `onnxruntime`, so `labels: ["classification"]` on a `llamacpp` model is an
+  error — register it as the chat model it is.
+- **Two different modes.** `labels: ["chat", "embeddings"]` on a `llamacpp` model
+  is an error even though llama.cpp serves both: the subprocess is launched for
+  one mode, so the second would name an endpoint it was never configured to
+  answer. Register one model per mode. The legacy `embedding` and `reranking`
+  booleans count as mode claims here, exactly as the labels do.
+
+[`POST /v1/pull`](./lemonade.md#post-v1pull) answers `400` and registers nothing.
+An entry already stored in `user_models.json` — written before these rules — is
+skipped at startup with an error naming it, and the file is left untouched so it
+can be corrected by hand.
+
+**Input-modality labels** — the model accepts additional input types in `/chat/completions`:
+
+| Label | Description |
+|-------|-------------|
+| `vision` | Accepts image attachments in chat messages. |
+| `chat-transcription` | Accepts audio attachments in chat messages and transcribes them as part of its answer (e.g. Qwen2.5-Omni). Like `vision`, this is something a chat model can do, not a deployment mode of its own — a model carrying it also carries `chat`. It is distinct from `transcription`, which deploys a dedicated ASR model on `/audio/transcriptions`. |
+
+**Streaming labels** — capability flags for real-time features:
+
+| Label | Description |
+|-------|-------------|
+| `realtime-transcription` | Supports the WebSocket `/realtime` endpoint for live microphone transcription. |
+
+**Runtime labels** — affect backend launch defaults:
+
+| Label | Description |
+|-------|-------------|
+| `mtp` | Enables llama.cpp MTP draft decoding defaults (`--spec-type draft-mtp --spec-draft-n-max 3 --spec-draft-p-min 0.75`); users can override these with `llamacpp_args`. |
+
+**Image capability labels** — carried alongside `image`; they refine what the model is offered for without changing its deployment mode:
+
+| Label | Description |
+|-------|-------------|
+| `edit` | Tuned for editing an input image (`/images/edits`). Also selects the model for the `edit_image` role in an omni collection. |
+| `upscaling` | Image upscaling model (e.g. Real-ESRGAN, `/images/upscale`). Used as a component in image pipelines rather than offered on its own. |
+
+**Characteristic labels** — informational, do not affect routing:
+
+| Label | Description |
+|-------|-------------|
+| `hot` | Featured or popular model, highlighted in the UI. |
+| `reasoning` | Uses extended chain-of-thought reasoning (e.g. DeepSeek, Qwen3). |
+| `tool-calling` | Supports function/tool calling in chat completions. |
+| `coding` | Tuned for code generation and software tasks. |
+| `experimental` | Not yet validated for production use. |
+
+
+## `GET /v1/models/{model_id}`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Retrieve a specific model by its ID. Returns the same model object format as the list endpoint above.
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `model_id` | Yes | The ID of the model to retrieve. Must match one of the model IDs from the [models list](https://lemonade-server.ai/models.html). |
+
+### Example request
+
+```bash
+curl http://localhost:13305/v1/models/Qwen3-0.6B-GGUF
+```
+
+### Response format
+
+Returns a single model object with the same fields as described in the [models list endpoint](#get-v1models) above. For Omni collections (`recipe: "collection.omni"`), the object additionally carries `components` (ordered component names) and `models` (each component's full model object) — see the [collection file documentation](../guide/configuration/custom-models.md#share-a-collection-export-import-and-hugging-face).
+
+```json
+{
+  "id": "Qwen3-0.6B-GGUF",
+  "created": 1744173590,
+  "object": "model",
+  "owned_by": "lemonade",
+  "checkpoint": "unsloth/Qwen3-0.6B-GGUF:Q4_0",
+  "recipe": "llamacpp",
+  "size": 0.38,
+  "max_context_window": 40960,
+  "context_length": 8192,
+  "downloaded": true,
+  "suggested": true,
+  "labels": ["reasoning"],
+  "recipe_options": {
+    "ctx_size": 8192,
+    "llamacpp_args": "--no-mmap",
+    "llamacpp_backend": "rocm"
+  }
+}
+```
+
+### Error responses
+
+If the model is not found, the endpoint returns a 404 error:
+
+```json
+{
+  "error": {
+    "message": "Model Qwen3-0.6B-GGUF has not been found",
+    "type": "not_found"
+  }
+}
+```