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

# Llm raw

# LLM API

Modellix LLM 文本接口：提供 OpenAI 兼容的 **Chat Completions**、**Responses**，以及 Anthropic 兼容的 **Messages**。调用为同步请求（支持流式 SSE）；参数与响应格式分别遵循对应官方协议（差异见文末说明）。

> **最后更新**: 2026-08-04

***

## 概览

| 项        | 说明                                                         |
| -------- | ---------------------------------------------------------- |
| Base URL | `https://llm.modellix.ai`                                  |
| 路径前缀     | `/v1`                                                      |
| 调用方式     | 同步（支持流式 SSE）                                               |
| 鉴权       | `Authorization: Bearer` 或 `x-api-key`（同一 Modellix API Key） |
| 模型字段     | 请求体 `model`（如 `openai/gpt-5.6-sol`）                        |

| 协议               | 方法     | 路径                     | 典型用途                         |
| ---------------- | ------ | ---------------------- | ---------------------------- |
| Chat Completions | `POST` | `/v1/chat/completions` | OpenAI SDK、多数 Chat 客户端、Codex |
| Responses        | `POST` | `/v1/responses`        | OpenAI Responses             |
| Messages         | `POST` | `/v1/messages`         | Anthropic 兼容客户端、Claude Code  |

示例完整 URL：

```text theme={null}
https://llm.modellix.ai/v1/chat/completions
https://llm.modellix.ai/v1/responses
https://llm.modellix.ai/v1/messages
```

***

## 认证

所有业务请求须携带 Modellix API Key，以下两种方式等价（便于 OpenAI / Anthropic 原生 SDK 直接接入）：

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

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

| 方式                      | 典型客户端                       |
| ----------------------- | --------------------------- |
| `Authorization: Bearer` | OpenAI SDK、Codex、OpenCode 等 |
| `x-api-key`             | Anthropic SDK、Claude Code 等 |

二者同时出现时须为同一 Key；冲突则鉴权失败。Key 不是各厂商官方 Key。失败时返回 [错误响应](#错误响应)。

***

## 模型

在请求 JSON 中传 `model`，格式为 `provider/name`，例如：

| model                        | 说明          |
| ---------------------------- | ----------- |
| `openai/gpt-5.6-sol`         | OpenAI 系    |
| `openai/gpt-5.6-terra`       | OpenAI 系    |
| `openai/gpt-5.6-luna`        | OpenAI 系    |
| `openai/gpt-5.5`             | OpenAI 系    |
| `anthropic/claude-fable-5`   | Anthropic 系 |
| `anthropic/claude-sonnet-5`  | Anthropic 系 |
| `anthropic/claude-opus-5`    | Anthropic 系 |
| `anthropic/claude-haiku-4.5` | Anthropic 系 |
| `google/gemini-3.1-pro`      | Google 系    |
| `google/gemini-3.5-flash`    | Google 系    |
| `google/gemini-3.6-flash`    | Google 系    |

可用模型以控制台 / 产品发布为准。

***

## 协议选择

三套接口的 **URL 与请求体结构均不同**，请按所用协议传参，不要混用字段：

|      | Chat Completions                       | Responses            | Messages                           |
| ---- | -------------------------------------- | -------------------- | ---------------------------------- |
| 输入   | `messages: [{role, content}, ...]`     | `input`（字符串或内容数组）    | Anthropic `messages` + 可选 `system` |
| 长度字段 | `max_tokens` / `max_completion_tokens` | `max_output_tokens`  | `max_tokens`                       |
| 流式   | `stream: true` → SSE                   | `stream: true` → SSE | `stream: true` → SSE               |

**建议：**

| 模型前缀            | 推荐协议                                        |
| --------------- | ------------------------------------------- |
| `openai/...`    | Chat Completions 或 Responses                |
| `anthropic/...` | Messages（Anthropic 客户端）；也可 Chat Completions |
| `google/...`    | Chat Completions（也可 Responses）              |

按客户端选路径时：

* OpenAI Chat / 多数第三方工具 → `/v1/chat/completions`
* OpenAI Responses → `/v1/responses`
* Anthropic 兼容客户端 → `/v1/messages`，模型选 `anthropic/...`

***

## Chat Completions

### 请求

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

| 字段                      | 必填 | 类型      | 说明                        |
| ----------------------- | -- | ------- | ------------------------- |
| `model`                 | 是  | string  | 模型 ID                     |
| `messages`              | 是  | array   | OpenAI messages           |
| `stream`                | 否  | boolean | 默认 `false`；`true` 时返回 SSE |
| `max_tokens`            | 否  | integer | 生成上限（视模型而定）               |
| `max_completion_tokens` | 否  | integer | 生成上限（部分新模型优先用此字段）         |
| `temperature`           | 否  | number  | 采样温度                      |
| `n`                     | 否  | integer | 生成条数                      |

其他字段遵循 OpenAI Chat Completions 约定，具体以所选模型能力为准。

### 示例

```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": "用一句话介绍你自己"}]
  }'

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

***

## Responses

### 请求

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

| 字段                  | 必填 | 类型             | 说明         |
| ------------------- | -- | -------------- | ---------- |
| `model`             | 是  | string         | 模型 ID      |
| `input`             | 是  | string / array | 用户输入       |
| `stream`            | 否  | boolean        | 默认 `false` |
| `max_output_tokens` | 否  | integer        | 输出上限       |
| `temperature`       | 否  | number         | 采样温度       |

其他字段遵循 OpenAI Responses 约定。

### 示例

```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": "用一句话介绍你自己"
  }'
