### Install and Run Pre-commit Hooks

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/development_guide.md

Installs pre-commit hooks to enforce code style and quality checks before committing. Running `--all-files` applies these checks to the entire project.

```bash
pre-commit install
pre-commit run --all-files
```

--------------------------------

### MLX Omni Server Development Setup (Bash)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Outlines the steps to set up the MLX Omni Server for development. This includes cloning the repository, installing the project's dependencies in editable mode, and running the server using `uvicorn` with hot reloading enabled for development.

```bash
git clone https://github.com/zhutao100/mlx-omni-server.git
cd mlx-omni-server
```

```bash
pip install -e .
```

```bash
uvicorn mlx_omni_server.main:app --reload --host 0.0.0.0 --port 10240
```

--------------------------------

### Install Project Dependencies with uv

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/development_guide.md

Installs the project's dependencies in editable mode using the uv package manager. This command ensures all necessary libraries are available for development.

```bash
uv pip install -e .
```

--------------------------------

### Install MLX Omni Server

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Installs the MLX Omni Server by cloning the repository and installing it via pip. Requires git and Python 3.11+.

```bash
git clone https://github.com/zhutao100/mlx-omni-server.git
cd mlx-omni-server
pip install .
```

--------------------------------

### Clone MLX Omni Server Repository

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/development_guide.md

Clones the MLX Omni Server repository from GitHub and navigates into the project directory. This is the initial step for setting up the development environment.

```bash
git clone https://github.com/zhutao100/mlx-omni-server.git
cd mlx-omni-server
```

--------------------------------

### Function Calling Example (cURL)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Provides a cURL command for making a function calling request to the MLX Omni Server. This example mirrors the Python function calling setup, demonstrating the JSON payload required.

```bash
curl http://localhost:10240/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/Qwen3-Coder-30B-A3B-Instruct-8bit",
    "messages": [{"role": "user", "content": "What\'s the weather like in Boston?"}],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},
                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "tool_choice": "auto"
  }'
```

--------------------------------

### Function Calling Example (Python)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Demonstrates how to implement function calling with the MLX Omni Server using the OpenAI SDK. This example shows defining tools and making a chat completion request that the model can use to call a function. Supported by Qwen3 and GLM model families. Requires the 'openai' library.

```python
import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="mlx-community/Qwen3-Coder-30B-A3B-Instruct-8bit",
    messages=[{"role": "user", "content": "What's the weather like in Boston?"}],
    tools=tools,
    tool_choice="auto",
)
```

--------------------------------

### Run MLX Omni Server with uvicorn

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/development_guide.md

Starts the MLX Omni Server in development mode using uvicorn. The `--reload` flag enables automatic server restarts upon code changes, and `--host` and `--port` specify the server's network address and port.

```bash
uvicorn mlx_omni_server.main:app --reload --host 0.0.0.0 --port 10240
```

--------------------------------

### Run MLX Omni Server (Standard Entry Point)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/development_guide.md

Executes the MLX Omni Server using its standard entry point command. This is an alternative method for running the server during development.

```bash
mlx-omni-server
```

--------------------------------

### Production and Development Server Configuration (Bash)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Provides commands for running the MLX Omni Server in different configurations. The first command sets up a multi-worker production environment with specified log levels. The second command starts the server in development mode with hot reloading enabled.

```bash
# Multi-worker setup for better throughput
mix-omni-server --workers 2 --log-level warning
```

```bash
# Development with hot reload
uvicorn mlx_omni_server.main:app --reload --port 10240
```

--------------------------------

### Run Project Tests with Pytest

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/development_guide.md

Executes the project's test suite using the pytest framework. This command ensures that all tests pass, verifying the functionality and stability of the code.

```bash
pytest
```

--------------------------------

### Download Model using Hugging Face CLI (Bash)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Provides a command to download a specific model from Hugging Face using the `huggingface-cli` tool. This is useful for troubleshooting model download issues or pre-downloading models. Ensure you have the Hugging Face CLI installed and configured.

