> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modellix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Modellix LLM API Guide

> Call Modellix LLM with OpenAI-compatible Chat Completions and Responses or Anthropic-compatible Messages—sync requests, streaming SSE, multimodal content parts, auth, model list, request logs, errors, and billing.

Modellix LLM is a text gateway at `https://llm.modellix.ai` with three protocol surfaces:

| Protocol         | Method | Path                   | Typical clients                              |
| ---------------- | ------ | ---------------------- | -------------------------------------------- |
| Chat Completions | `POST` | `/v1/chat/completions` | OpenAI SDK, Codex, Cursor, most chat clients |
| Responses        | `POST` | `/v1/responses`        | OpenAI Responses API clients                 |
| Messages         | `POST` | `/v1/messages`         | Anthropic SDK, Claude Code                   |

Also available on the same host: [`GET /v1/models`](#list-models) and [`GET /v1/logs`](#request-logs).

Calls are **synchronous** (optional streaming SSE). Request and response shapes follow the corresponding official protocols; this guide lists core fields only. Full OpenAPI specs: [Chat Completions](/llm/chat-completions), [Responses](/llm/responses), [Messages](/llm/messages), [List models](/llm/list-models), [Request logs](/llm/get-llm-logs).

<Note>
  Media generation (image, video, speech) uses `https://api.modellix.ai` and async tasks. Do not mix that host with the LLM gateway.
</Note>

## Base URL and Auth

| Item        | Value                                                                             |
| ----------- | --------------------------------------------------------------------------------- |
| Host        | `https://llm.modellix.ai`                                                         |
| Path prefix | `/v1`                                                                             |
| Auth        | `Authorization: Bearer <Modellix API Key>` **or** `x-api-key: <Modellix API Key>` |

```http theme={null}
Authorization: Bearer mdlx-xxxxxxxx
```

```http theme={null}
x-api-key: mdlx-xxxxxxxx
```

Both headers are equivalent. If both are sent, they must be the same key. Get a key from the [console](https://modellix.ai/console/api-key)—not a vendor platform key.

| Header style | Typical clients                     |
| ------------ | ----------------------------------- |
| Bearer       | OpenAI SDK, Codex, OpenCode, Cursor |
| `x-api-key`  | Anthropic SDK, Claude Code          |

## Models

Pass `model` in the JSON body as `provider/name`. See [Models & Pricing](/llm/overview#models-and-pricing) for the full Model ID list and rates. Availability follows the console and product releases.

You can also list currently available Model IDs via [`GET /v1/models`](#list-models).

## Choose a Protocol

The three endpoints use **different URLs and body shapes**. Do not mix fields across protocols.

|        | Chat Completions                                  | Responses                         | Messages                                 |
| ------ | ------------------------------------------------- | --------------------------------- | ---------------------------------------- |
| Input  | `messages: [{role, content}, ...]`                | `input` (string or content array) | Anthropic `messages` + optional `system` |
| Length | `max_tokens` / `max_completion_tokens`            | `max_output_tokens`               | `max_tokens` (**required**)              |
| Stream | `stream: true` → OpenAI chat.completion.chunk SSE | `stream: true` → Responses SSE    | `stream: true` → Anthropic Messages SSE  |

**Routing tips**

| Model prefix    | Recommended protocol                                                     |
| --------------- | ------------------------------------------------------------------------ |
| `openai/...`    | Chat Completions or Responses                                            |
| `anthropic/...` | Messages (Anthropic clients); Chat Completions also works for many tools |
| `google/...`    | Chat Completions or Responses                                            |

## Chat Completions

```http theme={null}
POST /v1/chat/completions
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

| Field                   | Required | Description                                     |
| ----------------------- | -------- | ----------------------------------------------- |
| `model`                 | Yes      | Model ID                                        |
| `messages`              | Yes      | OpenAI-style messages                           |
| `stream`                | No       | Default `false`; `true` returns SSE             |
| `max_tokens`            | No       | Generation cap (model-dependent)                |
| `max_completion_tokens` | No       | Preferred cap on some newer OpenAI-style models |
| `temperature`           | No       | Sampling temperature                            |
| `n`                     | No       | Number of choices                               |

```bash theme={null}
curl -sS "https://llm.modellix.ai/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "stream": false,
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Introduce yourself in one sentence"}]
  }'
```

Streaming:

```bash theme={null}
curl -sS -N "https://llm.modellix.ai/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "stream": true,
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

See [Create chat completion](/llm/chat-completions). For image and video `content` parts, see [Multimodal Inputs](#multimodal-inputs).

## Responses

```http theme={null}
POST /v1/responses
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

| Field               | Required | Description                                               |
| ------------------- | -------- | --------------------------------------------------------- |
| `model`             | Yes      | Model ID                                                  |
| `input`             | Yes      | String or content array (not Chat Completions `messages`) |
| `stream`            | No       | Default `false`                                           |
| `max_output_tokens` | No       | Output cap                                                |
| `temperature`       | No       | Sampling temperature                                      |

```bash theme={null}
curl -sS "https://llm.modellix.ai/v1/responses" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-luna",
    "stream": false,
    "max_output_tokens": 256,
    "input": "Introduce yourself in one sentence"
  }'
```

See [Create response](/llm/responses). For `input_image` / `input_file`, see [Multimodal Inputs](#multimodal-inputs).

## Messages (Anthropic)

```http theme={null}
POST /v1/messages
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

| Field        | Required | Description                                    |
| ------------ | -------- | ---------------------------------------------- |
| `model`      | Yes      | For example `anthropic/claude-sonnet-5`        |
| `messages`   | Yes      | Anthropic messages (`user` / `assistant` only) |
| `max_tokens` | Yes      | Output cap                                     |
| `stream`     | No       | Default `false`                                |
| `system`     | No       | System prompt (string or content blocks)       |

Auth may use Bearer or `x-api-key`. Optional `anthropic-version` header is forwarded when present.

```bash theme={null}
curl -sS "https://llm.modellix.ai/v1/messages" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

See [Create message](/llm/messages). For `image` / `document` blocks, see [Multimodal Inputs](#multimodal-inputs).

<h2 id="multimodal-inputs">
  Multimodal Inputs
</h2>

Field names follow the protocol you call. Prefer a public HTTPS URL, including the `url` returned by the Media [File API](/ways-to-use/api#upload-media-files). Local filesystem paths are ignored.

Image, video, and audio support is per **model**—see [Models & Pricing](/llm/overview#models-and-pricing). Examples use `google/gemini-3.7-flash`. Check `usage` to confirm the media was consumed.

| Client                            | Endpoint                                    | Image                            | File / PDF            | Video                     | Audio                       |
| --------------------------------- | ------------------------------------------- | -------------------------------- | --------------------- | ------------------------- | --------------------------- |
| OpenAI SDK, Codex, most chat apps | [Chat Completions](#chat-completions-parts) | `image_url.url`                  | `file.file_id`        | `file.file_id` + `format` | `input_audio` (inline only) |
| OpenAI Responses clients          | [Responses](#responses-parts)               | `input_image.image_url` (string) | `input_file.file_url` | `input_file.file_url`     | —                           |
| Anthropic SDK, Claude Code        | [Messages](#messages-parts)                 | `image.source.url`               | `document.source.url` | —                         | —                           |

Do not mix fields across protocols. OpenAI or Anthropic Files IDs (`file-...`) are not accepted; for Media File API uploads, pass the returned **`url`**, not the UUID. Uploads default to **16 MB**.

Official schemas: [Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create/), [Responses](https://developers.openai.com/api/reference/resources/responses/methods/create/), [Messages](https://docs.anthropic.com/en/api/messages), [vision](https://developers.openai.com/api/docs/guides/images-vision), [file inputs](https://developers.openai.com/api/docs/guides/file-inputs), [Anthropic vision](https://docs.anthropic.com/en/docs/build-with-claude/vision).

<h3 id="chat-completions-parts">
  Chat Completions
</h3>

Recommended: HTTPS in `image_url.url` or `file.file_id`. There is no `video_url` type.

```bash theme={null}
curl -sS "https://llm.modellix.ai/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.7-flash",
    "stream": false,
    "max_tokens": 256,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What appears in this video?"},
        {
          "type": "file",
          "file": {
            "file_id": "https://example.com/clip.mp4",
            "format": "video/mp4"
          }
        }
      ]
    }]
  }'