```

***

## Messages（Anthropic）

### 请求

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

| 字段           | 必填 | 类型             | 说明                                  |
| ------------ | -- | -------------- | ----------------------------------- |
| `model`      | 是  | string         | 模型 ID，如 `anthropic/claude-sonnet-5` |
| `messages`   | 是  | array          | Anthropic messages                  |
| `max_tokens` | 是  | integer        | 输出上限                                |
| `stream`     | 否  | boolean        | 默认 `false`                          |
| `system`     | 否  | string / array | 系统提示                                |

其他字段遵循 Anthropic Messages 约定。鉴权可用 `Authorization: Bearer` 或 Anthropic 习惯的 `x-api-key`（均为 Modellix API Key）。

可选请求头：`anthropic-version`（如 `2023-06-01`；Anthropic 原生客户端常自动附带，本服务会转发上游）。

### 示例

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

***

## 会话头（可选）

多轮对话需要会话亲和时，可传：

| Header              | 说明                         |
| ------------------- | -------------------------- |
| `X-Mdlx-Session-Id` | 长度 8–128，仅字母数字 / `-` / `_` |

部分原生工具自带的会话头（如 Claude Code 的 `X-Claude-Code-Session-Id`）亦可使用；若同时传 `X-Mdlx-Session-Id`，以后者为准。

```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": "继续上次的话题"}]
  }'
```

***

## 成功响应

* **非流式**：HTTP `200`，JSON 体遵循对应官方协议（Chat / Responses / Messages）。
* **流式**：HTTP `200`，`Content-Type: text/event-stream`，按协议返回 SSE 事件。

响应中通常包含 `usage`（流式时多在终包中）。计费说明见 [计费](#计费)。

***

## 错误响应

错误体一般为：

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

部分错误还会包含 `code`、`param` 等字段。

| HTTP  | 常见含义                       | 常见 `error.type`                                         |
| ----- | -------------------------- | ------------------------------------------------------- |
| `400` | 参数非法                       | `invalid_request_error`                                 |
| `401` | API Key 缺失、无效，或鉴权头冲突       | `invalid_request_error`                                 |
| `402` | 余额不足                       | `insufficient_quota`                                    |
| `404` | 路径不存在，或所选模型当前不可用           | `invalid_request_error`                                 |
| `429` | 限流，或所选模型暂时不可用（见 [限流](#限流)） | `rate_limit_exceeded` / `request_limited` / `api_error` |
| `5xx` | 服务暂时不可用，可稍后重试              | `api_error` 等                                           |

***

## 计费

按成功响应中的 token `usage` 计费；单价与模型以控制台 / 账单为准。最终扣费以账户账单为准。

余额不足时返回 `402`，`error.type` 为 `insufficient_quota`。

***

## 限流

| 情况                 | HTTP  | `error.type`（常见）      | 说明                                                                      |
| ------------------ | ----- | --------------------- | ----------------------------------------------------------------------- |
| 每分钟请求数（RPM）超限      | `429` | `rate_limit_exceeded` | 可能带 `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` |
| 其他请求限制（如免费额度相关）    | `429` | `request_limited`     | 降低频率或稍后再试                                                               |
| 所选模型暂时不可用（上游部署冷却等） | `429` | `api_error`           | 文案类似 *temporarily unavailable*；可能带 `Retry-After`，可换模型或稍后重试              |

收到 `429` 后请降低频率并退避重试。

***

## 客户端接入提示

将下方 `mdlx-xxxxxxxx` 换成控制台签发的 Modellix API Key。Key 不是各厂商官方 Key。

### OpenAI SDK / 通用 OpenAI 兼容客户端

```bash theme={null}
export OPENAI_API_KEY="mdlx-xxxxxxxx"
export OPENAI_BASE_URL="https://llm.modellix.ai/v1"
```

随后按 SDK 惯例调用即可；请求体里的 `model` 使用 `openai/...`（如 `openai/gpt-5.5`）。

### Codex CLI

```bash theme={null}
export OPENAI_API_KEY="mdlx-xxxxxxxx"
```

在 `~/.codex/config.toml` 中指定 Base URL 与模型（推荐；`OPENAI_BASE_URL` 环境变量在较新 Codex 中已弃用）：

```toml theme={null}
model = "openai/gpt-5.5"
openai_base_url = "https://llm.modellix.ai/v1"
```

### Anthropic SDK / Claude Code

```bash theme={null}
export ANTHROPIC_API_KEY="mdlx-xxxxxxxx"
export ANTHROPIC_BASE_URL="https://llm.modellix.ai"
```

说明：

* Base URL **不要**带 `/v1`（SDK 会自行拼接 `/v1/messages`）。
* `ANTHROPIC_API_KEY` 会以 `x-api-key` 发送，本接口已支持。
* 若工具要求 Bearer，可改用 `ANTHROPIC_AUTH_TOKEN`（与 `ANTHROPIC_API_KEY` 二选一，勿同时设成不同值）。
* 模型使用 `anthropic/...`（如 `anthropic/claude-sonnet-5`）。

也可写入 `~/.claude/settings.json` 持久化：

```json theme={null}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm.modellix.ai",
    "ANTHROPIC_API_KEY": "mdlx-xxxxxxxx"
  }
}
```

### OpenCode

环境变量：

```bash theme={null}
export OPENAI_API_KEY="mdlx-xxxxxxxx"
# 若走 Anthropic 协议，也可：
# export ANTHROPIC_API_KEY="mdlx-xxxxxxxx"
```

在 `opencode.json`（或 `~/.config/opencode/opencode.json`）中把对应 provider 指到 Modellix，例如 OpenAI 兼容：

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/gpt-5.5",
  "provider": {
    "openai": {
      "options": {
        "baseURL": "https://llm.modellix.ai/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}
```

