Moonshot AI（Kimi）

Moonshot AI 通过托管 API 提供 Kimi 模型系列。应用通过稳定的 AISIX 别名调用 Kimi，同时网关确保 Moonshot 凭证不会出现在客户端代码中。

前提条件

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

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

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 的基础 URL；应包含 /api，且末尾不要带斜杠
# 本地 On-Premises 快速入门使用 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"

为 Moonshot 支持的 chat-completions 路由创建模型服务提供方密钥、模型别名和调用方 API Key。

由于 Moonshot AI 提供兼容 OpenAI 的 API，AISIX 通过 openai 适配器连接，并使用创建凭证所在区域的 API 根地址。

创建模型服务提供方密钥

Moonshot AI 通过两个独立主机提供 API，目录将它们建模为两个不同的模型服务提供方 ID。请选择与创建 API Key 的控制台相匹配的组合：

模型服务提供方 ID	API 根地址	适用情况
`moonshotai`	`https://api.moonshot.ai/v1`	密钥在全球平台签发。
`moonshotai-cn`	`https://api.moonshot.cn/v1`	密钥在中国平台签发。

两个主机是具有独立控制台的不同部署，因此一个平台签发的密钥无法在另一个平台上认证。请选择与密钥匹配的模型服务提供方 ID，不要将一个 ID 指向另一个平台的主机：用量记录和成本报告会根据模型服务提供方 ID 归属流量。

对于新建服务提供方密钥，两个 ID 的 api_base 都是可选字段。AISIX Cloud Admin API 会为 moonshotai 填入全球根地址，为 moonshotai-cn 填入中国根地址。示例显式设置该字段，使目标平台保持可见。

在区域默认值修正前创建的旧 moonshotai 密钥可能仍固定到中国根地址。使用全球平台凭证更新此类配置时，请显式设置全球根地址。

以下示例使用 moonshotai。如果账户位于中国平台，请在所有位置分别替换为 moonshotai-cn 和 https://api.moonshot.cn/v1。

创建用于存储 Moonshot 凭证和 API 根地址的模型服务提供方密钥，并保存其 ID：

# 请替换为实际值
export MOONSHOT_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": "moonshot-prod",
    "provider": "moonshotai",
    "api_key": "'"${MOONSHOT_API_KEY}"'",
    "api_base": "https://api.moonshot.ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为 moonshotai，不是 moonshot 或 kimi。AISIX Cloud Admin API 仅接受目录中的模型服务提供方 ID，并会以 400 INVALID_REQUEST 拒绝其他拼写。AISIX Cloud Admin API 会从目录模型服务提供方推导适配器；adapter 字段仅接受用于 BYO 模型服务提供方密钥。

❷ api_key 存储 Moonshot API Key，并作为 Bearer Token 发送。该值在存储前加密，读取端点绝不会返回它。它遵循模型服务提供方密钥中的凭证处理行为。

❸ api_base 已包含 /v1 路径，因为 Moonshot AI 在 /v1 下而非主机根地址上提供兼容 OpenAI 的接口。AISIX 会将端点路径追加到该值，因此应使用 https://api.moonshot.ai/v1，末尾不要带 /chat/completions。如需路由到中国平台，请创建单独的模型服务提供方密钥，将 provider 设置为 moonshotai-cn，并将 api_base 设置为 https://api.moonshot.cn/v1。

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

创建模型

Moonshot 模型 ID 遵循 kimi-<generation> 模式，并可带有用于特定任务或吞吐量变体的可选后缀。例如，kimi-k2.6 是通用模型，kimi-k2.7-code 是编程模型，kimi-k2.7-code-highspeed 是其高吞吐量变体。kimi-k3 是当前旗舰模型。Moonshot AI 会停用早期 kimi-k2-*-preview ID 等较旧快照，因此固定 ID 前，请对照 Kimi 模型列表确认。

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

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": "kimi-k26-prod",
    "model_name": "kimi-k2.6",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方在 model 中发送的别名。别名与上游 ID 相互独立，因此不需要包含代次编号。

