用途
openrouter-usage 用于在命令行中查询 OpenRouter API 的费用与用量，并生成使用报告。适合需要检查 OpenRouter 支出、按模型/提供商/日期拆分费用、导出用量数据用于记账，或审计哪些模型与 API 密钥消耗最多积分的人。
前提条件
- 需要 OPENROUTER_API_KEY 环境变量（或放在项目的 .env 文件中）。
- 该密钥必须是 Management key，可在 https://openrouter.ai/settings/management-keys 创建。
- 普通的 provisioning key 在分析类接口上会返回 401/403。
使用方式
脚本路径为 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py，可通过 python3 运行，常见用法如下：
# Full 30-day summary with credits balance
python3 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py
# Filter to a single date
python3 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py --date 2026-02-01
# Export as CSV (for spreadsheets)
python3 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py --csv
# Raw JSON output (for piping to jq)
python3 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py --json
# Skip credits lookup (activity only)
python3 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py --no-credits
主要能力与输出
默认报告包含：
- 积分余额：总购买、已使用、剩余。
- 按模型的费用：每个模型的费用及 token 数量（prompt、completion、reasoning）。
- 按提供商的费用：按提供商聚合（OpenAI、Anthropic、Google 等）。
- 按日期的费用：每日花费并带可视化柱状图。
API 端点
两个端点均为只读 GET，通过 Bearer token 认证：
| Endpoint | Purpose |
|---|---|
| GET /api/v1/credits | Total credits purchased and used |
| GET /api/v1/activity | Last 30 days of usage grouped by model/endpoint/provider |
活动接口每行返回：date、model、provider_name、usage、byok_usage_inference、requests、prompt_tokens、completion_tokens、reasoning_tokens。
适用场景
- 查看 OpenRouter 最近 30 天的花费。
- 按模型、提供商或日期拆分费用。
- 将用量数据导出为 CSV 或 JSON 以用于会计。
- 审计哪些模型和 API 密钥消耗了最多积分。
限制
必须使用 Management key，否则分析接口会返回 401/403；脚本依赖 Python 3 运行环境；文档未提供其他平台或界面支持信息。