OpenRouter接入新推理服务商Makora：从发现到调用的完整指南

最近 OpenRouter 平台上线了一个新的推理服务商，名字叫 Makora。做过多模型聚合调用的人应该都清楚，OpenRouter 上多一家服务商，不是简单的“模型列表变长了”，而是意味着你在模型选型时又多了一个后端、一个定价维度，以及一类延迟表现。这篇文章会从 OpenRouter 的实际用法出发，把“新推理服务商上线后怎么用起来”这件事讲清楚：包括如何发现和筛选新上线的服务商、如何用标准 OpenAI 兼容接口调用、如何把这类服务商接入 Claude Code、Dify 等现有工具，以及 429 限流、模型列表里找不到模型这些高频问题怎么处理。

如果你平时已经在用 OpenRouter 做多模型调用，这篇文章可以直接收藏；如果你只是刚注册账号，想搞懂 OpenRouter 怎么用、API Key 怎么创建、怎么把推理服务商接到自己的代码里，也能照着把基础流程跑通。内容以通用工程流程为主，具体定价、额度、模型清单和区域可用性，都以你打开 OpenRouter 时实际看到的信息为准。

1. 核心能力速览

这里要先说清楚一个基本概念：OpenRouter 本身不做模型训练，它更像一个模型网关。各家推理服务商把模型接入平台后，OpenRouter 负责把用户请求转发到对应后端，再把结果统一返回给调用方。所以 Makora 作为新服务商上线，实际含义是：OpenRouter 的可用模型池里新增了来自该服务商的模型，你可以通过 OpenRouter 的同一个 API 去调用它，而不用单独注册它的原始平台。

从工程角度看，这个架构有三个直接好处。第一，调用端只需要维护一套接口规范，模型厂商的差异被挡在网关后面。第二，计费被统一了，你不需要在多个服务商之间分别充值、分别统计消费。第三，可以做路由和降级，一个服务商不稳定时，可以在网关层快速切换。这三个点在 Makora 这类新服务商上线后尤其有用，因为你可以非常快地把它拉进对比池里做测试。

2. 适用场景与使用边界

2.1 适合场景

从 OpenRouter 的设计目标来看，这类聚合平台重点解决三个问题：

1. 模型选择困难：不同服务商的模型能力、价格、上下文长度都不一样，靠人工逐个维护成本太高。
2. 接口碎片化：不同厂商给不同 SDK，每接入一个服务商就要重新写一段请求逻辑。
3. 故障转移：一个服务商不可用时，可以在网关层面切换到备选。

Makora 上线以后，你可以在 OpenRouter 的模型列表里找到它提供的模型，然后做同一组输入、同一组参数下的横向对比。这个“横向对比”能力很重要，因为它直接影响成本决策：同样是处理一批文本，A 服务商可能延迟低但价格高，B 服务商可能便宜但输出质量一般。没有统一网关时，做这种对比要写多套调用代码，现在一次 API 调用就能切换。

2.2 不适合场景

聚合 API 也不是万能的。如果你需要私有化部署、数据完全不出内网，那么云端的聚合 API 并不适合，因为请求必然经过 OpenRouter 转发。如果你的业务对最低时延有硬性要求，跨区域公网转发不一定比直连厂商更稳。如果只是偶尔调用一次，可能不值得先充一大笔钱，先用小额度测试更稳妥。

2.3 合规与安全边界

使用任何第三方推理服务商，都要注意几个边界：

• 输入数据可能经过平台转发，涉及敏感业务数据前先评估脱敏方案和隐私政策。
• 要确认服务商对生成内容的版权、使用要约是否清晰。
• 不要用真实个人信息、他人肖像、版权文本去做无授权测试。
• 如果业务要求内容审核、合规留痕，还要结合自身业务规范做复审。

新服务商上线的早期，文档和模型行为描述不一定完整。遇到信息不明确的地方，宁可先小规模测试，也不要直接把生产流量切过去。

3. 环境准备与前置条件

虽然 OpenRouter 是 API 服务，不涉及本地显卡、CUDA 和模型文件，但正式开始前仍要做一轮环境清单检查。