```

Image: `{ "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }`. Audio has no URL field: `{ "type": "input_audio", "input_audio": { "data": "<raw Base64>", "format": "wav" } }` (`mp3` is also valid). If the model returns `usage.prompt_tokens_details.video_tokens` or `audio_tokens`, those counts are already inside `prompt_tokens`—see [Billing](#billing).

<h3 id="responses-parts">
  Responses
</h3>

Recommended: HTTPS string in `input_image.image_url` or `input_file.file_url` (not the Chat Completions nested `{ "url": "..." }` object).

```json theme={null}
{
  "model": "google/gemini-3.7-flash",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "What appears in this video?" },
        { "type": "input_file", "file_url": "https://example.com/clip.mp4" }
      ]
    }
  ]
}
```

Image: `{ "type": "input_image", "image_url": "https://example.com/photo.jpg" }`.

<h3 id="messages-parts">
  Messages
</h3>

Recommended: HTTPS in `source.url`. This protocol has no video or audio block. For those inputs, use Chat Completions or Responses.

```json theme={null}
{
  "model": "anthropic/claude-sonnet-5",
  "max_tokens": 256,
  "messages": [{
    "role": "user",
    "content": [
      {
        "type": "image",
        "source": { "type": "url", "url": "https://example.com/photo.jpg" }
      },
      { "type": "text", "text": "Describe this image." }
    ]
  }]
}
```

PDF: `{ "type": "document", "source": { "type": "url", "url": "https://example.com/doc.pdf" } }`.

### Inline media

Use the same `type` as above. Chat Completions and Responses images: `data:<mime>;base64,...` in the URL field. Chat Completions `file`: the same form in `file.file_id`. Responses files: `file_data`. Messages: `source.type` `base64` with `media_type` and `data`. Put the data URL on one line; Base64 increases JSON size by about 4/3.

## Session Header

For multi-turn session affinity, send:

| Header              | Rules                                         |
| ------------------- | --------------------------------------------- |
| `X-Mdlx-Session-Id` | Length 8–128; alphanumeric, `-`, and `_` only |

Some native tools send their own session header (for example Claude Code’s `X-Claude-Code-Session-Id`). If both are present, `X-Mdlx-Session-Id` takes precedence.

```bash theme={null}
curl -sS "https://llm.modellix.ai/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Mdlx-Session-Id: my-conversation-001" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "messages": [{"role": "user", "content": "Continue our previous topic"}]
  }'
```

## End-User ID Header

Optional. Tag requests with your own end-user identifier so you can filter [request logs](#request-logs) later. Invalid values return `400`.

| Header           | Rules                                                            |
| ---------------- | ---------------------------------------------------------------- |
| `X-Mdlx-User-Id` | Optional; length 8–128; ASCII letters, digits, `-`, and `_` only |

```bash theme={null}
curl -sS "https://llm.modellix.ai/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Mdlx-Session-Id: my-conversation-001" \
  -H "X-Mdlx-User-Id: end_user_01" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "messages": [{"role": "user", "content": "Continue our previous topic"}]
  }'
```

<h2 id="list-models">
  List Models
</h2>

```http theme={null}
GET /v1/models
Authorization: Bearer <API_KEY>
```

Returns an OpenAI-compatible model list for the gateway (`object: list`, `data[].id` in `provider/name` form). IDs are de-duplicated. This endpoint uses the **query** rate limit (shared with request-log listing and similar read APIs)—not the inference RPM quota.

```bash theme={null}
curl -sS "https://llm.modellix.ai/v1/models" \
  -H "Authorization: Bearer ${API_KEY}"
```

Example response:

```json theme={null}
{
  "object": "list",
  "data": [
    { "id": "openai/gpt-5.5", "object": "model" },
    { "id": "openai/gpt-5.6-sol", "object": "model" }
  ]
}
```

<h2 id="request-logs">
  Request Logs
</h2>

```http theme={null}
GET /v1/logs
Authorization: Bearer <API_KEY>
```

Lists **your team’s** LLM request logs for a time window (same API Key / team scope as inference). Uses the **query** rate limit.

| Query          | Required | Description                                                     |
| -------------- | -------- | --------------------------------------------------------------- |
| `start_time`   | Yes      | UNIX seconds                                                    |
| `end_time`     | Yes      | UNIX seconds; must be greater than `start_time`; span ≤ 30 days |
| `mdlx_user_id` | No       | Exact match; same rules as `X-Mdlx-User-Id`                     |
| `page`         | No       | Default `1`                                                     |
| `page_size`    | No       | Default `10`, max `100`                                         |

Response shape (fields useful for debugging and auditing):

| Field                                                              | Description                             |
| ------------------------------------------------------------------ | --------------------------------------- |
| `requests`                                                         | Log items                               |
| `total` / `page` / `page_size`                                     | Pagination                              |
| `requests[].task_id`                                               | Request id                              |
| `requests[].status` / `error`                                      | Outcome                                 |
| `requests[].model`                                                 | `{ provider, model_name }`              |
| `requests[].prompt_tokens` / `completion_tokens` / `cached_tokens` | Token usage when available              |
| `requests[].cost`                                                  | Cost in the console’s billing unit      |
| `requests[].created_at`                                            | UNIX seconds                            |
| `requests[].input` / `result`                                      | Request/response payloads when retained |

The list response does **not** include a `mdlx_user_id` field; filter with the query parameter instead.

```bash theme={null}
curl -sS "https://llm.modellix.ai/v1/logs?start_time=1700000000&end_time=1700086400&page=1&page_size=20" \
  -H "Authorization: Bearer ${API_KEY}"
```

For **media** (image/video/speech) request logs on `https://api.modellix.ai`, see [List media request logs](/api/get-logs).

## Success Responses

* **Non-streaming:** HTTP `200` with a JSON body matching the protocol (chat.completion, response, or message).
* **Streaming:** HTTP `200`, `Content-Type: text/event-stream`, protocol-specific SSE events.

Responses usually include `usage` (often on the final stream event). Billing uses token usage; see [Billing](#billing).

## Errors

```json theme={null}
{
  "error": {
    "message": "...",
    "type": "invalid_request_error"
  }
}
```

Optional fields may include `code` and `param`.

| HTTP  | Meaning                                         | Common `error.type`                                     |
| ----- | ----------------------------------------------- | ------------------------------------------------------- |
| `400` | Invalid parameters                              | `invalid_request_error`                                 |
| `401` | Missing/invalid key or conflicting auth headers | `invalid_request_error`                                 |
| `402` | Insufficient balance                            | `insufficient_quota`                                    |
| `404` | Unknown path or model unavailable               | `invalid_request_error`                                 |
| `429` | Rate limit or model temporarily unavailable     | `rate_limit_exceeded` / `request_limited` / `api_error` |
| `5xx` | Temporary upstream or service error             | `api_error`                                             |

## Billing

Successful responses are billed from token `usage` at the model’s input and output rates (plus cache read/write when present). `prompt_tokens_details.video_tokens` and `audio_tokens` are included in `prompt_tokens` and are not billed separately. Unit prices and the invoice follow the console. Insufficient balance returns `402` with `insufficient_quota`.

## Rate Limits

| Case                          | HTTP  | Common `error.type`   | Notes                                                                                                             |
| ----------------------------- | ----- | --------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Inference RPM exceeded        | `429` | `rate_limit_exceeded` | Chat / Responses / Messages; may include `X-RateLimit-Limit` / `Remaining` / `Reset`                              |
| Query RPM exceeded            | `429` | `rate_limit_exceeded` | `GET /v1/models`, `GET /v1/logs` (and similar listing APIs); separate from inference RPM; same rate-limit headers |
| Other request limits          | `429` | `request_limited`     | Slow down or retry later                                                                                          |
| Model temporarily unavailable | `429` | `api_error`           | May include `Retry-After`; switch model or retry                                                                  |

Back off and reduce request rate after `429`.

## Client Quick Reference

| Client                                                                          | Base URL                             | Credential env                                | Model prefix       |
| ------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------- | ------------------ |
| [OpenAI SDK](/llm/sdk/openai-sdk)                                               | `https://llm.modellix.ai/v1`         | `OPENAI_API_KEY`                              | `openai/...`       |
| [Codex](/llm/agent/codex)                                                       | `openai_base_url` = `.../v1`         | `OPENAI_API_KEY`                              | `openai/...`       |
| [Cursor](/llm/ide/cursor)                                                       | `https://llm.modellix.ai/v1`         | Modellix API Key in settings                  | `provider/name`    |
| [Anthropic SDK](/llm/sdk/anthropic-sdk) / [Claude Code](/llm/agent/claude-code) | `https://llm.modellix.ai` (no `/v1`) | `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` | `anthropic/...`    |
| [OpenCode](/llm/agent/opencode)                                                 | Provider `baseURL`                   | `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`        | Match the protocol |

Google models (`google/...`) on the OpenAI-compatible path use `OPENAI_*` and the `/v1` base URL.

## Differences from Vendor Docs

| Topic             | Modellix                                                                        |
| ----------------- | ------------------------------------------------------------------------------- |
| Auth              | Bearer or `x-api-key` with a Modellix key                                       |
| `model`           | `provider/name` form — see [Models & Pricing](/llm/overview#models-and-pricing) |
| Chat vs Responses | Different bodies—changing only the URL is not enough                            |
| Multimodal        | Fields follow the protocol you call—see [Multimodal Inputs](#multimodal-inputs) |
| Session           | Optional `X-Mdlx-Session-Id`                                                    |
| End-user id       | Optional `X-Mdlx-User-Id` for log filtering                                     |
| Model list        | `GET /v1/models` (OpenAI-compatible)                                            |
| Request logs      | `GET /v1/logs` (team-scoped; optional `mdlx_user_id`)                           |

Official field catalogs: [OpenAI Chat Completions](https://platform.openai.com/docs/api-reference/chat), [OpenAI Responses](https://platform.openai.com/docs/api-reference/responses), [Anthropic Messages](https://docs.anthropic.com/en/api/messages).