Anthropic 兼容时将 `baseURL` 设为 `https://llm.modellix.ai`，并用 `ANTHROPIC_API_KEY`。

### 对照速查

| 工具                          | Base URL                                        | 凭据环境变量                                       | 模型前缀            |
| --------------------------- | ----------------------------------------------- | -------------------------------------------- | --------------- |
| OpenAI SDK                  | `https://llm.modellix.ai/v1`                    | `OPENAI_API_KEY`                             | `openai/...`    |
| Codex                       | `https://llm.modellix.ai/v1`（`openai_base_url`） | `OPENAI_API_KEY`                             | `openai/...`    |
| Anthropic SDK / Claude Code | `https://llm.modellix.ai`（无 `/v1`）              | `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` | `anthropic/...` |
| OpenCode                    | 见上方 `provider.options.baseURL`                  | `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`       | 与所用协议一致         |
| 通用 OpenAI 兼容 SaaS           | `https://llm.modellix.ai` 或带 `/v1`（按表单说明）       | 填 Modellix API Key                           | 按产品要求           |

Google 系模型（`google/...`）走 OpenAI 兼容路径时，同样使用 `OPENAI_*` 环境变量与 `/v1` Base URL。

***

## 附录：与官方文档的差异

| 项                 | 本接口                                                      | 说明                |
| ----------------- | -------------------------------------------------------- | ----------------- |
| 鉴权                | `Authorization: Bearer` 或 `x-api-key` + Modellix API Key | 不是各厂商官方 Key；两种头等价 |
| `model`           | `provider/name` 形式                                       | 与官方裸模型名可能不同       |
| Chat vs Responses | 协议与字段不同                                                  | 仅换 URL 不够，须换请求体   |
| 会话头               | `X-Mdlx-Session-Id`                                      | 可选                |

完整请求/响应字段以官方协议为准（本接口仅列常用字段）：

| 协议               | 官方文档                                                                           |
| ---------------- | ------------------------------------------------------------------------------ |
| Chat Completions | [OpenAI Chat Completions](https://platform.openai.com/docs/api-reference/chat) |
| Responses        | [OpenAI Responses](https://platform.openai.com/docs/api-reference/responses)   |
| Messages         | [Anthropic Messages](https://docs.anthropic.com/en/api/messages)               |

请按本文与对应官方协议字段调用。

机器可读规范见同目录 [openapi.json](openapi.json)（OpenAPI 3.1，英文描述，仅列核心字段）。