```bash
huggingface-cli download mlx-community/gemma-3-1b-it-4bit-DWQ
```

--------------------------------

### Create Feature Branch for Development

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/development_guide.md

Creates a new Git branch for developing a new feature. This is a standard practice in collaborative development workflows.

```bash
git checkout -b feature/amazing-feature
```

--------------------------------

### Interact with MLX Omni Server via REST API (cURL)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Provides examples of interacting with the MLX Omni Server's REST API using cURL. Includes making chat completion requests and listing available models. Requires a running server instance.

```bash
# Chat completions
curl http://localhost:10240/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/gemma-3-1b-it-4bit-DWQ",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# List available models
curl http://localhost:10240/v1/models
```

--------------------------------

### GET /v1/models

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Retrieve a list of available models on the server.

```APIDOC
## GET /v1/models

### Description

Fetches a list of all models currently available and loadable by the MLX Omni Server.

### Method

GET

### Endpoint

`/v1/models`

### Parameters

None

### Response

#### Success Response (200)

*   **data** (array) - A list of model objects.
    *   **id** (string) - The unique identifier for the model.
    *   **object** (string) - The type of object, typically "model".
    *   **owned_by** (string) - The entity that owns the model.

### Response Example

```json
{
  "data": [
    {
      "id": "mlx-community/gemma-3-1b-it-4bit-DWQ",
      "object": "model",
      "owned_by": "community"
    },
    {
      "id": "mlx-community/Llama-3.2-3B-Instruct-4bit",
      "object": "model",
      "owned_by": "community"
    }
  ],
  "object": "list"
}
```
```

--------------------------------

### Push Feature Branch to Remote Repository

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/development_guide.md

Pushes the newly created feature branch to the remote origin repository. This makes the branch accessible for collaboration and pull requests.

```bash
git push origin feature/amazing-feature
```

--------------------------------

### Basic Chat Completion Test with cURL

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Tests the chat completion endpoint of the MLX Omni Server using cURL. This example sends a simple message to the server and expects a text response.

```bash
curl http://localhost:10240/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/gemma-3-1b-it-4bit-DWQ",
    "messages": [
      {
        "role": "user",
        "content": "What can you do?"
      }
    ]
  }'
```

--------------------------------

### Specify Model for Chat Completion (Python)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

This Python example demonstrates how to explicitly select a model for chat completions by using the 'model' parameter in the API request. This ensures that the desired model is used for processing the messages.

```python
response = client.chat.completions.create(
    model="mlx-community/gemma-3b-it-4bit-DWQ",
    messages=[{"role": "user", "content": "Hello"}]
)
```

--------------------------------

### Generate Embeddings using cURL

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

This example shows how to generate embeddings using the cURL command-line tool. It specifies the API endpoint, the content type, and the request body containing the model name and input text for embedding.

```bash
curl http://localhost:10240/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/all-MiniLM-L6-v2-4bit",
    "input": ["Hello world!", "Embeddings are useful for semantic search."]
  }'
```

--------------------------------

### MLX Omni Server Configuration Options

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Demonstrates various ways to configure and run the MLX Omni Server using command-line arguments. Covers default settings, custom ports, host binding, logging levels, and worker processes.

```bash
mlx-omni-server
mlx-omni-server --port 8000
mlx-omni-server --host 127.0.0.1 --port 8000
mlx-omni-server --log-level debug
mlx-omni-server --workers 2 --log-level warning
mlx-omni-server --help
```

--------------------------------

### Server Configuration

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Details on how to run and configure the MLX Omni Server, including command-line options and their default values.

