MiniMax

MiniMax 通过其平台 API 提供托管生成式模型。应用通过稳定的 AISIX 别名调用 MiniMax，同时网关确保上游凭证不会出现在客户端代码中。

前提条件

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 从 MiniMax 平台获取的 MiniMax API Key。
• curl 和 jq。

设置正确的基础 URL

MiniMax 为相同的模型提供两个上游接口：

接口	根地址	请求格式
OpenAI SDK	https://api.minimax.io/v1	OpenAI chat completions
Anthropic SDK	https://api.minimax.io/anthropic	Anthropic Messages

minimax 的社区目录条目发布的地址是 https://api.minimax.io/anthropic/v1，这是兼容 Anthropic 的接口，并明确包含原本由 Anthropic SDK 追加的版本路径；但目录默认分配的是 openai 适配器。两者并不匹配。如果省略 api_base，AISIX 会接受模型服务提供方密钥并填入该目录值，随后向期望 Anthropic Messages 格式的端点发送 OpenAI chat-completions 格式的请求，导致通过该别名的所有调用在上游失败。

警告

在 minimax 模型服务提供方密钥上始终将 api_base 设置为 https://api.minimax.io/v1。网关会将 /chat/completions 等端点路径追加到所配置的根地址，因此该根地址必须是 MiniMax 兼容 OpenAI 的 /chat/completions 所在的根地址。

下文配置的模型服务提供方密钥使用 api_base 处理 Chat Completions，并为 Messages 和 Count Tokens 单独声明 Base。参见使用兼容 Anthropic 的接口。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为以 MiniMax 为后端的 Chat Completions、Messages 和 Count Tokens 创建模型服务提供方密钥、模型别名和调用方 API Key。

MiniMax 是一个社区目录模型服务提供方。AISIX 通过 openai 适配器连接，并使用 Bearer Token 对上游请求进行认证。由于目录发布的基础 URL 不是适配器所需的根地址，你还必须显式设置 api_base。请参阅设置正确的基础 URL。

创建模型服务提供方密钥

创建用于存储 MiniMax 凭证和 API 根地址的模型服务提供方密钥：

# 请替换为实际值
export MINIMAX_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "minimax-prod",
    "provider": "minimax",
    "api_key": "'"${MINIMAX_API_KEY}"'",
    "api_base": "https://api.minimax.io/v1",
    "apis": {
      "messages": { "base": "https://api.minimax.io/anthropic" }
    },
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为 minimax。由于 minimax 是 models.dev 目录条目，AISIX Cloud Admin API 会接受该值，并从目录推导出适配器；adapter 字段仅适用于 BYO 模型服务提供方密钥。

❷ api_key 存储 MiniMax API Key。MiniMax 使用 HTTP Bearer 认证其兼容 OpenAI 的接口，这也正是 openai 适配器发送的认证方式。该值遵循模型服务提供方密钥中的凭证处理行为。

❸ api_base 为 https://api.minimax.io/v1，即 MiniMax 为 OpenAI 客户端库记录的 base_url。这是本页最重要的字段。省略它不会导致创建调用失败，因为目录发布了默认值；但会导致后续每个聊天请求失败，因为该默认值指向兼容 Anthropic 的根地址。

❹ apis.messages 在同级 Base 上声明 MiniMax 的 Anthropic 兼容 Messages 和 Count Tokens 路由。MiniMax-M3 是本指南使用的模型，其 Count Tokens 已有文档说明。

仅供 MiniMax-M3 别名使用的服务提供方密钥应保留此声明。对于其他代次的模型，请使用不带 apis.messages 的单独服务提供方密钥，除非 MiniMax 已提供该模型支持 Count Tokens 的文档。

该命令将返回的模型服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

MiniMax 模型 ID 区分大小写，且不包含供应商前缀。其模式为 MiniMax-<generation>：供应商名称两部分的首字母 M 均为大写，后接可含小数的代次编号；某一代次的低延迟变体还可能带有 -highspeed 后缀。请勿转换为小写，也不要添加来自聚合服务的 minimax/ 前缀。