注意一点：OpenRouter 的模型调用是在云端完成的，本机不需要 GPU、显存、显卡驱动。这也是它和本地部署模型最大的区别。你想要测试推理延迟，关注的是网络 RTT、服务商排队情况和模型生成速度，而不是本地显存占用。

“OpenRouter 国内能用吗”这类问题的答案，取决于你的实际网络出口到 OpenRouter API 的连通性。有的网络环境访问正常，有的则可能因为网络波动出现超时、429、连接不上等情况。更稳妥的判断方式是：先通过 curl 或网页控制台做一次连通性测试，再决定是否投入正式业务。不要把别人的网络表现直接当成你的网络表现。

4. 启动与接入思路

OpenRouter 没有本地启动器，它本身就是远程服务。所谓“启动”，对应的是这样几个步骤：

1. 打开 OpenRouter 页面，登录。
2. 在 Model 或 Providers 区域查找 Makora 以及它提供的模型。
3. 创建 API Key。
4. 通过 curl / SDK 发起第一次请求。

4.1 生成 API Key

在 OpenRouter 控制台创建 API Key，一般步骤是：进入 Keys 页面，创建新 Key，设置权限和用途，然后保存。创建完成后，把 Key 放到环境变量里，避免写死在代码中。

export OPENROUTER_API_KEY="sk-or-v1-xxxxxx"

注意：API Key 通常在创建时完整展示一次，后续再打开只能看到脱敏信息。忘记完整内容就重新创建一个，旧 Key 可以撤销。

4.2 查看模型列表

请求模型列表接口，可以看到当前 OpenRouter 可用的模型，以及包括 Makora 在内的服务商信息：

curl https://openrouter.ai/api/v1/models \ -H "Authorization: Bearer $OPENROUTER_API_KEY" | jq '.data[].id'

如果 jq 没安装，可以去掉| jq...直接看 JSON。正常响应里会包含大量模型 ID，通常采用“服务商/模型名”的格式。你可以在返回结果里搜索makora关键词，确认该服务商是否有模型、是否处于上线状态。如果确实搜不到，可能说明该服务商的模型没有对当前账号开放，或者还没正式上架到模型列表。

4.3 第一次 Chat 请求

用 curl 发一个简单的对话请求：

curl https://openrouter.ai/api/v1/chat/completions \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "makora/具体模型ID", "messages": [ {"role": "user", "content": "用一句话介绍 OpenRouter"} ] }'

这里makora/具体模型ID需要替换成实际模型 ID。如果模型 ID 不对，接口会返回模型不存在或不可用的错误；此时去模型列表里确认准确 ID。

需要特别提醒的是：不要照抄网络上的旧模型 ID。聚合平台上的模型 ID 会随时更新，新服务商刚上线时，ID 也可能在短时间内调整。一切以/api/v1/models返回值为准。

4.4 在 Dify / 自定义应用中配置

如果你在使用 Dify 这类 LLM 应用平台，通常会提供一个“OpenAI API 兼容”接入入口。这时你可以把 OpenRouter 当作一个兼容后端来配置：

• API Base URL 填https://openrouter.ai/api/v1。
• API Key 填 OpenRouter 的 Key。
• 模型名填 OpenRouter 上能查到的准确 ID。

配置完成后，先做一个最简单的对话测试，确认应用平台能连通 OpenRouter，再继续配置多轮对话、知识库或工作流。这里要强调一下：Dify 的 Chatflow 是否支持多轮对话推理，取决于 Dify 版本和你选择的模型是否支持消息历史传递，不能只看 OpenRouter 这一侧。

5. 功能测试与效果验证

新服务商上线后，建议按下面的测试矩阵快速验证，而不是直接丢到生产环境。这样能更快发现模型不可用、接口不兼容、限流策略异常等问题。

5.1 连通性测试

目的：确认 API 能通、Key 有效。

操作：

• 调用/api/v1/models，确认返回 200。
• 用一个极短对话请求确认 Chat 接口可用。

判断标准：

• 返回 JSON，包含模型列表或正常文本响应。
• 如果返回 401、403，说明 Key 无效或权限不足。
• 如果返回 429，说明触发限流或额度不足。