```APIDOC
## Server Configuration

MLX Omni Server can be run with various configurations using command-line arguments.

### Command Line Usage

*   **Default settings:** `mlx-omni-server` (binds to port 10240 on all interfaces)
*   **Custom port:** `mlx-omni-server --port 8000`
*   **Specific host and port:** `mlx-omni-server --host 127.0.0.1 --port 8000`
*   **Development with debug logging:** `mlx-omni-server --log-level debug`
*   **Production with multiple workers:** `mlx-omni-server --workers 2 --log-level warning`
*   **View all options:** `mlx-omni-server --help`

### Configuration Options

| Option      | Default   | Description                           |
|-------------|-----------|---------------------------------------|
| `--host`    | `0.0.0.0` | Host to bind the server to            |
| `--port`    | `10240`   | Port to bind the server to            |
| `--workers` | `1`       | Number of worker processes            |
| `--log-level`| `info`    | Logging level (debug, info, warning, error, critical) |
```

--------------------------------

### MLX Omni Server OpenAI SDK Integration (Python)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Shows how to set up and use the OpenAI Python SDK to interact with the MLX Omni Server. This method abstracts the direct HTTP requests, making integration simpler. Requires the 'openai' library.

```python
from openai import OpenAI

# Standard client setup
client = OpenAI(
    base_url="http://localhost:10240/v1",
    api_key="not-needed"
)
```

--------------------------------

### Test Client for OpenAI API with MLX Omni Server (Python)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Demonstrates how to use FastAPI's TestClient to simulate requests to the MLX Omni Server's OpenAI-compatible API for testing purposes. This allows for development and testing without needing to run a live server instance. It initializes an OpenAI client with the TestClient.

```python
from openai import OpenAI
from fastapi.testclient import TestClient
from mlx_omni_server.main import app

client = OpenAI(http_client=TestClient(app))
response = client.chat.completions.create(
    model="mlx-community/gemma-3-1b-it-4bit-DWQ",
    messages=[{"role": "user", "content": "Hello"}]
)
```

--------------------------------

### List Available Models via API (Bash) and Python Client

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Shows two methods for listing the models available on the MLX Omni Server: using `curl` to query the server's API endpoint, and using the Python client's `models.list()` method. Both methods retrieve a list of model IDs.

```bash
curl http://localhost:10240/v1/models
```

```python
response = client.models.list()
for model in response.data:
    print(f"Model ID: {model.id}")
```

--------------------------------

### Chat Completion with OpenAI Python Client

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Demonstrates how to use the OpenAI Python client to interact with the MLX Omni Server. It connects to the local server and performs a basic chat completion.

```python
from openai import OpenAI

# Connect to local server
client = OpenAI(
    base_url="http://localhost:10240/v1",
    api_key="not-needed"
)

# Simple chat request
response = client.chat.completions.create(
    model="mlx-community/gemma-3-1b-it-4bit-DWQ",
    messages=[{"role": "user", "content": "Hello! How are you?"}]
)
print(response.choices[0].message.content)
```

--------------------------------

### Image Description from URL

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Generate a description for an image by providing its URL.

```APIDOC
## POST /v1/chat/completions

### Description
This endpoint allows for multimodal chat completions, enabling the model to understand and describe images provided via URL.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for the chat completion (e.g., "llava-v1.6-7b").
- **messages** (array) - Required - An array of message objects. Each object can contain:
  - **role** (string) - The role of the message (e.g., "user").
  - **content** (array) - The content of the message, which can include:
    - **type** (string) - The type of content ("text" or "image_url").
    - **text** (string) - The text content.
    - **image_url** (object) - An object containing the image URL:
      - **url** (string) - The URL of the image.

### Request Example
```json
{
  "model": "llava-v1.6-7b",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What's in this image?"},
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.jpg"
          }
        }
      ]
    }
  ]
}
```

### Response
#### Success Response (200)
- **choices** (array) - An array of message choices.
  - **message** (object)
    - **content** (string) - The model's response describing the image.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "content": "The image contains a cat sleeping on a couch."
      }
    }
  ]
}
```
```

--------------------------------

### Using Local Models with OpenAI Client (Python)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Demonstrates how to utilize a model that has already been downloaded and is available locally. The `model` parameter is set to the local file path of the model. This is part of the MLX Omni Server's flexible model management.

```python
response = client.chat.completions.create(
    model="/path/to/your/local/model",  # Local model path
    messages=[{"role": "user", "content": "Hello"}]
)
```

--------------------------------

### Auto-download and Use Local Models (Python)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

This Python snippet shows how MLX Omni Server automatically downloads models from Hugging Face on first use. It also demonstrates how to specify a local path to use pre-downloaded models.

```python
# Auto-download on first use
response = client.chat.completions.create(
    model="mlx-community/gemma-3b-it-4bit-DWQ",  # Downloads if not available
    messages=[{"role": "user", "content": "Hello"}]
)

