OpenRouter 入门与概览

OpenRouter 入门与概览

模型

3 分钟阅读

模型

一个 API，接入数百种模型

在 我们的网站 上浏览 400 多种模型和模型服务提供商，或 通过我们的 API 查询。你也可以订阅我们的 RSS feed，以跟踪新模型。

查询参数

模型 API 支持查询参数，用于筛选返回的模型列表。

output_modalities

按输出能力筛选模型。接受以逗号分隔的模态列表，或 "all" 以包含所有模型，无论输出类型如何。

值说明
text生成文本输出的模型（默认）
image生成图像的模型
audio生成音频输出的模型
embeddings嵌入模型
all包含所有模型，跳过模态筛选

示例：

# 默认（仅文本模型）
curl "https://openrouter.ai/api/v1/models"

# 仅图像生成模型
curl "https://openrouter.ai/api/v1/models?output_modalities=image"

# 文本和图像模型
curl "https://openrouter.ai/api/v1/models?output_modalities=text,image"

# 无论模态，包含所有模型
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

在返回前于服务端对模型排序。接受以下值之一：

值说明
pricing-low-to-high最便宜的模型优先（提示词、补全、请求和 web_search 价格的加权平均）
pricing-high-to-low最贵的模型优先
context-high-to-low最大上下文窗口优先
throughput-high-to-low最高 Token/秒优先（来自路由启发式的 p50 吞吐量）
latency-low-to-high最低首 Token 时间优先（p50 延迟）
most-popular过去一周处理的 Token 最多
top-weekly与 most-popular 相同
newest最近添加到 OpenRouter 的模型

在所请求的排序维度上没有数据的模型（例如没有定价、没有吞吐量启发式）会排在最后。省略 sort 会保留默认顺序（向后兼容）。

# 最便宜的模型优先
curl "https://openrouter.ai/api/v1/models?sort=pricing-low-to-high"

# 最新模型
curl "https://openrouter.ai/api/v1/models?sort=newest"

# 与筛选条件组合
curl "https://openrouter.ai/api/v1/models?sort=throughput-high-to-low&supported_parameters=tools"

查询单个模型

无需获取完整列表，即可查询单个模型的全部详情：

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

该端点会自动解析别名。例如，anthropic/claude-3-5-sonnet 会重定向到规范的 anthropic/claude-3.5-sonnet 并返回其数据。

也支持变体后缀。在 slug 后追加 :free、:thinking 等：

# 查询特定模型
curl "https://openrouter.ai/api/v1/model/openai/gpt-4o"

# 别名会自动解析
curl "https://openrouter.ai/api/v1/model/anthropic/claude-3-5-sonnet"

# 变体后缀
curl "https://openrouter.ai/api/v1/model/openai/gpt-4:free"

如果模型不存在，也不是其他模型的别名，则返回 404。响应形态会包装列表端点中使用的同一 Model 对象：

{
  "data": {
    "id": "openai/gpt-4o",
    "name": "GPT-4o",
    "pricing": { "prompt": "0.0000025", "completion": "0.00001", ... },
    ...
  }
}

模型 API 标准

我们的 模型 API 会在确认后，尽快免费提供所有大语言模型最重要的信息。

API 响应 Schema

模型 API 返回标准化的 JSON 响应格式，为每个可用模型提供全面的元数据。该 schema 缓存在边缘节点，专为与生产应用可靠集成而设计。

根响应对象

{
  "data": [
    /* Model 对象数组 */
  ],
  "total_count": 150,        // 匹配查询的模型总数
  "links": {
    "next": "/api/v1/models?offset=500&limit=500" // 下一页 URL；最后一页为 null
  }
}
分页

列表端点支持可选的 offset 和 limit 查询参数。分页是可选的：两者都省略时，会返回完整列表，且 links.next 为 null。启用分页时，limit 默认为 500（最大 1000），links.next 包含下一页可直接使用的 URL（最后一页为 null）：

curl "https://openrouter.ai/api/v1/models?offset=0&limit=500"

Model 对象 Schema

data 数组中的每个模型包含以下标准化字段：

字段类型说明
idstringAPI 请求中使用的唯一模型标识符（例如 "google/gemini-2.5-pro-preview"）
canonical_slugstring永不更改的模型永久 slug
namestring模型的人类可读显示名称
creatednumber模型添加到 OpenRouter 时的 Unix 时间戳
descriptionstring模型能力与特征的详细描述
context_lengthnumber最大上下文窗口大小（以 Token 计）
architectureArchitecture描述模型技术能力的对象
pricingPricing该模型排名最前的服务提供商的定价
top_providerTopProvider主要服务提供商的配置详情
per_request_limits速率限制信息（无限制时为 null）
supported_parametersstring[]该模型支持的 API 参数数组
default_parametersobject | null该模型的默认参数值（没有则为 null）
expiration_datestring | null模型端点的弃用日期（未弃用则为 null）
benchmarksBenchmarks | undefined第三方基准测试排名（无数据时省略）

Architecture 对象

{
  "input_modalities": string[], // 支持的输入类型：["file", "image", "text"]
  "output_modalities": string[], // 支持的输出类型：["text"]
  "tokenizer": string,          // 使用的分词方法
  "instruct_type": string | null // 指令格式类型（不适用时为 null）
}

Pricing 对象