当前模型 ID 包括：

模型 ID	说明
MiniMax-M3	最新代次。在兼容 OpenAI 的 chat-completions 路由上接受文本、图像和视频输入。
MiniMax-M2.7	上一代旗舰模型，仅接受文本输入。
MiniMax-M2.7-highspeed	同一代次的低延迟变体。

MiniMax-M2.5、MiniMax-M2.5-highspeed、MiniMax-M2.1 和 MiniMax-M2 ID 作为早期代次仍保留在目录中。创建别名前，请查看 MiniMax 模型文档了解当前列表。

创建调用方将在请求中发送的模型别名：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "minimax-m3-prod",
    "model_name": "MiniMax-M3",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是 MiniMax 发布的确切模型 ID，例如 MiniMax-M3。

❸ provider_key_id 将别名关联到 MiniMax 模型服务提供方密钥。

如需了解模型成本元数据和 AISIX Cloud 定价，请参阅模型别名。

创建调用方 API Key

创建可访问该模型别名的调用方 API Key。明文密钥由服务器生成，并仅在创建响应中返回一次，因此请立即保存：

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "minimax-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 的值必须引用上一步保存的模型 ID。写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送到网关的调用方 API Key：

export MINIMAX_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "minimax-prod"
    provider: "minimax"
    adapter: "openai"
    api_key: ${MINIMAX_API_KEY}
    api_base: "https://api.minimax.io/v1"
    apis:
      messages:
        base: "https://api.minimax.io/anthropic"

models:
  - display_name: "minimax-m3-prod"
    provider: "minimax"
    model_name: "MiniMax-M3"
    provider_key: "minimax-prod"

api_keys:
  - display_name: "minimax-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "minimax-m3-prod"

如果 AISIX 安装在本地，请在加载前验证该文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中设置所引用的环境变量并启动网关。仅当这些变量已在进程中可用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两个命令中使用 -e 传入它引用的每个环境变量。资源加载后，为下方的通用验证请求做好准备：

export AISIX_API_KEY="$CALLER_API_KEY"

验证模型服务提供方连接

导出 AISIX 网关源地址：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 chat-completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m3-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from MiniMax."
      }
    ]
  }'

网关返回兼容 OpenAI 的响应，其中会回显面向调用方的别名 minimax-m3-prod。

使用同一别名验证 MiniMax-M3 Count Tokens 路由：

curl -sS -X POST "$AISIX_PROXY/v1/messages/count_tokens" \
  -H "x-api-key: ${AISIX_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m3-prod",
    "messages": [
      {
        "role": "user",
        "content": "Count this MiniMax prompt."
      }
    ]
  }'

成功响应包含 input_tokens。如果 Chat Completions 正常而此请求失败，请检查 apis.messages.base 的值，并确认别名仍指向 MiniMax-M3。

如果 Chat Completions 请求失败，请按以下顺序检查：

1. 模型服务提供方密钥上的 api_base。上游返回 404，或上游错误提及非预期的请求字段，通常表示密钥仍指向 https://api.minimax.io/anthropic/v1，而不是 https://api.minimax.io/v1。
2. 如果上游返回认证错误，请检查模型服务提供方密钥上的 api_key。
3. 检查 model_name 的拼写和大小写。MiniMax 模型 ID 区分大小写。

使用兼容 Anthropic 的接口

AISIX 可以把 Anthropic 形态请求转换为 MiniMax Chat Completions，但该桥接无法保留 MiniMax 完整的 Anthropic 兼容协议。本指南中的模型服务提供方密钥因此在同一凭证和别名上声明原生 Messages 协议面。原生与转换行为参见 Anthropic Messages API。

该声明会把 /v1/messages 和 /v1/messages/count_tokens 发送到 https://api.minimax.io/anthropic，而 Chat Completions 继续使用 api_base。MiniMax-M3 提供 Count Tokens 文档；不要由此推断平台列出的所有模型都支持该接口。

了解社区目录路径

