OpenRouter 支持通过 HTTP 请求头标识你的应用——设置 HTTP-Referer（必填）和 X-OpenRouter-Title（可选）后，你的应用会出现在 openrouter.ai/rankings 排行榜，并可查看详细的模型用量分析。还可以通过 X-OpenRouter-Categories 声明应用类型，加入对应分类排名。本页提供完整的头部配置说明和代码示例。

应用归因（App Attribution）让开发者将 API 请求与具体应用关联，在 OpenRouter 的排行榜和分析页面追踪应用的 token 用量。

实现方式

在每次 API 请求中添加以下 HTTP 头：

请求头	是否必填	说明
HTTP-Referer	必填	你的应用 URL（如 https://myapp.com）
X-OpenRouter-Title	可选	应用显示名称
X-OpenRouter-Categories	可选	应用类别（逗号分隔）

HTTP-Referer 是创建应用页面并出现在排行榜的最低要求。只设置 X-OpenRouter-Title 而不设置 URL 不会创建应用条目。

应用类别

通过 X-OpenRouter-Categories 声明应用所属类别：

Coding — 开发类工具：

• cli-agent — 命令行 agent
• cloud-agent — 云端 agent
• coding-assistant — 编程助手
• programming-app — 编程应用
• native-app-builder — 移动端/桌面端应用构建器

Creative — 创意类应用：

• creative-writing — 创意写作
• video-gen — 视频生成
• image-gen — 图像生成

Productivity — 效率类工具：

• writing-assistant — AI 写作工具
• general-chat — 通用聊天
• personal-agent — 个人 AI 助手

Entertainment — 娱乐类：

• roleplay — 角色扮演
• game — 游戏和互动娱乐

仅识别以上列表中的类别，未知值会被静默忽略。

代码示例

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
  defaultHeaders: {
    'HTTP-Referer': 'https://myapp.com',        // 你的应用 URL
    'X-OpenRouter-Title': 'My AI Assistant',    // 你的应用名称
    'X-OpenRouter-Categories': 'cli-agent,cloud-agent',  // 可选类别
  },
});

const completion = await openRouter.chat.send({
  model: 'openai/gpt-5.2',
  messages: [
    {
      role: 'user',
      content: 'Hello, world!',
    },
  ],
  stream: false,
});

console.log(completion.choices[0].message);

应用出现的位置

应用排行榜

归因后的应用会出现在 openrouter.ai/rankings，包括：

• Top Apps：按 token 用量排名的公开应用
• 时间维度：日榜、周榜、月榜
• 用量指标：跨所有模型的总 token 消耗

模型页面的 Apps 标签

在单个模型页面（如 GPT-4o），你的应用会出现在"Apps"标签中，展示：

• Top Apps：使用该模型最多的应用
• 周榜：每周更新
• 用量对比：与使用同一模型的其他应用的对比

独立应用分析页

应用被追踪后，可在 openrouter.ai/apps?url=<your-app-url> 查看详细分析，包括：

• 模型用量趋势：各模型的历史使用图表
• Token 消耗：prompt 和 completion token 的详细拆分
• 用量规律：历史数据帮助理解应用的 AI 用量模式

最佳实践

URL 要求

• 始终包含 HTTP-Referer——这是应用归因的最低要求
• 使用应用的主域名（如 https://myapp.com）
• 除非代表独立应用，否则避免使用子域名
• localhost 开发环境必须同时设置 X-OpenRouter-Title
• 在 openrouter.ai/apps?url=<your-referer-url> 查看你的应用页面

名称规范

• 名称简洁且描述性强
• 使用用户已知的实际应用名称
• 避免"AI App"或"Chatbot"等通用名称

常见问题

Q: localhost 开发时也能测试归因吗？

A: 可以，但 localhost URL 必须同时设置 X-OpenRouter-Title 才能被追踪。生产部署后换成真实域名，数据会自动关联。

Q: 应用的 token 用量是否会公开？

A: 只有设置了 HTTP-Referer 的公开应用会出现在排行榜。应用的用量数据对外展示，但不包含请求的具体内容。

Q: 排行榜多久更新一次？

A: 日榜每天更新，周榜每周更新，月榜每月更新。新应用可能需要一段时间才会出现在排行榜中。