# Use pre-downloaded local models
response = client.chat.completions.create(
    model="/path/to/your/local/model",  # Local path
    messages=[{"role": "user", "content": "Hello"}]
)
```

--------------------------------

### Chat Completion with Streaming (Python)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Illustrates how to perform chat completions with streaming enabled using the OpenAI SDK and MLX Omni Server. This allows for real-time processing of responses. Requires the 'openai' library.

```python
response = client.chat.completions.create(
    model="mlx-community/Llama-3.2-3B-Instruct-4bit",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    temperature=0,
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

--------------------------------

### Describe Image from URL with MLX VLM Model

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Generates a description of an image by sending its URL to a VLM model. Requires the client library and a VLM model like 'llava-v1.6-7b'.

```python
response = client.chat.completions.create(
    model="llava-v1.6-7b",  # VLM model
    messages=[{
        "role": "user", 
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://example.com/image.jpg"
                }
            }
        ]
    }]
)

print(response.choices[0].message.content)
```

--------------------------------

### MLX Omni Server FastAPI TestClient (Python)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Demonstrates how to use FastAPI's TestClient with the MLX Omni Server's app for testing API interactions without running a separate server process. Ideal for development and testing workflows. Requires 'openai' and 'fastapi' libraries.

```python
from openai import OpenAI
from fastapi.testclient import TestClient
from mlx_omni_server.main import app

client = OpenAI(http_client=TestClient(app))
```

--------------------------------

### Image Generation with MLX

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Generates an image based on a text prompt using a specified model, resolution, and quantity. Uses the 'argmaxinc/mlx-FLUX.1-schnell' model for generation.

```python
image_response = client.images.generate(
    model="argmaxinc/mlx-FLUX.1-schnell",
    prompt="A serene landscape with mountains and a lake",
    n=1,
    size="512x512"
)
```

--------------------------------

### Automatic Model Downloading with OpenAI Client (Python)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Illustrates how the MLX Omni Server automatically downloads models from Hugging Face when a model ID is provided that is not yet available locally. This snippet shows the usage within the OpenAI client's chat completions creation.

```python
response = client.chat.completions.create(
    model="mlx-community/gemma-3-1b-it-4bit-DWQ",  # Will download if not available
    messages=[{"role": "user", "content": "Hello"}]
)
```

--------------------------------

### Multiple Image Description

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Provide descriptions and comparisons for multiple images in a single request.

```APIDOC
## POST /v1/chat/completions (Multiple Images)

### Description
This endpoint allows for processing multiple images in a single request for tasks like comparison or detailed analysis.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model to use (e.g., "llava-v1.6-7b").
- **messages** (array) - Required - An array of message objects, including multiple image URLs:
  - **role** (string) - The role of the message (e.g., "user").
  - **content** (array) - The content of the message:
    - **type** (string) - The type of content ("text" or "image_url").
    - **text** (string) - The text content.
    - **image_url** (object) - An object containing the image URL.

### Request Example
```json
{
  "model": "llava-v1.6-7b",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Compare these two images:"},
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image1.jpg"
          }
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image2.jpg"
          }
        }
      ]
    }
  ]
}
```

### Response
#### Success Response (200)
- **choices** (array) - An array of message choices.
  - **message** (object)
    - **content** (string) - The model's response comparing the images.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "content": "Image 1 shows a sunny beach, while Image 2 depicts a cloudy mountain landscape."
      }
    }
  ]
}
```
```

--------------------------------

### Describe Image from Base64 with MLX VLM Model

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Describes an image provided as a Base64 encoded string. This involves loading an image, encoding it, and then sending it to the VLM model. Dependencies include Pillow and requests.

```python
import base64
from io import BytesIO
from PIL import Image
import requests

