MuxLLM
开始使用

API Reference

API 调用参考

从模型广场复制精确模型名，并按端点标签选择请求路径。示例只演示稳定的基础字段；模型专属参数请以实时模型信息和实际响应为准。

选择端点 查看模型广场

Authentication

按协议发送 API Key

API Key 应保存在服务端环境变量或受控的密钥管理系统中。下面的值仅为占位符，不要把真实凭证写入公开代码、日志或截图。

协议请求头示例
OpenAI 兼容AuthorizationBearer YOUR_API_KEY
Claude 原生x-api-keyYOUR_API_KEY
Gemini 原生x-goog-api-keyYOUR_API_KEY
不要混用认证成功只表示凭证被识别；模型、分组和端点仍需要同时匹配。更换协议时应一起更换 Base URL、路径、认证头和请求体。

Endpoint Map

从端点标签确定请求路径

模型标签方法与路径请求体核心字段响应形态
openaiPOST /v1/chat/completionsmodel、messageschoices
openai-responsePOST /v1/responsesmodel、inputResponse 对象
anthropicPOST /v1/messagesmodel、max_tokens、messagesMessage 对象
geminiPOST /v1beta/models/{model}:generateContentcontentscandidates

不要根据模型厂商品牌猜测协议。例如 Claude 或 Gemini 模型也可能提供 OpenAI 兼容入口；最终以模型广场显示的端点标签为准。

OpenAI Compatible

Chat Completions

适用于显示 openai 标签的模型。Base URL 通常填写到 /v1，请求路径为 /chat/completions。

cURL 最小请求
POST /v1/chat/completions
curl https://api.muxllm.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [
      { "role": "system", "content": "你是一个简洁的技术助手。" },
      { "role": "user", "content": "用三句话说明统一模型 API 的作用。" }
    ]
  }'
流式输出

在目标模型支持流式响应时加入 "stream": true。客户端应逐行消费 SSE，并处理结束标记和中途断线。

Chat Completions · stream
curl -N https://api.muxllm.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [{ "role": "user", "content": "分步骤解释这个概念。" }],
    "stream": true
  }'

Responses API

Responses 请求

仅用于显示 openai-response 标签的模型。它与 Chat Completions 的请求结构不同，不能只替换路径。

文本输入示例
POST /v1/responses
curl https://api.muxllm.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "input": "列出排查 API 401 错误的三个步骤。"
  }'
CodexCodex 自定义模型供应商使用 Responses 协议。对应模型必须支持 openai-response，完整配置见客户端教程。

Anthropic Native

Claude Messages API

适用于显示 anthropic 标签的模型。原生根地址不额外添加 /v1，请求时再使用完整路径 /v1/messages。

认证x-api-key: YOUR_API_KEY
版本头anthropic-version: 2023-06-01
输出上限请求体需要提供 max_tokens，具体上限取决于模型。
Messages API 示例
POST /v1/messages
curl https://api.muxllm.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "解释 Messages API 的基本请求结构。" }
    ]
  }'

Gemini Native

Gemini generateContent

适用于显示 gemini 标签的模型。模型名位于 URL 路径中，请保持模型广场中的精确拼写。

generateContent 示例
POST /v1beta/models/{model}:generateContent
curl https://api.muxllm.com/v1beta/models/MODEL_NAME:generateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "概括这次请求的内容。" }]
      }
    ]
  }'
密钥位置优先通过 x-goog-api-key 请求头发送 API Key，避免把凭证放进可能被访问日志记录的 URL 查询参数。

Vision

视觉输入

只有目标模型支持视觉输入时，图片内容才会被处理。远程图片 URL 必须可由上游访问；Base64 数据会显著增加请求体积。

OpenAI 兼容视觉消息
image_url 内容块
curl https://api.muxllm.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text", "text": "描述图片中的主要内容。" },
        { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } }
      ]
    }]
  }'
Gemini 原生图片内容
inline_data 内容块
{
  "contents": [{
    "role": "user",
    "parts": [
      { "text": "描述图片中的主要内容。" },
      {
        "inline_data": {
          "mime_type": "image/jpeg",
          "data": "BASE64_IMAGE_DATA"
        }
      }
    ]
  }]
}

Tools

函数调用

工具调用需要目标模型与端点同时支持。模型只负责提出结构化调用，业务代码仍需校验参数、执行函数，并把结果作为后续消息返回。

  1. 01声明工具

    提供名称、用途和 JSON Schema 参数。

  2. 02请求模型

    发送用户消息与 tools 定义。

  3. 03执行并校验

    解析调用参数，在服务端验证后执行。

  4. 04回传结果

    把工具结果加入会话，再请求最终答复。

OpenAI 兼容工具定义
tools 字段
{
  "model": "MODEL_NAME",
  "messages": [{ "role": "user", "content": "查询上海当前天气。" }],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询指定城市的天气",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  }]
}
安全边界不要直接执行模型生成的参数。必须在服务端做类型、权限和取值范围校验，涉及支付、删除或外部消息的操作还应增加人工确认。

SDK

使用兼容 SDK

只修改 API Key、Base URL 和模型名即可接入常见 SDK。以下示例把凭证写成占位符，正式项目应改为读取服务端环境变量。

OpenAI Python SDK
Python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.muxllm.com/v1",
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)
Anthropic Python SDK
Python
from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.muxllm.com",
)

message = client.messages.create(
    model="MODEL_NAME",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(message.content[0].text)

SDK 可能在升级后调整参数名。若客户端生成了错误路径，先打印最终请求 URL，并对照本页端点地图确认是否重复拼接版本路径。

Error Handling

错误处理与重试

类型是否直接重试处理建议
400 / 404否修正请求体、模型名、Base URL 或路径后再发送
401 / 403否核对凭证、认证头、账户和分组权限
429有限重试先检查余额和额度，再使用指数退避并降低并发
5xx / 网络中断有限重试仅对幂等或可安全重放的请求重试，并设置次数上限
媒体请求图片和视频生成可能产生费用。网络超时不代表任务一定未创建；重复提交前应先确认平台日志或任务状态，避免重复计费。

Next Step

把配置交给常用客户端

API 最小请求通过后，再按客户端要求填写同一套协议字段。

查看客户端配置