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，且不含尾部斜杠
# 本地私有化部署快速入门使用 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 和原生 Responses 创建服务提供方密钥、模型别名和调用方 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",
    "apis": {
      "responses": {}
    },
    "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。

❹ apis.responses 声明 OpenRouter 在同一根地址提供 Responses API。这样，AISIX 就能使用 OpenRouter 的原生请求和响应格式，而不必通过 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"
    apis:
      responses: {}

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：

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

通过 AISIX 代理发送 Responses 请求：

curl -sS -X POST "$AISIX_PROXY/v1/responses" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter-sonnet-prod",
    "input": "Say hello from OpenRouter."
  }'

AISIX 会将请求发送至 OpenRouter 的原生 Responses 端点，在上游请求中把 AISIX 别名替换为带命名空间的模型 ID，并在响应中恢复该别名。

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

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

通过透传使用原生 Messages

上述服务提供方密钥已经会把 Responses 请求发送到 OpenRouter 原生端点，同时保留 AISIX 模型别名。OpenRouter 还在同一 API Root 上提供原生 Messages API，但其文档使用 Bearer 身份认证，且未提供 Count Tokens。请继续通过透传访问原生 Messages，不要添加 apis.messages；该声明会发送 x-api-key，并把两条 Messages 路由表示为一个完整协议面。

调用 /passthrough/openrouter/messages，并发送带命名空间的 OpenRouter 模型 ID，因为透传不会重写别名。详细的路由行为和透传设置参见OpenRouter 模型的端点支持情况。

传递 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 还可能返回结构化 reasoning_details 数组；某些多轮推理和工具调用流程需要原样重放该数组。规范化 AISIX Chat 路径不会保留它。应用必须保留结构化推理状态时，请通过透传路由使用 OpenRouter 原生端点。

警告

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

OpenRouter 模型的端点支持情况

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

路由	OpenRouter 支持情况
/v1/chat/completions，包括 stream: true	通过 openai 适配器支持。
/v1/completions	对接受 OpenRouter 旧版基于 Prompt 的 Completions 格式的模型提供支持。
/v1/responses	由于本指南声明了 apis.responses，请求会发送至 OpenRouter 原生 Responses API。如果没有此声明，AISIX 会通过 Responses 桥接转换请求。
/v1/messages	通过转换为 Chat Completions 支持，而非调用 OpenRouter 原生 Anthropic Messages API。没有 Chat 等价项的字段和响应块无法往返保留。原生协议请使用 /passthrough/openrouter/messages。
/v1/messages/count_tokens	不可用。此 AISIX 路由要求采用 Anthropic 协议的服务提供方密钥，而 OpenRouter 集成使用 openai 适配器。
/v1/embeddings	当别名指向 OpenRouter 嵌入模型时支持。AISIX 会将 OpenAI Embeddings 请求格式转发到 https://openrouter.ai/api/v1/embeddings。
/v1/audio/speech	当别名指向 OpenRouter 语音模型时支持，因为 JSON 请求和上游路径兼容。
/v1/audio/transcriptions 和 /v1/audio/translations	这些规范化路由不支持。AISIX 接受 OpenAI 风格的 Multipart 上传，而 OpenRouter 转录端点接受 JSON input_audio 对象，且 OpenRouter 未提供匹配的翻译路由。请使用 /passthrough/openrouter/audio/transcriptions 和 OpenRouter 原生 JSON 结构。
/v1/images/generations	不可用。该路由只接受服务提供方值为 openai 的模型，且 OpenRouter 原生图片端点是 /images，而非 /images/generations。请使用 /passthrough/openrouter/images 和 OpenRouter 图片请求。
/v1/rerank	不可用。该路由只接受 openai、cohere 和 jina 服务提供方值。请使用 /passthrough/openrouter/rerank 和 OpenRouter 重排模型 ID 调用其原生路由。
/v1/videos 及其状态和内容路由	不可用。openrouter 服务提供方值会返回 501 not_implemented。对于 OpenRouter 原生异步视频 API，通过 /passthrough/openrouter/videos 提交，再使用返回的作业 ID 调用 /passthrough/openrouter/videos/{jobId} 和 /passthrough/openrouter/videos/{jobId}/content。
/v1/files	不要将规范化文件路由用于 OpenRouter 原生文件引用。AISIX 会为其作业路由协议封装返回的文件 ID，但不会在原生 OpenRouter Messages 或 Responses 请求体中解封这些 ID。请使用 /passthrough/openrouter/files 保留 OpenRouter 原始文件 ID。
/v1/batches 和 /v1/fine_tuning/jobs	不可用，因为 OpenRouter 未发布匹配的路由。
/v1/models	返回调用方可访问的 AISIX 模型别名，而非 OpenRouter 模型目录。原生列表请使用 /passthrough/openrouter/models。
/passthrough/openrouter/*rest	通过已配置的透传路由可用。

对于 AISIX 未标准化的路由，请使用透传路由。本页的 /passthrough/openrouter 路径假定这样一条路由认领该前缀，target_url 设为 https://openrouter.ai/api/v1；在调用方 Key 的 allowed_routes 上授予该路由。网关会将剩余路径追加到路由的 target_url；如果路径开头的 v1 与目标末尾的 /v1 重复，则会移除一个 v1 路径段。因此，/passthrough/openrouter/models 和 /passthrough/openrouter/v1/models 都会到达 https://openrouter.ai/api/v1/models。

透传路由会原样转发请求体，不会重写模型别名。请发送带命名空间的 OpenRouter 模型 ID（例如 anthropic/claude-sonnet-5），而非 openrouter-sonnet-prod。路由会增量中继 SSE 响应。AISIX 会为信封识别与用量中列出的请求形态记录 Token 用量，其中包括顶层带 query 和 documents 数组的 rerank 请求体，但透传用量不计成本。如果规范化端点的协议足够使用，并且需要 AISIX 成本核算，请优先使用规范化端点。

后续步骤

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

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