# Load and encode image as base64
image_url = "https://example.com/image.jpg"
response = requests.get(image_url)
image = Image.open(BytesIO(response.content))

buffered = BytesIO()
image.save(buffered, format="JPEG")
img_str = base64.b64encode(buffered.getvalue()).decode()

# Send to model
response = client.chat.completions.create(
    model="llava-v1.6-7b",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {
                "type": "image_url",
                "image_url": {
                    "url": f"data:image/jpeg;base64,{img_str}"
                }
            }
        ]
    }]
)

print(response.choices[0].message.content)
```

--------------------------------

### Describe Multiple Images with MLX VLM Model

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Compares or describes multiple images by sending their URLs in a single request to the VLM model. This allows for multi-image analysis.

```python
response = client.chat.completions.create(
    model="llava-v1.6-7b",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Compare these two images:"},
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://example.com/image1.jpg"
                }
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://example.com/image2.jpg"
                }
            }
        ]
    }]
)

print(response.choices[0].message.content)
```

--------------------------------

### Create Audio Transcription (VTT Format)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/apis/audio.md

Transcribes an audio file and returns the transcription in WebVTT format, commonly used for video subtitles. Requires `response_format=vtt`.

```shell
curl -X POST "http://localhost:10240/v1/audio/transcriptions" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@mlx_example.wav" \
  -F "model=mlx-community/whisper-large-v3-turbo" \
  -F "response_format=vtt"
```

--------------------------------

### Create Audio Transcription (Text Format)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/apis/audio.md

Transcribes an audio file and returns the transcription as plain text. This is useful for simple text output. Requires specifying `response_format=text` in the request.

```shell
curl -X POST "http://localhost:10240/audio/transcriptions" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@mlx_example.wav" \
  -F "model=mlx-community/whisper-large-v3-turbo" \
  -F "response_format=text"
```

--------------------------------

### Chat Completion with Streaming (cURL)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Provides a cURL command to perform chat completions with streaming enabled against the MLX Omni Server. Useful for testing streaming functionality directly from the command line.

```bash
curl http://localhost:10240/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/Llama-3.2-3B-Instruct-4bit",
    "stream": true,
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

--------------------------------

### Image Description using Base64 Encoded Image

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Generate a description for an image by providing its Base64 encoded string.

```APIDOC
## POST /v1/chat/completions (Base64 Image)

### Description
This endpoint allows for multimodal chat completions using Base64 encoded images.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model to use (e.g., "llava-v1.6-7b").
- **messages** (array) - Required - An array of message objects:
  - **role** (string) - The role of the message (e.g., "user").
  - **content** (array) - The content of the message:
    - **type** (string) - The type of content ("text" or "image_url").
    - **text** (string) - The text content.
    - **image_url** (object) - An object containing the Base64 encoded image URL:
      - **url** (string) - The Base64 encoded image string (e.g., "data:image/jpeg;base64,...").

### Request Example
```json
{
  "model": "llava-v1.6-7b",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What's in this image?"},
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_STRING"
          }
        }
      ]
    }
  ]
}
```

### Response
#### Success Response (200)
- **choices** (array) - An array of message choices.
  - **message** (object)
    - **content** (string) - The model's response describing the image.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "content": "The image shows a dog playing fetch in a park."
      }
    }
  ]
}
```
```

--------------------------------

### Create Audio Transcription (SRT Format)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/apis/audio.md

Transcribes an audio file and returns the transcription in SubRip Text (SRT) format, suitable for subtitles. Requires `response_format=srt`.

```shell
curl -X POST "http://localhost:10240/audio/transcriptions" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@mlx_example.wav" \
  -F "model=mlx-community/whisper-large-v3-turbo" \
  -F "response_format=srt"