5.2 基础对话测试

目的：确认该服务商的模型能正常生成内容。

操作：

• 用 curl 请求发送一句“你好”。
• 观察返回内容是否完整、是否有明显延迟。
• 设置max_tokens为较小值，控制返回长度，避免长文本等待。

5.3 特殊参数测试

OpenRouter 是 OpenAI 兼容接口，常规参数和 OpenAI 大体一致：

{ "model": "当前服务商模型ID", "messages": [ {"role": "system", "content": "你是一名测试助手"}, {"role": "user", "content": "请输出 3 个关于推理服务的建议"} ], "temperature": 0.7, "max_tokens": 256, "top_p": 0.9 }

建议观察：

• temperature、top_p是否被模型接受。
• 平台是否返回参数说明或警告。
• 返回的usage字段中 token 统计是否合理。

不同服务商对相同参数的解释不一定一致，同一个请求在不同服务商上的结果可能不同。跨服务商对比时，尽量固定同一套参数，这样对比才有意义。

5.4 上下文长度测试

目的：验证模型在长文本场景下的表现。

操作：

• 输入一段 2000 字左右的资料，让模型做摘要。
• 观察是否超出上下文限制。
• 逐步增加文本长度，找到模型可稳定处理的边界。

判断标准：

• 如果提示词超过模型最大上下文，接口通常返回参数错误。可以在模型详情里查看上下文参数。

5.5 多轮对话和工具调用测试

如果你的场景涉及 Agent 或多轮对话，建议测：

• 连续多轮对话，确认历史消息是否正常传递。
• Function Calling / Tool Calling 是否可用。
• 在 Dify、Claude Code 等框架里是否正常工作。

这类功能在聚合 API 上不是每个模型都支持。Makora 新服务商模型是否支持，以平台模型详情页标注为准，不要假设它一定具备完整的 Agent 能力。

6. 接口 API 与批量任务

6.1 为什么要在接口层做控制

OpenRouter 这类网关模式，天然适合做批量任务：你只需要维护一套请求代码，把模型名换成不同服务商的模型即可。但批量调用和单次调用不一样，必须提前考虑限流、超时和重试。

6.2 Python 批量调用示例

下面给出一段通用 Python 示例，可以用于批量发送推理请求：

import os import time import requests API_KEY = os.getenv("OPENROUTER_API_KEY", "") API_URL = "https://openrouter.ai/api/v1/chat/completions" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } def call_model(prompt, model_id="当前服务商模型ID", max_tokens=256): payload = { "model": model_id, "messages": [{"role": "user", "content": prompt}], "max_tokens": max_tokens } try: resp = requests.post(API_URL, headers=headers, json=payload, timeout=120) if resp.status_code == 200: data = resp.json() return data.get("choices", [{}])[0].get("message", {}).get("content", "") else: print(resp.status_code, resp.text) return None except Exception as exc: print("request error:", exc) return None tasks = [ "总结 OpenRouter 的核心优势", "给出一个 API 降级测试方案", "解释什么是模型路由" ] for idx, task in enumerate(tasks, 1): result = call_model(task) print(f"任务 {idx}: {result}") time.sleep(1) # 控制频率，降低限流概率

这里没有使用 OpenAI SDK，直接用 requests，方便你复制到任意环境测试。如果你已经装了openaiSDK，也可以把base_url指向 OpenRouter，参数基本兼容。

6.3 批量任务建议

批量任务不要一把梭，建议按以下思路做：

• 控制并发：先 1 并发，确认稳定后再逐步加。
• 加入重试：遇到 429、503 时，做指数退避重试，例如 1s、2s、4s。
• 记录日志：任务 ID、模型 ID、请求时间、返回码、token 消耗。
• 设置预算：批量任务前先估算 token 成本。

import time def call_with_retry(prompt, model_id, retries=3): for attempt in range(retries): result = call_model(prompt, model_id) if result is not None: return result wait = 2 ** attempt print(f"第 {attempt + 1} 次失败，等待 {wait}s") time.sleep(wait) return None

6.4 从接口层面筛选服务商

