OpenRouter

OpenRouter 通过一套 API 和凭证聚合多个服务提供方的模型。AISIX 将 OpenRouter 凭证保留在网关中，同时提供稳定的模型别名、调用方访问控制、速率限制和用量核算。

准备工作

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

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
从 OpenRouter 密钥页面获取的 OpenRouter API Key。OpenRouter 密钥值以 sk-or- 开头。
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"

为 OpenRouter 支持的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

由于 OpenRouter 提供 OpenAI 兼容 API，AISIX 会通过 openai 适配器连接，并将 OpenRouter API Root 用作 api_base。

创建服务提供方密钥

创建用于存储 OpenRouter 凭证和 API Root 的服务提供方密钥：

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

echo "$PROVIDER_KEY_ID"

❶ provider 为 openrouter。AISIX Cloud Admin API 会根据目录服务提供方推导适配器；adapter 字段仅适用于 BYO 服务提供方密钥。

❷ api_key 存储 OpenRouter API Key。该值会在存储前加密，读取端点绝不会将其返回。它遵循服务提供方密钥中的凭证处理行为。

❸ api_base 为 https://openrouter.ai/api/v1。OpenRouter 在其主机的 /api 路径下提供 API，因此该 Root 同时包含 /api 和 /v1，而不是 https://openrouter.ai/v1。AISIX 会在此值后追加端点路径，例如 /chat/completions。

请始终为 OpenRouter 显式设置 api_base。与多数精选目录服务提供方不同，OpenRouter 在 AISIX 中没有预先维护的默认 Base URL；如果省略 api_base，AISIX Cloud Admin API 将依赖同步的目录元数据，创建操作可能会以 400 INVALID_REQUEST 失败。

网关在请求时也会执行同一规则。当非 OpenAI 服务商的服务提供方密钥以空 api_base 到达网关时，OpenAI 系列桥接器不会回退到 OpenAI 公共主机，而会返回上游配置错误。因此，OpenRouter 凭证绝不会发送到 api.openai.com。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

OpenRouter 模型 ID 带有命名空间。上游 ID 的格式为 vendor/model，其中服务商前缀是 ID 的组成部分，而不是路由提示。创建模型别名前，请在 OpenRouter 模型列表中查看当前 ID。

命名约定有四种形式：

vendor/model 是基本形式，例如 anthropic/claude-sonnet-5、openai/gpt-5.2-pro 或 deepseek/deepseek-v4-pro。
变体后缀追加到 Slug 末尾，例如 :free 或 :thinking。
服务商名称前的 ~ 会解析为某个模型系列的最新版本，例如 ~anthropic/claude-sonnet-latest。
openrouter/auto 选择 OpenRouter 自身的 Auto Router，而不是具名模型。

模型别名和上游模型 ID 是两个不同的名称。display_name 是调用方放入请求 model 字段的 AISIX 别名，model_name 则是 OpenRouter 模型 ID。AISIX 会将 model_name 原样转发到上游，包括服务商前缀中的 /。它不会拆分 ID，也不会移除服务商部分。

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

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": "openrouter-sonnet-prod",
    "model_name": "anthropic/claude-sonnet-5",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方在 model 中发送的别名。请使用简短的扁平名称。将带命名空间的上游 ID 复制到别名中，会降低客户端代码的可读性，也会让人难以分辨实际使用的是哪个别名。

❷ model_name 是 OpenRouter 模型 ID，例如 anthropic/claude-sonnet-5 或 openai/gpt-5.2-pro。

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

为每个要公开的 OpenRouter 模型分别创建一个别名。一个 OpenRouter 服务提供方密钥可以支持任意数量的别名，这样一套凭证就能覆盖多个服务商，同时每个别名仍拥有各自的允许列表条目和速率限制。

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

echo "$AISIX_API_KEY"

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

使用开源 AISIX 网关配置

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

export OPENROUTER_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

resources.yaml
_format_version: "1"

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

models:
  - display_name: "openrouter-sonnet-prod"
    provider: "openrouter"
    model_name: "anthropic/claude-sonnet-5"
    provider_key: "openrouter-prod"

api_keys:
  - display_name: "openrouter-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "openrouter-sonnet-prod"

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

aisix validate --resources resources.yaml

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

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

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# 本地快速入门使用 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": "openrouter-sonnet-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from OpenRouter."
      }
    ]
  }'

网关返回 OpenAI 兼容响应，其中回显调用方可见的别名 openrouter-sonnet-prod，而不是带命名空间的上游 ID。