```

--------------------------------

### Models API

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Provides endpoints to list available models and retrieve information about a specific model.

```APIDOC
## GET /v1/models

### Description
Lists all the models available through the MLX Omni Server.

### Method
GET

### Endpoint
/v1/models

### Parameters
None

### Response
#### Success Response (200)
- **object** (string) - Type of object, usually `list`.
- **data** (array) - A list of model objects.
  - **id** (string) - The unique identifier for the model.
  - **object** (string) - The type of object, usually `model`.
  - **created** (integer) - Unix timestamp of model creation.
  - **owned_by** (string) - The entity that owns the model.

#### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "mlx-community/gemma-3-1b-it-4bit-DWQ",
      "object": "model",
      "created": 1677652288,
      "owned_by": "MLX"
    },
    {
      "id": "mlx-community/llama3-8b-8bit",
      "object": "model",
      "created": 1677652288,
      "owned_by": "MLX"
    }
  ]
}
```
```

```APIDOC
## GET /v1/models/{model}

### Description
Retrieves information about a specific model.

### Method
GET

### Endpoint
/v1/models/{model}

### Parameters
#### Path Parameters
- **model** (string) - Required - The ID of the model to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the model.
- **object** (string) - The type of object, usually `model`.
- **created** (integer) - Unix timestamp of model creation.
- **owned_by** (string) - The entity that owns the model.

#### Response Example
```json
{
  "id": "mlx-community/gemma-3-1b-it-4bit-DWQ",
  "object": "model",
  "created": 1677652288,
  "owned_by": "MLX"
}
```
```

--------------------------------

### List Available Models (cURL)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

This cURL command retrieves a list of all models currently available on the MLX Omni Server. This is useful for checking which models have been downloaded or are accessible.

```bash
curl http://localhost:10240/v1/models
```

--------------------------------

### Image Generations API

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Generates images based on text prompts.

```APIDOC
## POST /v1/images/generations

### Description
Generates an image from a text prompt using a specified model.

### Method
POST

### Endpoint
/v1/images/generations

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for image generation.
- **prompt** (string) - Required - A text description of the desired image.
- **n** (integer) - Optional - The number of images to generate. Defaults to 1.
- **size** (string) - Optional - The size of the generated images. Defaults to `1024x1024`.
- **response_format** (string) - Optional - The format in which the generated images are returned. Defaults to `url`.

### Request Example
```json
{
  "model": "mlx-community/flux-v0.1",
  "prompt": "A photo of a futuristic cityscape at sunset",
  "n": 1,
  "size": "1024x1024"
}
```

### Response
#### Success Response (200)
- **created** (integer) - Unix timestamp of creation.
- **data** (array) - A list of image objects.
  - **url** (string) - The URL of the generated image (if `response_format` is `url`).
  - **b64_json** (string) - The base64 encoded image data (if `response_format` is `b64_json`).

#### Response Example
```json
{
  "created": 1677652288,
  "data": [
    {
      "url": "http://localhost:10240/images/generated_image.png"
    }
  ]
}
```
```

--------------------------------

### Image Generation

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Generate images based on textual prompts using a specified model.

```APIDOC
## POST /v1/images/generations

### Description
Generates images based on a provided text prompt using a specified image generation model. You can control the number of images and their size.

### Method
POST

### Endpoint
/v1/images/generations

### Parameters
#### Request Body
- **model** (string) - Required - The image generation model to use (e.g., "argmaxinc/mlx-FLUX.1-schnell").
- **prompt** (string) - Required - The textual description for the image to be generated.
- **n** (integer) - Optional - The number of images to generate. Defaults to 1.
- **size** (string) - Optional - The desired size of the generated images (e.g., "512x512", "1024x1024").

### Request Example (cURL)
```shell
curl http://localhost:10240/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{ 
    "model": "argmaxinc/mlx-FLUX.1-schnell",
    "prompt": "A cute baby sea otter",
    "n": 1,
    "size": "1024x1024"
  }'