OpenRouter 支持在请求中指定服务商或排除某些服务商。例如provider参数中的order、allow、disallow字段。具体字段以最新文档为准，但思路是通用的：

• 想让请求优先走 Makora，可以设置提供商排序。
• 想避免某些不稳定服务商，可以用排除列表。
• 想降低成本，可以按价格从低到高路由。

这个能力很适合对比测试：你可以在固定模型的前提下，测试不同服务商返回结果的差异。

6.5 用 OpenAI SDK 接入

如果你用的是 OpenAI Python SDK，可以像下面这样切换到 OpenRouter：

from openai import OpenAI client = OpenAI( base_url="https://openrouter.ai/api/v1", api_key=os.getenv("OPENROUTER_API_KEY") ) response = client.chat.completions.create( model="当前服务商模型ID", messages=[{"role": "user", "content": "你好"}] ) print(response.choices[0].message.content)

SDK 的好处是已经封装了请求和响应解析，适合直接嵌入到现有项目。缺点是你需要确认所用 SDK 版本与 OpenRouter 的兼容性，特别是一些较新的 Agent 参数，不同 SDK 版本差异较大。

7. 资源占用与性能观察

OpenRouter 是云 API，本机资源占用很小。真正需要观察的是这三件事：延迟、成本、稳定性。

7.1 延迟

一次请求的完整耗时由几个部分组成：

• 客户端到 OpenRouter 的网络 RTT。
• OpenRouter 到服务商的内部转发时间。
• 模型排队和生成时间。
• 返回内容的传输时间。

测试时不要只看总耗时，最好同时看：

• time命令测出的总耗时。
• 服务端返回中的usage字段。
• 从请求发出到返回第一个 token 的耗时，一般叫 TTFT。聚合 API 未必直接暴露这些字段，但你可以用日志估算。

7.2 成本计量

聚合平台一般按 token 计费。对比服务商时，不能只看单次价格，还要看：

• 上下文长度：输入越长，成本越高。
• 输出长度：输出 token 是否受限。
• 缓存命中：平台是否提供 prompt caching 机制。
• 限流：同一价格下，限流配置可能不同。

建议做一个小表格记录：

7.3 稳定性

稳定性不能通过一次请求判断。更稳妥的方式是：

• 连续跑 50 到 100 次请求，统计失败率。
• 在不同时间段测试，观察高峰时段是否更容易 429。
• 长时间跑批量任务，观察是否有偶发超时。

如果发现某个服务商在网络波动时表现得明显不稳定，可以在路由层面把它调整为备选。

7.4 token 用量的价值

token 用量不仅是计费依据，也是判断调用是否正常的依据。如果一个请求返回内容很短，但usage显示消耗了大量 token，说明提示词和系统指令占用了大量上下文；如果返回报错，但usage里有内容，说明部分 token 已经被计费。批量任务里，建议把每次请求的 usage 写入日志，方便后续做成本归因。

8. 常见问题与排查方法

这里把 OpenRouter 使用中最常见的问题列成一个排查表：

8.1 429 限流再说明

OpenRouter 429 是很多人都遇到过的错误。最常见的几个原因：

• 免费或低额度账户的配额较紧。
• 同时发了大量并发请求。
• 某个服务商自身也在限流。

处理思路很简单：

• 在代码里统一封装重试逻辑。
• 根据响应头里的Retry-After或错误信息调整等待时间。
• 如果只是测试，把并发改成 1，逐条请求。

不要一遇到 429 就认为是 OpenRouter 的问题。先看请求频率，再看账户余额，最后再看具体服务商的限流状态。

8.2 模型列表里找不到服务商模型

“为什么我在 OpenRouter 配置后找不到某个模型”这个问题，通常不是配置错了，而是：

• 模型 ID 不准确，需要去/models接口刷新。
• 模型暂未开放或仅对特定地区、特定账户开放。
• 工具里缓存了旧的模型列表。

处理方式是用/models接口直接搜索关键词，拿到准确 ID 后手动配置。不要依赖网页页面上的模糊搜索，接口返回的 JSON 是最新的。

8.3 Claude Code / cc-switch 接入问题

