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：

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 直接接入）：

Authorization: Bearer mdlx-xxxxxxxx

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

请求

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 约定，具体以所选模型能力为准。

示例

# 非流式
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

请求

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 约定。

示例

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）

请求

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 原生客户端常自动附带，本服务会转发上游）。

示例

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，以后者为准。

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（流式时多在终包中）。计费说明见计费。

错误响应

错误体一般为：

{
  "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 兼容客户端

export OPENAI_API_KEY="mdlx-xxxxxxxx"
export OPENAI_BASE_URL="https://llm.modellix.ai/v1"

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

Codex CLI

export OPENAI_API_KEY="mdlx-xxxxxxxx"

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

model = "openai/gpt-5.5"
openai_base_url = "https://llm.modellix.ai/v1"

Anthropic SDK / Claude Code

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 持久化：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm.modellix.ai",
    "ANTHROPIC_API_KEY": "mdlx-xxxxxxxx"
  }
}

OpenCode

环境变量：

export OPENAI_API_KEY="mdlx-xxxxxxxx"
# 若走 Anthropic 协议，也可：
# export ANTHROPIC_API_KEY="mdlx-xxxxxxxx"

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

{
  "$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
Responses	OpenAI Responses
Messages	Anthropic Messages

请按本文与对应官方协议字段调用。机器可读规范见同目录 openapi.json（OpenAPI 3.1，英文描述，仅列核心字段）。

Getting Started

Ways to Use

LLM

Llm raw

LLM API

概览

认证

模型

协议选择

Chat Completions

请求

示例

Responses

请求

示例

Messages（Anthropic）

请求

示例

会话头（可选）

成功响应

错误响应

计费

限流

客户端接入提示

OpenAI SDK / 通用 OpenAI 兼容客户端

Codex CLI

Anthropic SDK / Claude Code

OpenCode

对照速查

附录：与官方文档的差异

​LLM API

​概览

​认证

​模型

​协议选择

​Chat Completions

​请求

​示例

​Responses

​请求

​示例

​Messages（Anthropic）

​请求

​示例

​会话头（可选）

​成功响应

​错误响应

​计费

​限流

​客户端接入提示

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

​Codex CLI

​Anthropic SDK / Claude Code

​OpenCode

​对照速查

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

LLM API

概览

认证

模型

协议选择

Chat Completions

请求

示例

Responses

请求

示例

Messages（Anthropic）

请求

示例

会话头（可选）

成功响应

错误响应

计费

限流

客户端接入提示

OpenAI SDK / 通用 OpenAI 兼容客户端

Codex CLI

Anthropic SDK / Claude Code

OpenCode

对照速查

附录：与官方文档的差异