> ## 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, auth, 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                   |

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).

<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.

## 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 (Responses also fine)                                   |

## 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).

## 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).

## 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).

## 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"}]
  }'
```

## 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`. Unit prices and final charges follow the console and account invoice. Insufficient balance returns `402` with `insufficient_quota`.

## Rate limits

| Case                          | HTTP  | Common `error.type`   | Notes                                                   |
| ----------------------------- | ----- | --------------------- | ------------------------------------------------------- |
| RPM exceeded                  | `429` | `rate_limit_exceeded` | May include `X-RateLimit-Limit` / `Remaining` / `Reset` |
| 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/openai-sdk)                                         | `https://llm.modellix.ai/v1`         | `OPENAI_API_KEY`                              | `openai/...`       |
| [Codex](/llm/codex)                                                   | `openai_base_url` = `.../v1`         | `OPENAI_API_KEY`                              | `openai/...`       |
| [Cursor](/llm/cursor)                                                 | `https://llm.modellix.ai/v1`         | Modellix API Key in settings                  | `provider/name`    |
| [Anthropic SDK](/llm/anthropic-sdk) / [Claude Code](/llm/claude-code) | `https://llm.modellix.ai` (no `/v1`) | `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` | `anthropic/...`    |
| [OpenCode](/llm/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                            |
| Session           | Optional `X-Mdlx-Session-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).