所有定价值均为美元，按 Token / 请求 / 单位计。值为 "0" 表示该功能免费。

{
  "prompt": string,           // 每个输入 Token 的费用
  "completion": string,       // 每个输出 Token 的费用
  "request": string,          // 每次 API 请求的固定费用
  "image": string,           // 每个图像输入的费用
  "web_search": string,      // 每次网络搜索操作的费用
  "internal_reasoning": string, // 内部推理 Token 的费用
  "input_cache_read": string,   // 每个缓存输入 Token 读取的费用
  "input_cache_write": string,  // 每个缓存输入 Token 写入的费用
  "overrides": PricingOverride[] // 可选的条件定价覆盖（见下文）
}
定价覆盖

某些端点会在特定条件下收取不同费率。例如，超过 Token 阈值后的长上下文定价，或高峰时段更贵的分时定价。这些会出现在可选的 pricing.overrides 数组中：

{
  // 条件：当提示词 Token 总数严格大于此阈值时适用
  "min_prompt_tokens": 200000,

  // 条件：当前 UTC 时间落在此每日窗口内时适用
  "utc_start": 1630,  // 包含起始，HHMM 时钟（16:30 UTC）
  "utc_end": 30,      // 不包含结束，HHMM 时钟（00:30 UTC；窗口可以跨过午夜）

  // 覆盖后的价格，键和单位与基础定价对象相同
  "prompt": "0.000005",
  "completion": "0.00002",
  "input_cache_read": "0.0000005",
  "input_cache_write": "0.00000625"
}

当某条目的所有条件字段都与请求匹配时，该条目生效。多个条目同时适用时，靠后的条目按键胜出。条目中缺失的价格键继承基础价格。顶层定价键始终反映默认条件下适用于请求的价格；overrides 承载有条件的例外。

例如，一个模型通常按每百万输入 Token $2.50 收费，超过 200K 提示词 Token 后按每百万 $5 收费：

"pricing": {
  "prompt": "0.0000025",
  "completion": "0.00001",
  "overrides": [
    {
      "min_prompt_tokens": 200000,
      "prompt": "0.000005",
      "completion": "0.00002"
    }
  ]
}

时间窗口条件用于表达高峰 / 非高峰定价。overrides 数组始终列出每一个窗口（高峰和非高峰），铺满完整的 24 小时。这意味着无论响应是何时生成的，完整时间表都可以还原。例如，一个模型在 16:30 到 00:30 UTC 之间收取半价：

"pricing": {
  // 顶层价格始终反映此刻适用的窗口
  // （此处：当前 UTC 时间在 00:30 到 16:30 之间）
  "prompt": "0.00000028",
  "completion": "0.00000042",
  "overrides": [
    {
      "utc_start": 30,
      "utc_end": 1630,
      "prompt": "0.00000028",
      "completion": "0.00000042"
    },
    {
      "utc_start": 1630,
      "utc_end": 30,
      "prompt": "0.00000014",
      "completion": "0.00000021"
    }
  ]
}

Top Provider 对象

{
  "context_length": number,        // 服务提供商特定的上下文限制
  "max_completion_tokens": number, // 响应中的最大 Token 数
  "is_moderated": boolean         // 是否应用内容审核
}

Benchmarks 对象

仅出现在已参加第三方基准测试评估的模型上。目前包括 Design Arena 排名。

{
  "design_arena": [
    {
      "arena": string,    // Arena 类型（例如 "models"、"builders"、"agents"）
      "category": string, // Arena 内的分类（例如 "website"、"gamedev"）
      "elo": number,      // 来自两两对战的 ELO 评分
      "win_rate": number,  // 胜率百分比
      "rank": number      // 该 arena+category 内的排名（1 = ELO 最高）
    }
  ]
}

排名是在 OpenRouter 上架的模型之间计算的，而不是完整的外部排行榜。没有基准测试数据的模型会完全省略 benchmarks 字段。

# 查找包含基准测试数据的模型
curl -s "https://openrouter.ai/api/v1/models" | jq '.data[] | select(.benchmarks) | {id, benchmarks}'

支持的参数

supported_parameters 数组标明每个模型可用的 OpenAI 兼容参数：

  • tools - 函数调用能力
  • tool_choice - 工具选择控制
  • max_tokens - 限制响应长度
  • temperature - 随机性控制
  • top_p - 核采样
  • reasoning - 内部推理模式
  • include_reasoning - 在响应中包含推理过程
  • structured_outputs - JSON schema 强制约束
  • response_format - 输出格式规范
  • stop - 自定义停止序列
  • frequency_penalty - 降低重复
  • presence_penalty - 主题多样性
  • seed - 确定性输出

不同模型以不同方式对文本分词

有些模型会把文本拆成多个字符组成的块（GPT、Claude、 Llama 等），另一些则按字符分词（PaLM）。这意味着即使输入和 输出相同，Token 计数（以及因此产生的费用）也会因模型而异。费用按 所用模型的分词器显示和计费。你可以使用响应中的 usage 字段 获取输入和输出的 Token 计数。

如果你感兴趣的模型或服务提供商尚未出现在 OpenRouter 上，请在我们的 Discord 频道 告诉我们。

面向服务提供商

如果你有兴趣与 OpenRouter 合作，可以在我们的 服务提供商页面 了解更多。

上一页设计原则下一页 MCP 服务器