OpenRouter 把自己定位成什么：principles 与 models 两页的自述

2026-08-18

先说触发我去翻这两页文档的那个具体问题：假设你要在自己的服务里按价格做一次模型筛选，按官方文档的说明，/api/v1/models 返回的每个模型对象里都有一个 pricing 字段——这个价格是谁的价格？是这个模型在平台上所有 provider 里的最低价，还是某一家的价？这个问题不搞清楚，后面所有基于它算的东西都是错的。而这个问题只能靠读字段说明来定，不能靠猜。

答案就写在官方文档《Models》页的字段表里，而这个答案又恰好能反过来解释《Principles》页那几条自述。所以这篇不讲怎么用，只做一件事：把「官方自述」和「接口里真能核到的字段语义」两栏并排放好，看哪些对得上、哪些对不上。

官方自述的六条，先照原样摆出来

openrouter.ai/docs/guides/overview/principles 这一页很短，开头一句是官方自述的立场：他们认为未来是多模型、多供应商的（multi-model and multi-provider）。往下是「Why OpenRouter?」的六条小标题——价格与性能、标准化 API、真实世界数据、合并计费、更高可用性、更高速率上限。这六条我数过，就是六条，没有第七条。

这里我必须先立个规矩：以上全部是官方自述，是这家平台自己对自己的描述，不是我们核实过的客观结论。我们没有装过、没有跑过、也没有买过这个平台的任何东西，本文不替其中任何一条背书。下面做的事情只有一件——去《Models》页找，看这六条里哪几条能落到具体字段上。

顺带一提，官方自述在「价格与性能」那条上，把「怎么排优先级」的链接指向了 openrouter.ai/docs/guides/routing/provider-selection；在「标准化 API」那条上，把「让你的用户自己选、自己付」的链接指向了 OAuth 那一页。这两页各自有专门的内容，本文不展开。

顺着一次列表请求走：过滤、排序，然后停在口径上

openrouter.ai/docs/guides/overview/models 页写明，列表接口支持几个查询参数。最基础的是 output_modalities，按输出能力过滤，文档给的取值表里有 text、image、audio、embeddings、all 五个值，其中 text 标注为默认，all 的语义是「跳过模态过滤、全都要」。原样抄一条文档里的示例：

# All models regardless of modality
curl "https://openrouter.ai/api/v1/models?output_modalities=all"

文档同时写明，同一个参数在 /v1/models/count 端点上也可用，给出的理由是官方自述的：让计数与列表结果保持一致。这句话值得留意——它是文档把两个端点之间的口径约定写在了明面上；至于实际返回是否在任何时刻都严格对齐，本文没有可核的依据，不做判断。

第二个是 supported_parameters，按模型支持的 API 参数过滤。文档的例子是找支持工具调用的模型：

curl "https://openrouter.ai/api/v1/models?supported_parameters=tools"

第三个参数 sort 是这一段里最需要看清楚口径的。文档列了一张取值表，里面有按价格高低、按上下文窗口、按吞吐、按延迟、按热度、按新增时间排序的若干种。关键不在有哪些取值，而在文档给这些取值标注的口径：吞吐那一档，文档写的是「p50 throughput from routing heuristics」——来自路由启发式统计的 p50；延迟那一档写的是「p50 latency」，衡量的是首 token 时间。也就是说，这两个排序维度依据的是 OpenRouter 自己一侧的统计口径，不是第三方基准。文档还写明两条边界：缺少该排序维度数据的模型会排在最后；省略 sort 会保持默认排序，这是为了向后兼容。

「多供应商」这条自述，在字段上是怎么兑现的

现在回到开头那个问题。《Models》页的 Model Object 字段表里，pricing 这一行的说明原文是「Pricing from the top provider for this model」——这个模型在 top provider 上的价格。不是最低价，不是平均价，是那一家的价。

紧接着的 top_provider 字段是一个对象，文档在字段表里把它写成「主供应商的配置详情」，类型定义里有三个键：context_length、max_completion_tokens、is_moderated。这三个键的注释也值得逐字看：context_length 文档标的是 provider-specific，即供应商侧的上下文限制；max_completion_tokens 是响应里的最大 token 数；is_moderated 是是否施加内容审核。也就是说，同一个模型 id 底下，这几项被文档明确归到了「某一家供应商」的名下，而不是模型本身的全局属性。文档没有解释这样安排的原因，本文也不替它解释。

这就是官方自述的「多模型、多供应商」在 schema 上留下的痕迹。它带来的实际后果是：你按 /api/v1/models 返回的 pricing 做成本估算，估的是主供应商这一档，一旦路由落到别家，口径就对不上了。这不是我推断出来的，这是「Pricing from the top provider」这句话直接说的。至于路由到底怎么选供应商、有哪些供应商，那属于路由文档的范畴，而且平台上的供应商与端点随时在变，以官方文档最新内容为准，本文不列任何名单。

价格结构里那个容易漏掉的 `overrides`

pricing 对象本身是一组「每 token / 每请求 / 每单位」的价格键：prompt、completion、request、image、web_search、internal_reasoning、input_cache_read、input_cache_write。文档写明值为 "0" 表示该项免费。具体数值本文一个都不写，它们随时会变。

真正值得单独拎出来的是可选的 pricing.overrides 数组。文档自述它存在的原因是：有些端点在特定条件下按不同费率计费，例子是超过某个 token 阈值的长上下文计价，以及分时段计价（高峰时段更贵）。它的条件字段有三个：min_prompt_tokens（当总 prompt token 严格大于该阈值时生效）、utc_start 与 utc_end（当前 UTC 时间落在这个每日窗口内时生效，写成 HHMM 时钟格式，起点含、终点不含，窗口允许跨零点）。

