账单对账与用量自动同步
如果你需要把 AIone 的消费数据同步进自己的财务/监控系统（每日对账、余额告警、按模型分摊成本），不必人工登录控制台导出。平台提供两条程序化查询通道，按需组合即可实现全自动对账：
| 通道 | 凭据 | 适合场景 |
|---|---|---|
① API 令牌直查（/v1/dashboard/billing/*） |
你的 sk-nex- API 令牌 |
余额监控、额度告警、查看本月消耗总额。零登录，可直接接入 one-api / new-api 生态的余额查询工具 |
② 账号登录拉明细（/api/v1/obs/*、/api/v1/billing/*） |
控制台账号（邮箱 + 密码） | 逐笔明细对账：按日 / 按模型 / 按 Key 聚合，CSV / XLSX 导出，账务流水与账单 |
对账口径：两条通道读取的是同一份计费事实（
usage_ledger逐请求账目），金额单位均为 USD，月边界按你组织设置的时区计算。导出明细中逐笔cost_usd之和即为账单金额，不存在第二套口径。
一、API 令牌直查余额（推荐日常监控）
Base URL：https://api.portal.aiin1.ai。鉴权与调用模型接口完全一致（Authorization: Bearer sk-nex-...，受 API Key 的 IP 白名单约束），响应为 OpenAI 兼容格式。
1.1 查询额度汇总：GET /v1/dashboard/billing/credit_grants
curl https://api.portal.aiin1.ai/v1/dashboard/billing/credit_grants \
-H "Authorization: Bearer sk-nex-your-key-here"{
"object": "credit_summary",
"total_granted": 1000.0,
"total_used": 137.42,
"total_available": 862.58,
"grants": { "object": "list", "data": [] }
}字段含义随你的计费模式而定：
| 计费模式 | total_available |
total_used |
total_granted |
|---|---|---|---|
| 预付费（prepaid） | 实时可用余额 | 本月已消耗 | 余额 + 本月已消耗 |
| 后付费 / 混合（postpaid / hybrid） | 信用额度 − 本月敞口 | 本月敞口（= 本月消耗 − 本月已确认付款） | 信用额度 |
1.2 查询套餐额度：GET /v1/dashboard/billing/subscription
curl https://api.portal.aiin1.ai/v1/dashboard/billing/subscription \
-H "Authorization: Bearer sk-nex-your-key-here"{
"object": "billing_subscription",
"has_payment_method": true,
"soft_limit_usd": 862.58,
"hard_limit_usd": 862.58,
"system_hard_limit_usd": 862.58,
"plan": { "title": "prepaid", "id": "prepaid" }
}hard_limit_usd 是当前的消费上限：后付费 / 混合模式下为信用额度，预付费模式下为当前可用余额。
这两个端点与 OpenAI 官方旧版账单接口同构,市面上支持"查询 OpenAI 余额"的工具（浏览器插件、new-api / one-api 的渠道余额监控等）把 Base URL 指向
https://api.portal.aiin1.ai即可直接使用。
二、账号登录拉取明细（对账 / 导出）
明细数据挂在控制台后端 API 下，Base URL：https://portal.aiin1.ai/api/v1。鉴权方式是短期会话令牌：用控制台账号登录一次，拿到 15 分钟有效的 access_token，对账脚本在这 15 分钟内完成全部拉取即可，无需实现令牌刷新。
建议：为对账创建一个专用的普通成员账号（控制台 → 团队成员 → 邀请），不要开启两步验证（TOTP）。开启 TOTP 的账号登录时必须额外提供
totp_code动态码，不适合脚本调用。限流提示：登录接口按来源 IP 限流。正确姿势是"登录一次 → 复用 token 拉完所有数据"，不要每个请求都重新登录。
2.1 登录：POST /auth/login
TOKEN=$(curl -s https://portal.aiin1.ai/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{ "email": "billing-bot@yourcompany.com", "password": "YOUR_PASSWORD" }' \
| jq -r .access_token)响应：
{ "access_token": "eyJhbGci...", "token_type": "bearer", "expires_in": 900 }后续请求统一携带 Authorization: Bearer $TOKEN。
2.2 用量聚合：GET /obs/usage
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
start / end |
date | 否 | 起止日期（YYYY-MM-DD，含两端），必须成对出现，跨度 ≤ 365 天，end 不能是未来日期。不传则用 range_days |
range_days |
int | 否 | 最近 N 天（默认 7） |
group |
string | 否 | 聚合维度：date（默认）/ model / team / key / owner；支持逗号组合做多维交叉（如 group=model,key），group_key 按顺序以 | 拼接 |
model |
string | 否 | 按模型名过滤 |
apikey_id |
uuid | 否 | 按 API Key 过滤 |
team_id |
uuid | 否 | 按团队过滤 |
curl -s "https://portal.aiin1.ai/api/v1/obs/usage?start=2026-07-01&end=2026-07-31&group=model" \
-H "Authorization: Bearer $TOKEN"响应为数组，每行字段：
| 字段 | 说明 |
|---|---|
group_key / group_name |
聚合键（日期、模型名、团队 / Key 的 ID 与名称） |
request_count |
请求数 |
prompt_tokens / completion_tokens / total_tokens |
输入 / 输出 / 总 token |
cache_creation_input_tokens / cache_read_input_tokens |
缓存写入 / 命中 token |
cost_usd |
消费金额（USD） |
avg_latency_ms / error_count |
平均延迟 / 错误数 |
2.3 逐笔明细导出：GET /obs/usage/export（CSV）
参数：start、end（必填），可选 model / apikey_id / team_id 过滤。直接返回 CSV 流：
curl -s "https://portal.aiin1.ai/api/v1/obs/usage/export?start=2026-07-01&end=2026-07-31" \
-H "Authorization: Bearer $TOKEN" -o usage-202607.csvCSV 列：occurred_at, request_id, trace_id, model, apikey_id, team_id, subscription_id, prompt_tokens, completion_tokens, cache_creation_input_tokens, cache_read_input_tokens, total_tokens, latency_ms, status_code, error_code, input_per_1m_usd, output_per_1m_usd, cache_write_per_1m_usd, cache_read_per_1m_usd, price_multiplier, cost_usd
每行是一次请求：既有 token 事实，也有当次生效的单价与折扣（*_per_1m_usd 为目录价，price_multiplier 为你的折扣系数），可独立复算 cost_usd。时间列按组织时区渲染。
同路径还提供 Excel 版本：GET /obs/usage/export.xlsx（明细）与 GET /obs/usage/stats.xlsx（统计），参数相同。
2.4 账务与账单
| 端点 | 说明 |
|---|---|
GET /billing/account |
账户快照：billing_mode、credit_balance_usd、credit_limit_usd |
GET /billing/ledger?page=1&page_size=100 |
账务流水（充值 / 扣费 / 调整），字段含 type、direction、amount_usd、balance_after_usd、description、created_at |
GET /billing/invoices?start=&end=&page=&page_size= |
账单列表：invoice_no、period_start/end、total、status、due_date |
GET /billing/invoices/{id} |
账单详情（含明细行） |
GET /billing/invoices/{id}/pdf |
账单 PDF 下载 |
2.5 完整示例：每日 T+1 对账脚本
#!/usr/bin/env bash
set -euo pipefail
BASE="https://portal.aiin1.ai/api/v1"
DAY=$(date -d "yesterday" +%F 2>/dev/null || date -v-1d +%F)
TOKEN=$(curl -sf "$BASE/auth/login" -H "Content-Type: application/json" \
-d "{\"email\":\"$BILLING_EMAIL\",\"password\":\"$BILLING_PASSWORD\"}" | jq -r .access_token)
# 昨日逐笔明细 CSV
curl -sf "$BASE/obs/usage/export?start=$DAY&end=$DAY" \
-H "Authorization: Bearer $TOKEN" -o "usage-$DAY.csv"
# 昨日按模型汇总
curl -sf "$BASE/obs/usage?start=$DAY&end=$DAY&group=model" \
-H "Authorization: Bearer $TOKEN" > "usage-$DAY-by-model.json"
# 当前余额（走 API 令牌通道，也可放进独立的余额告警任务）
curl -sf https://api.portal.aiin1.ai/v1/dashboard/billing/credit_grants \
-H "Authorization: Bearer $NEXARA_API_KEY" > "balance-$DAY.json"三、常见问题
Q：两条通道的数字会对不上吗？
不会。余额通道的"本月已消耗"和明细通道逐笔 cost_usd 之和来自同一张账目表，口径一致。唯一注意点是时区：月边界与明细时间列都按你组织设置的时区计算，你自己系统里的聚合请使用同一时区。
Q：access_token 过期了怎么办？ 它只有 15 分钟有效期，这是有意为之——对账脚本应当"登录 → 拉取 → 结束"。如果单次拉取超过 15 分钟（极大范围导出），拆分日期区间分批拉取即可。
Q：可以用 sk-nex- 令牌直接拉明细吗？
目前明细通道仅支持账号登录。若你的场景强需要"令牌直查明细"，请联系我们。