如果你想把 OpenRouter 上的模型接入 Claude Code，常见做法是通过环境变量或配置工具指定自定义 Base URL 和 API Key。cc-switch 这类工具的价值在于，可以集中管理多套 API 配置，在 OpenAI 兼容接口、不同服务商之间快速切换。

下面是一个通用配置思路：

• Base URL 填https://openrouter.ai/api/v1。
• API Key 填 OpenRouter 的 Key。
• 模型名填 OpenRouter 上能查到的准确 ID。

不要把模型名写成不存在的名称。配置完成后，先用最简单的对话确认连通性，再逐步测试工具调用、多轮对话和文件处理等高级功能。如果配置后仍然报模型找不到，优先刷新模型列表。

8.4 网络连通性判断流程

可以按这个流程做一次快速判断：

1. 打开 OpenRouter 网页，确认账号能登录。
2. 用 curl 请求https://openrouter.ai/api/v1/models，确认 API 可访问。
3. 如果网页正常但 API 超时，检查本地代理、防火墙和 DNS。
4. 如果 API 延迟高，可以试着换一个网络出口再测试。
5. 如果请求返回 429，优先看频率和余额。

这个流程能帮你把“平台问题”和“本机网络问题”区分开，避免在错误的方向上排查。

9. 最佳实践与使用建议

9.1 先小规模验证

新服务商上线，不要一上来就把生产流量切过去。先用 10 个以内请求验证基础能力，再决定是否扩大测试。这里的“小规模”不仅指请求数量少，也指单次请求的 token 量要小，避免一次性消耗过多额度。

9.2 固定一套基线 Prompt

跨服务商对比时，把所有测试 Prompt、参数、输出长度固定下来。否则对比结果很容易失真。建议整理一份独立的测试集，包含简单问答、长文本摘要、代码生成、多轮对话这几类，覆盖常见业务场景。

9.3 把凭证和代码分离

API Key 放环境变量或密钥管理服务里，不要写进代码仓库。特别是团队协作时，泄露 Key 会导致超额计费。如果发现 Key 泄露，第一时间在控制台撤销并重建。

9.4 建立批量任务的日志体系

批量任务至少要记录：

• 请求 ID。
• 模型 ID。
• 时间戳。
• 返回状态码。
• token 用量。
• 失败原因。

有了日志，后续排错和成本复盘都会轻松很多。批量任务跑完之后，还可以用日志里的 token 总量和平台账单对一下，及时发现计费异常。

9.5 设置预算和告警

聚合平台的计费是实时累积的。建议：

• 在平台设置消费上限或提醒。
• 在代码层统计 token 消耗，及时发现异常。
• 批量任务前先测一次单条成本，再估算总成本。

如果你是在团队里统一使用 OpenRouter，最好让所有人都用同一个计量方式，避免月底账单对不上。

9.6 关注生成内容合规

通过 OpenRouter 使用第三方模型，生成内容仍然由开发者或企业负责落地审核。涉及人脸、声音、版权文本、用户数据的场景，务必确认授权和合规边界。特别是做内容生成类产品时，输出内容需要经过人工或规则审核后再对外发布。

10. 总结与下一步

这次 OpenRouter 上线 Makora 推理服务商，给多模型调用带来的不是简单的“多了一个模型按钮”，而是多了一个可以对比的推理后端。如果你是做模型选型、成本对比或工具接入的开发者，最值得先做的一件事是：登录 OpenRouter，进入模型列表搜一下 Makora，确认它提供的模型 ID 和支持能力，然后用一个最小请求跑通。最容易踩的坑是模型 ID 写错、直接拿旧配置请求新服务商，以及忽略限流和超时。

下一步可以继续做三件事：一是建立一套按服务商维度记录的测试表格，把延迟、成本、质量分数沉淀下来；二是把 OpenRouter 接到现有工具链，比如 Claude Code、Dify 或自定义 Agent，验证实际业务场景；三是持续跟踪新服务商上线后的稳定性，至少在切换生产流量前完成一轮批量压力测试。

建议收藏备用，等新服务商稳定后直接按这套流程验证。