匹配规则文档写得很清楚，四条：一个条目要在它所有条件字段都匹配时才生效；多个条目同时生效时，按键逐个比较、后面的条目胜出；条目里没写到的价格键继承基础价；顶层的价格键始终反映默认条件下适用的价格，overrides 只承载条件例外。

还有一条设计我认为是这两页里最实用的信息：文档写明，时间窗口类的 overrides 数组总是列出全部窗口（高峰与非高峰），铺满完整的 24 小时。官方给出的理由是——这属于文档自述——这样一来，不管响应是什么时候生成的，完整的计价排期都能从这一份响应里复原出来。如果你要在自己这边缓存价格表，这条决定了你不需要在不同时段反复拉取。

模型标识会变，这件事被写进了 schema

单模型查询这一段，文档给的路径是：

GET /api/v1/model/{author}/{slug}

文档写明这个端点会自动解析别名，给的例子是 anthropic/claude-3-5-sonnet 会重定向到规范形式 anthropic/claude-3.5-sonnet 并返回其数据；也支持变体后缀，把 :free、:thinking 之类追加到 slug 后面即可。模型不存在且不是任何模型的别名时返回 404。

# Aliases resolve automatically
curl "https://openrouter.ai/api/v1/model/anthropic/claude-3-5-sonnet"

需要说明的是：以上代码块里的模型 slug 是官方文档当时写的示例值，平台上有哪些模型、哪些变体随时在变，请不要把它当清单用。

和别名解析配套的，是字段表里的 canonical_slug——文档给的说明是「Permanent slug for the model that never changes」，永不改变的规范 slug，与会变的 id 分开。再加上 expiration_date（模型端点的弃用日期，未弃用则为 null），可以看出：模型改名、模型下架这两件在多模型场景里必然会发生的事，是被显式建模成字段的，而不是留给调用方自己去猜。你要做长期存储的关联键，canonical_slug 和 id 该用哪个，这两行字段说明已经给了答案。

哪几条自述，在这两页里核不到

这一节是我认为对读者最有价值的一段，因为它划的是边界。

benchmarks 字段的说明里有一句限定必须照实抄：文档写明其中的排名「是在 OpenRouter 上架的模型之间计算的，不是完整的外部榜单」，并且没有评测数据的模型会整个省略 benchmarks 字段。这是官方自己给自己的数据打的折扣。本文不写其中任何分数、名次与胜率。

per_request_limits 这一行的说明是「Rate limiting information (null if no limits)」——只告诉你有没有限制信息，没有限制时为 null。官方自述里那条「更高的速率上限」，在这两页里能核到的就只有这个字段的存在与它的空值语义；至于「更高」相对于什么、高多少，这两页没有给出可核的依据，我们不做任何推断。同样，「合并计费」「真实世界数据」这两条自述，在这两页里也没有对应的字段可核——《Principles》页把「真实世界数据」指向了平台自己的排行页面，那属于另一处内容，不在本文依据范围内。

反而是「标准化 API」这条自述，官方在《Models》页自己给它加了一个补丁。页面末尾那条 Note 写明：不同模型的分词方式不同，有的按多字符块切分，有的按字符切分，因此即使输入输出完全相同，token 计数（以及由此产生的成本）在模型之间也会不同，计费按所用模型的 tokenizer 来。文档给的处置是：用响应里的 usage 字段去拿输入与输出的实际 token 数。

这一条我建议认真对待：一个统一的 API 形状并不意味着统一的计量口径。要做成本核算，别拿自己那边的估算值去乘单价，读 usage。

命令行侧的两句提醒（通用做法，非官方文档内容）

上面几段的示例都是 curl。有一点和 OpenRouter 无关、但会真的绊到人，这里明确标注为命令行通用做法、不是 OpenRouter 官方文档的内容：

Linux / macOS：URL 里带 & 时要用引号包住整串，否则 & 会被 shell 当成后台执行符。文档里的示例本来就带引号，照抄即可。
Windows：PowerShell 里 curl 默认是 Invoke-WebRequest 的别名，行为与 curl 不同；要用真正的 curl 请显式调用 curl.exe。在 cmd 里，& 同样是命令分隔符，URL 必须加引号。

涉及鉴权的请求里，密钥一律用 <YOUR_API_KEY> 这类占位替代，不要写进会提交到仓库的脚本。

以上为按官方文档中的字段语义组合的示例，未经实测，以官方文档与 API 的实际响应为准。该平台迭代频繁，参数取值与字段说明随时可能变动，请以官方文档最新内容为准。

落到一句话

《Principles》页给的是六条官方自述，《Models》页给的是可以被程序读到的字段。两页并排看，能核到的部分集中在三处：pricing 是主供应商的价格而不是全平台价、overrides 用条件字段表达长上下文与分时计价且时间窗口铺满全天、canonical_slug 与 expiration_date 把「模型会改名、会下架」写进了 schema。核不到的部分也很清楚：速率上限、合并计费这些自述，在这两页里没有可验证的字段，就当作官方立场看待，别当成结论用。

本文依据 OpenRouter 官方文档（openrouter.ai/docs）于 2026-08-18 的公开内容整理。该平台闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观与运行表现的任何描述。该平台的供应商、模型与路由策略随时变动，文中不列具体供应商名单与模型清单；价格、额度与限流的具体数值请以官方定价页与用量说明为准。