如果请求失败，请先检查以下 OpenRouter 特有原因：

上游返回 404 通常表示 model_name 中缺少服务商前缀或前缀拼写错误。claude-sonnet-5 不是有效的 OpenRouter ID；anthropic/claude-sonnet-5 才是。
上游返回 401 通常表示 api_key 中保存的不是 OpenRouter 密钥。OpenRouter 不接受由模型原始服务商签发的密钥。
连接到意外主机时出现错误，通常表示 api_base 缺少 /api 路径段。

传递 OpenRouter 路由和推理控制参数

AISIX 不会移除其未建模的顶层 Chat Completions 字段。未建模字段会原样转发到上游，因此 OpenRouter 自身的请求级控制参数会原封不动地到达 OpenRouter。

通过网关通常会使用以下两个 OpenRouter 控制对象：

provider 用于选择处理请求的上游服务商。它接受 order、allow_fallbacks 和 require_parameters 等字段。请参阅服务提供方路由。
reasoning 通过 enabled、effort 和 max_tokens 控制思维链行为，顶层 reasoning_effort 字段是推理强度设置的别名。请参阅推理 Token。

以下请求固定提供服务的服务商、禁用 OpenRouter 故障转移，并请求较高的推理强度：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter-sonnet-prod",
    "messages": [
      {
        "role": "user",
        "content": "Summarize the CAP theorem in two sentences."
      }
    ],
    "provider": {
      "order": ["anthropic"],
      "allow_fallbacks": false
    },
    "reasoning": {
      "effort": "high"
    }
  }'

读取推理输出

OpenRouter 在非流式路径的 message.reasoning 和流式路径的 delta.reasoning 中返回思维链文本，而不是使用其他 OpenAI 兼容上游采用的 reasoning_content 字段。

AISIX 会将二者标准化到规范的 reasoning_content 字段，因此无论上游使用哪种字段名称，客户端都读取 choices[0].message.reasoning_content 和 choices[0].delta.reasoning_content。当上游同时发送两个字段时，reasoning_content 优先。

此标准化逻辑内置于 openai 适配器的 OpenRouter 处理中。不要在 OpenRouter 服务提供方密钥上设置 response.reasoning_field 覆盖项。该覆盖项用于 AISIX 尚无法识别其推理路径的上游。

警告

服务提供方和推理控制参数是 OpenRouter 特有的请求字段。如果以后将别名重新指向其他服务提供方，或将其置于多目标路由模型之后，AISIX 会把这些字段转发到实际处理请求的上游，而非 OpenRouter 上游可能会忽略或拒绝无法识别的字段。

OpenRouter 模型的端点支持情况

OpenRouter 模型别名并不能访问所有代理路由。部分路由根据配置的服务提供方值而非适配器系列进行限制。

路由	OpenRouter 支持情况
`/v1/chat/completions`，包括 `stream: true`	通过 `openai` 适配器支持。
`/v1/responses`	通过 Responses 桥接支持，该桥接会将请求转换到聊天适配器路径。
`/v1/embeddings`	当别名指向 OpenRouter 嵌入模型时支持。AISIX 会将 OpenAI Embeddings 请求格式转发到 `https://openrouter.ai/api/v1/embeddings`。
`/v1/images/generations`	不可用。该路由仅接受服务提供方值为 `openai` 的模型，因此通过 OpenRouter 访问的图像模型会被拒绝。
`/v1/rerank`	不可用。该路由仅接受 `openai`、`cohere` 和 `jina` 服务提供方值。
`/v1/videos` 及其状态和内容路由	不可用。`openrouter` 服务提供方值会返回 `501 not_implemented`。
`/passthrough/openrouter/*rest`	支持。

对于 AISIX 未标准化的路由，请使用透传隧道。它会将剩余路径追加到服务提供方密钥的 api_base；如果路径开头的 v1 与 Base 末尾的 /v1 重复，则会移除一个 v1 路径段。因此，/passthrough/openrouter/models 和 /passthrough/openrouter/v1/models 都会到达 https://openrouter.ai/api/v1/models。

后续步骤

现在，你已将 AISIX 连接到 OpenRouter，并验证了模型别名。请继续阅读以下指南：

模型别名：为此别名配置路由、重试行为或成本元数据。
路由和故障转移：在 OpenRouter 和直接服务商账户之间进行故障转移。
服务提供方透传：访问 AISIX 未标准化的 OpenRouter 路由。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

传递 OpenRouter 路由和推理控制参数​

读取推理输出​

OpenRouter 模型的端点支持情况​

后续步骤​