特色模型服务提供方包含由 AISIX 维护的适配器、认证方案、默认基础 URL，以及上游所需的请求或响应重写规则。minimax 不包含这些设置。控制台将它归入社区目录，AISIX 仅代为做出三项决定：

• 适配器为 openai。
• 认证方案为 HTTP Bearer。
• 默认基础 URL 为 models.dev 为该模型服务提供方发布并缓存在 AISIX 模型服务提供方元数据中的值。

其他所有设置都需要由你提供。实际使用中，这意味着：

• 你需要负责基础 URL。 对于此模型服务提供方，发布的默认值与分配的适配器不匹配，因此应按照设置正确的基础 URL显式设置。仅当 models.dev 根本未发布模型服务提供方基础 URL 时，AISIX 才会以 400 错误拒绝创建调用；minimax 发布了默认值，因此请求会成功，而不匹配的问题会在之后暴露。
• 未注册任何请求或响应重写规则。 AISIX 将调用方的 Chat Completions 请求体转发给 MiniMax，不重命名任何参数，并从规范路径 delta.reasoning_content 规范化推理内容。它不会保留 MiniMax 独立的 reasoning_details 数组。请参阅配置请求和响应覆盖设置。
• AISIX 不会为你跟踪上游契约。 MiniMax 更改其传输格式时，目录条目不会随之更改。MiniMax API 更新后，请使用非生产别名验证一个代表性请求。

用量记录仍会将该模型服务提供方密钥标记为品牌为 minimax 的目录密钥，并标记为非特色，因此可在用量数据中区分社区目录流量。

这些差异并不意味着 minimax 是能力较弱的上游。它是受支持的目录模型服务提供方，与任何其他别名一样支持调用方密钥、允许列表、速率限制和用量核算。在 AISIX Cloud 中，匹配的预算同样生效。区别仅在于由谁负责传输契约。

配置请求和响应覆盖设置

由于 minimax 没有 AISIX 精选适配器映射，模型服务提供方密钥是记录 MiniMax 特定传输差异的唯一位置。除非配置 request.param_renames，否则 AISIX 会原样发送顶层请求字段。MiniMax-M3 当前同时接受 max_tokens 和 max_completion_tokens，因此本指南中的模型无需重命名。仅当所选模型要求不同字段名称时才添加重命名。

MiniMax-M3 的 reasoning_split 默认为 false，思考内容会保留在 content 的 <think> 标签中，AISIX 会保留该内容。如果将 reasoning_split 设置为 true，MiniMax 还会发出 reasoning_content 和 reasoning_details 数组。在 /v1/chat/completions 上，AISIX 会保留 reasoning_content，但丢弃 reasoning_details；Responses 桥接不会公开这两个字段。response.reasoning_field 覆盖设置也无法保留该数组。MiniMax 在包含工具的交错思考对话历史中要求完整数组，因此通过规范化 Chat 或 Responses 端点进行多轮工具循环时，请保持拆分推理关闭。应用依赖完整 Anthropic 思考和工具使用协议时，请使用兼容 Anthropic 的接口。

如果其他模型从非标准 delta 路径流式返回标量推理内容，请在模型服务提供方密钥上将 response.reasoning_field 设置为该路径。AISIX 会将其映射到调用方看到的 delta.reasoning_content。请针对配置的模型用流式请求验证任何覆盖设置。

覆盖设置会应用于引用该模型服务提供方密钥的每个模型，因此请先使用非生产别名进行测试。请参阅模型服务提供方特定的覆盖设置。

连接中国平台

MiniMax 在中国大陆运营独立平台，拥有自己的开发者控制台和主机名。它在目录中显示为独立的模型服务提供方 ID minimax-cn，且两个平台分别签发各自的 API Key，因此中国平台需要单独的模型服务提供方密钥。

同样需要修正基础 URL：目录默认值指向兼容 Anthropic 的根地址，而当前兼容 OpenAI 的根地址为 https://api.minimax.cn/v1。