❷ model_name 是 Moonshot 模型 ID，例如 kimi-k2.6、kimi-k2.7-code 或 kimi-k3。句点是上游 ID 的一部分，必须原样保留。

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

创建调用方 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": "moonshot-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 的值通过 ID 引用模型，因此该密钥只能访问你创建的别名。写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置

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

export MOONSHOT_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

为此模型服务提供方创建完整的声明式资源文件：

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "moonshot-prod"
    provider: "moonshotai"
    adapter: "openai"
    api_key: ${MOONSHOT_API_KEY}
    api_base: "https://api.moonshot.ai/v1"

models:
  - display_name: "kimi-k26-prod"
    provider: "moonshotai"
    model_name: "kimi-k2.6"
    provider_key: "moonshot-prod"

api_keys:
  - display_name: "moonshot-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "kimi-k26-prod"

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

aisix validate --resources resources.yaml

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

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

export AISIX_API_KEY="$CALLER_API_KEY"

验证模型服务提供方连接

导出 AISIX 网关源地址：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 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": "kimi-k26-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Kimi."
      }
    ]
  }'

网关返回兼容 OpenAI 的响应，其中会回显面向调用方的别名 kimi-k26-prod。如果请求失败，请检查模型服务提供方密钥的 api_key、api_base，以及 model_name 中的 Moonshot 模型 ID。如果密钥在 Moonshot 控制台中有效，但认证失败，通常表示 api_base 主机与签发该密钥的平台不匹配。

使用思考模式

当前 Kimi 代次使用不同的推理控制。在 kimi-k2.6 上，发送顶层 thinking 对象中的 {"type": "disabled"} 可关闭该请求的推理：

{
  "thinking": {
    "type": "disabled"
  }
}

AISIX 会将自身未建模的顶层请求字段（包括 thinking）原样转发给上游，因此使用此控制无需模型服务提供方密钥覆盖设置。不同模型代次的推理控制存在差异：

模型	推理控制	跨轮保留思考
`kimi-k2.6`	`thinking.type` 接受 `enabled`（默认）或 `disabled`。	`thinking.keep` 默认为 `null`；设置为 `all` 可保留历史 `reasoning_content`。
`kimi-k2.7-code` 和 `kimi-k2.7-code-highspeed`	推理始终启用。省略 `thinking`，或使用唯一接受的类型 `enabled`。	始终启用。唯一接受的显式 `thinking.keep` 值是 `all`。
`kimi-k3`	推理始终启用，且不支持 `thinking` 对象。将顶层 `reasoning_effort` 设置为 `low`、`high` 或 `max`（默认）。	始终启用。

有关每个模型接受的参数，请查阅 Kimi 思考模式指南。

Moonshot AI 在 reasoning_content 字段中返回推理文本，这也是 AISIX 已经规范化到的标准字段。在流式响应中，reasoning_content 增量先于 content 增量到达；在非流式响应中，该字段位于 choices[0].message.reasoning_content。由于上游格式已经匹配，moonshotai 目录条目未设置 response.reasoning_field 覆盖规则，也不需要设置。仅当某个上游从其他 delta 路径流式返回推理内容时，才设置 response.reasoning_field。

对于 K3 和 K2.7 工具循环或多轮对话，请将 AISIX 返回的完整助手消息追加到下一次 Chat Completions 请求。AISIX 会在该路由上保留消息级 reasoning_content。如果只复制 content 和 tool_calls，会丢失这些模型要求的推理历史。K2.6 设置 thinking.keep 为 all 时同样适用。

推理 Token 和最终答案 Token 共享 Moonshot AI 的 max_completion_tokens 预算。已弃用的 max_tokens 字段仍可接受。当推理密集型提示词返回的内容被截断时，请提高限制，并在 AISIX 中设置按模型预算时核算相同的 Token。

