App Attribution

让你的应用出现在 OpenRouter 排名和分析中

原文链接：https://openrouter.ai/docs/app-attribution

App attribution 允许开发者将 API 使用与他们的应用程序关联，从而能够在 OpenRouter 的公开排名和详细分析中获得可见性。通过在请求中包含简单的 headers，你的应用可以出现在我们的排行榜上，并深入了解你的模型使用模式。

App Attribution 的优势

正确归因你的应用使用后，你可以访问：

公开应用排名：你的应用出现在 OpenRouter 的公开排名中，包含每日、每周和每月排行榜
模型应用标签：你的应用在显示使用每个模型最多的应用的单独模型页面上有特色
详细分析：访问显示你的应用随时间的模型使用情况、token 消耗和使用模式的综合分析
专业可见性：向 OpenRouter 开发者社区展示你的应用

Attribution Headers

OpenRouter 通过以下 HTTP headers 跟踪 app attribution：

HTTP-Referer（必需）

HTTP-Referer header 标识你的应用 URL，并用作排名中的主要标识符。此 header 是 app attribution 所必需的——没有它，不会创建应用页面，你的使用也不会出现在排名中。你的应用 URL 成为系统中的唯一标识符。

X-OpenRouter-Title

X-OpenRouter-Title header 在排名和分析中设置或修改你应用的显示名称。X-Title 仍然支持以保持向后兼容性。此 header 单独不会创建应用页面——必须与 HTTP-Referer 配对。

X-OpenRouter-Categories

X-OpenRouter-Categories header 将你的应用分配到一个或多个 marketplace categories。传递最多 2 个 categories 的逗号分隔列表。Categories 必须小写、连字符分隔，每个 category 限制为 30 个字符。只有以下列表中的公认 categories 会被接受；无法识别的会被静默忽略。Categories 会与现有 categories 合并（最多 10 个）。

Category Groups

Categories 按 marketplace 分组：

Coding — 软件开发工具：

cli-agent — 终端编码助手
ide-extension — 编辑器/IDE 集成
cloud-agent — 云托管编码代理
programming-app — 编程应用
native-app-builder — 移动和桌面应用构建器

Creative — 创意应用：

creative-writing — 创意写作工具
video-gen — 视频生成应用
image-gen — 图像生成应用

Productivity — 写作和生产力工具：

writing-assistant — AI 写作工具
general-chat — 通用聊天应用
personal-agent — 个人 AI 代理

Entertainment — 娱乐应用：

roleplay — 角色扮演应用和其他基于角色的聊天应用
game — 游戏和互动娱乐应用

自定义 Categories

只接受列表中公认的 categories。无法识别的值会被静默删除。如果你有不符合现有 categories 的用例，请联系我们，我们将来可能会添加新 categories。

HTTP-Referer 是必需的才能创建应用页面并出现在排名中。仅设置 X-OpenRouter-Title 而没有 URL 不会创建应用条目。使用 localhost URL 的应用还必须包含 X-OpenRouter-Title 才能被跟踪。

实现示例

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

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
  defaultHeaders: {
    'HTTP-Referer': 'https://myapp.com', // Your app's URL
    'X-OpenRouter-Title': 'My AI Assistant', // Your app's display name
    'X-OpenRouter-Categories': 'cli-agent,cloud-agent', // Optional categories
  },
});

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 的 OpenRouter 主排名页面。排名显示：

Top Apps：按 token 使用量排列的最大公开应用
Time Periods：每日、每周和每月视图
Usage Metrics：跨所有模型的总 token 消耗

模型应用标签

在单独模型页面（例如 GPT-4o）上，你的应用将在显示使用该特定模型最多的应用的"Apps"标签中有特色：

Top Apps：使用该特定模型最多的应用
Weekly Rankings：基于使用情况每周更新
Usage Context：你的应用与其他使用相同模型的应用的比较

单独应用分析

一旦你的应用被跟踪，你可以在 openrouter.ai/apps?url=<your-app-url> 访问详细分析，包括：

Model Usage Over Time：显示你的应用使用哪些模型的图表
Token Consumption：prompt 和 completion tokens 的详细分解
Usage Patterns：了解你的应用 AI 使用趋势的历史数据

最佳实践

URL 要求

始终包含 HTTP-Referer — 这是 app attribution 的最低要求
使用你应用的主域名（例如 https://myapp.com）
除非代表不同的应用，否则避免使用子域名
对于 localhost 开发，同时包含 X-OpenRouter-Title
你可以在 openrouter.ai/apps?url=<your-referer-url> 查看你的应用页面

标题指南

保持标题简洁且描述性强
使用用户实际知道的应用名称
避免使用"AI App"或"Chatbot"等通用名称

隐私注意事项

只有公开应用，即发送 headers 的应用，才会包含在排名中
Attribution headers 不会暴露有关你请求的敏感信息