{
  "display_name": "minimax-cn-prod",
  "provider": "minimax-cn",
  "api_key": "YOUR_MINIMAX_CN_API_KEY",
  "api_base": "https://api.minimax.cn/v1",
  "apis": {
    "messages": { "base": "https://api.minimax.cn/anthropic" }
  },
  "allowed_environments": ["YOUR_ENVIRONMENT_ID"]
}

目录为两个平台列出了相同的模型 ID，但不能保证特定代次的可用性相同。因此请根据中国平台文档验证，而不要假定两者完全一致。

此中国平台示例中的 apis.messages 也仅适用于 MiniMax-M3。除非 MiniMax 已提供其他代次支持 Count Tokens 的文档，否则供其使用的密钥应省略该声明。

端点覆盖范围

此别名使用 MiniMax 兼容 OpenAI 的文本和多模态 Chat 接口。MiniMax 还提供原生图片、视频、语音、音乐和文件 API，但其路径和请求体与 AISIX 规范化媒体及作业协议不匹配。

路由	MiniMax 别名的行为
/v1/chat/completions	支持，包括 stream: true。MiniMax-M3 可在此处接受图片和视频输入以进行多模态理解；该路由不会生成图片或视频。
/v1/responses	通过 Responses 桥接支持。AISIX 会将请求转换为 Chat Completions，而非调用 MiniMax /v1/responses 端点。没有 Chat 等价项的 OpenAI 特定 Responses 字段会被忽略。
/v1/messages 和 /v1/messages/count_tokens	由于本指南声明了 apis.messages，请求会发送到 MiniMax 的 Anthropic 兼容路由。MiniMax-M3 提供 Count Tokens 文档；其他代次的模型可能不支持。
/v1/embeddings	不要假定支持。AISIX 会将 OpenAI 格式的嵌入请求体原样转发到 {api_base}/embeddings，但 MiniMax 当前公开 API 文档未定义兼容 OpenAI 的嵌入协议或嵌入模型。请参阅嵌入。
/v1/images/generations	返回 400 错误而被拒绝。MiniMax 图片生成使用原生 /v1/image_generation 协议，可通过透传路由访问。
/v1/rerank	返回 400 错误而被拒绝。该路由仅接受 openai、cohere 和 jina 模型服务提供方值。
/v1/videos	返回 501 Not Implemented。MiniMax 视频生成使用原生 /v1/video_generation 协议，可通过透传路由访问。
/passthrough/minimax/*	通过已配置的透传路由可用于 /image_generation、/video_generation、/t2a_v2 和 /files/retrieve 等原生路由。AISIX 会转发原生请求体和响应而不进行转换。

本页的 /passthrough/minimax 路径假定一条透传路由认领该前缀，target_url 设为 MiniMax 的 API 根地址并挂上此服务提供方密钥；在调用方 Key 的 allowed_routes 上授予路由名称。一条路由只中继到一个固定目标，因此配置了多个 MiniMax 账号或基础 URL 时，请为每个账号另建一条路由。AISIX 不会重写原生请求体中的 model 值。它会检测 Chat、Completions 和 Responses 信封，并记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。

使用以本指南基础地址为目标的路由时，透传请求会基于 https://api.minimax.io/v1 解析。该根地址已以版本路径结尾，当透传路径的开头版本路径与其匹配时，网关会去除一个重复的版本路径。因此，/passthrough/minimax/v1/image_generation 和 /passthrough/minimax/image_generation 都会到达 https://api.minimax.io/v1/image_generation，而不是重复的 /v1/v1/ URL。

后续步骤

现在，你已将 AISIX 连接到 MiniMax 并验证了模型别名。接下来可阅读以下指南：

• 模型别名：为此别名配置路由、重试行为或成本元数据。
• 路由和故障转移：在 MiniMax 和第二个模型服务提供方之间配置故障转移。
• 模型服务提供方特定的覆盖设置：当上游 API 与其适配器不同时，调整请求和响应格式。
• 模型服务提供方兼容性：查看支持的代理端点和模型服务提供方特定的限制。