查看端点支持

Moonshot 主要提供 Chat Completions，以及兼容 OpenAI 的文件和批处理管理。AISIX 行为同时取决于适配器和特定路由的服务提供方检查：

路由	使用 Moonshot 别名时的行为
`/v1/chat/completions`	支持，包括流式传输、工具、结构化输出，以及兼容 Kimi 模型上的图片或视频内容块。
`/v1/responses`	通过基于 Chat 的 Responses 桥接支持，并非 Moonshot 原生 Responses 端点。桥接会丢弃 Responses 推理控制，也不会在返回的 Responses 输出中编码 Moonshot `reasoning_content`，因此推理工作流请使用 Chat Completions。
`/v1/messages`	通过 Anthropic 到 Chat 的转换支持，并非 Moonshot 独立的 Anthropic 兼容 API。桥接不会将 Moonshot 推理历史保留为 Anthropic 思考块。`/v1/messages/count_tokens` 要求 Anthropic 后端模型，因此会拒绝此配置。
`/v1/files` 和 `/v1/batches`	通过 `openai` 适配器支持。AISIX 会重写返回的资源 ID，使后续文件和批处理调用路由到同一别名。上传的批处理 JSONL 文件中的每个请求必须使用上游 Kimi 模型 ID（例如 `kimi-k2.6`）；AISIX 不会重写文件中的模型名称。
`/v1/embeddings`、`/v1/completions`、`/v1/audio/*` 和 `/v1/fine_tuning/jobs`	不支持。Moonshot 未为这些路由记录兼容的上游端点。
`/v1/images/generations`	返回 `400` 而被拒绝。该路由要求模型服务提供方为 `openai`。
`/v1/rerank`	返回 `400` 而被拒绝。该路由只接受 `openai`、`cohere` 和 `jina` 服务提供方值。
`/v1/videos`	返回 `501 not_implemented` 而被拒绝。路由允许列表不包含 `moonshotai`。Kimi 的视频能力是通过 Chat 输入理解视频，而非生成视频。
`/passthrough/moonshotai/*`	通过已配置的透传路由可用于路由 `/v1` 目标下的 Moonshot 原生路由。

规范化 /v1/files 返回的路由 ID 适用于后续规范化文件和批处理路由，但它不是原始 Moonshot 文件 ID。当 Kimi Chat 消息必须以 ms://<file-id> 引用上传的图片或视频时，请通过 /passthrough/moonshotai/files 上传和管理资源，使应用获得原生 ID。

对于 AISIX 未建模的 Moonshot 原生端点，请使用模型服务提供方透传，并将 moonshotai 用作模型服务提供方路径段：

curl -sS -X GET "$AISIX_PROXY/passthrough/moonshotai/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

透传会保留调用方认证；inject 模式路由会把路由服务提供方密钥的凭证注入上游。当请求路径以路由 target_url 末尾已有的相同版本路径开头时，AISIX 会合并重复部分，因此上述请求会到达 https://api.moonshot.ai/v1/models，而不是重复的 /v1/v1 路径。

其他实用原生路径包括 /tokenizers/estimate-token-count、/users/me/balance、/files 和 /batches。透传不会重写 AISIX 模型别名或资源 ID，并会增量中继上游响应和 SSE。AISIX 会检测 Chat、Completions 和 Responses 信封，并记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。每条路由绑定一个固定目标，inject 模式下还绑定一把服务提供方密钥，因此使用多个 Moonshot 账号或根地址时请分别建路由。

Moonshot 兼容 Anthropic 的 API 使用独立的 https://api.moonshot.ai/anthropic 根地址。它不在本指南使用的 /v1 根地址下，因此以该根地址为目标的路由无法访问它；兼容 Anthropic 的 API 需要自己的透传路由。

后续步骤

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

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

前提条件​

使用 AISIX Cloud 配置​

创建模型服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证模型服务提供方连接​

使用思考模式​

查看端点支持​

后续步骤​