From d5402f3a70fe86db320a1d4f5568082ff96c9b91 Mon Sep 17 00:00:00 2001
From: zhi <zhi@dev.hangman-lab.top>
Date: Wed, 11 Mar 2026 13:13:23 +0000
Subject: [PATCH] docs: add provider credential format guidance

---
 docs/monitor-provider-credentials.md | 55 ++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 docs/monitor-provider-credentials.md

diff --git a/docs/monitor-provider-credentials.md b/docs/monitor-provider-credentials.md
new file mode 100644
index 0000000..0eb4c3e
--- /dev/null
+++ b/docs/monitor-provider-credentials.md
@@ -0,0 +1,55 @@
+# Provider 账号凭证格式（Monitor）
+
+默认情况下，`credential` 可以直接填写 API Key 字符串。
+如果需要配置自定义 usage 端点，请使用 JSON 字符串。
+
+## 基础格式
+```json
+{
+  "api_key": "sk-...",
+  "usage_url": "https://.../usage",
+  "auth_header": "Authorization",
+  "auth_scheme": "Bearer"
+}
+```
+
+### 字段说明
+- `api_key`: API key（必填）
+- `usage_url`: 统计用量的 GET 端点（可选，minimax/kimi/qwen 推荐填写）
+- `auth_header`: 自定义鉴权头名（可选）
+- `auth_scheme`: 鉴权 scheme（如 `Bearer`），会拼成 `Bearer <api_key>`
+- `auth_value`: 直接指定头值（优先级高于 scheme）
+
+## OpenAI
+默认使用 OpenAI 官方 billing endpoints（7天窗口）：
+- `https://api.openai.com/v1/dashboard/billing/usage`
+- `https://api.openai.com/v1/dashboard/billing/subscription`
+
+如需自定义可使用 JSON：
+```json
+{
+  "api_key": "sk-...",
+  "usage_url": "https://api.openai.com/v1/dashboard/billing/usage?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD",
+  "subscription_url": "https://api.openai.com/v1/dashboard/billing/subscription"
+}
+```
+
+## Anthropic
+官方 usage API 需要自行提供 `usage_url`（不同组织可能不同）：
+```json
+{
+  "api_key": "ak-...",
+  "usage_url": "https://api.anthropic.com/.../usage"
+}
+```
+
+## Minimax / Kimi / Qwen
+目前需要你提供 `usage_url`（具体端点取决于部署/账号）：
+```json
+{
+  "api_key": "...",
+  "usage_url": "https://.../usage",
+  "auth_header": "Authorization",
+  "auth_scheme": "Bearer"
+}
+```