```

### Response
#### Success Response (200)
- The response typically contains URLs or data for the generated images. (Specific structure may vary by model implementation.)

#### Response Example (Conceptual)
```json
{
  "data": [
    {
      "url": "http://localhost:10240/generated_images/image1.png",
      "size": "1024x1024"
    }
  ]
}
```
```

--------------------------------

### POST /v1/chat/completions

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/README.md

Submit a chat completion request to the server. Supports streaming and function calling.

```APIDOC
## POST /v1/chat/completions

### Description

This endpoint allows you to interact with the chat models for conversational AI tasks. It supports streaming responses and function calling for structured output.

### Method

POST

### Endpoint

`/v1/chat/completions`

### Parameters

#### Request Body

*   **model** (string) - Required - The model identifier to use for completion.
*   **messages** (array) - Required - A list of messages comprising the conversation.
    *   **role** (string) - Required - Role of the author ('user', 'assistant', 'system').
    *   **content** (string) - Required - The content of the message.
*   **stream** (boolean) - Optional - Whether to stream back partial message deltas.
*   **temperature** (number) - Optional - Controls randomness. Lower values make output more deterministic.
*   **tools** (array) - Optional - A list of tools the model may call.
*   **tool_choice** (string or object) - Optional - Controls whether the model calls a function.

### Request Example (Standard Chat)

```bash
curl http://localhost:10240/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ 
    "model": "mlx-community/gemma-3-1b-it-4bit-DWQ",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

### Request Example (Streaming)

```bash
curl http://localhost:10240/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ 
    "model": "mlx-community/Llama-3.2-3B-Instruct-4bit",
    "stream": true,
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

### Request Example (Function Calling)

```bash
curl http://localhost:10240/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ 
    "model": "mlx-community/Qwen3-Coder-30B-A3B-Instruct-8bit",
    "messages": [{"role": "user", "content": "What\'s the weather like in Boston?"}],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},
                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "tool_choice": "auto"
  }'
```

### Response

#### Success Response (200)

*   **id** (string) - Unique identifier for the completion.
*   **choices** (array) - A list of completion choices.
    *   **message** (object) - The generated message.
        *   **role** (string) - The role of the author of the message.
        *   **content** (string) - The content of the message.
    *   **finish_reason** (string) - The reason the model stopped generating tokens.
*   **model** (string) - The model used for the completion.
*   **usage** (object) - Information about token usage.
    *   **prompt_tokens** (integer) - Number of tokens in the prompt.
    *   **completion_tokens** (integer) - Number of tokens in the completion.
    *   **total_tokens** (integer) - Total tokens used.

#### Streaming Response Example (chunk)

```json
{
  "id": "chatcmpl-xxxxxxxxxxxxx",
  "choices": [
    {
      "delta": {
        "role": "assistant"
      },
      "index": 0
    }
  ],
  "model": "mlx-community/Llama-3.2-3B-Instruct-4bit",
  "finish_reason": null
}
```

```json
{
  "id": "chatcmpl-xxxxxxxxxxxxx",
  "choices": [
    {
      "delta": {
        "content": "Hello! How can I help you today?"
      },
      "index": 0
    }
  ],
  "model": "mlx-community/Llama-3.2-3B-Instruct-4bit",
  "finish_reason": "stop"
}
```
```

--------------------------------

### Create Audio Transcription (Verbose Word JSON)

Source: https://github.com/zhutao100/mlx-omni-server/blob/main/docs/apis/audio.md

Transcribes an audio file and returns detailed JSON output with word-level timestamps and probabilities. Requires `timestamp_granularities[]=word` and `response_format=verbose_json`.

```shell
curl -X POST "http://localhost:10240/audio/transcriptions" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@mlx_example.wav" \
  -F "model=mlx-community/whisper-large-v3-turbo" \
  -F "timestamp_granularities[]=word" \
  -F "response_format=verbose_json"
```