請求照合と使用量の自動同期
AIone の利用金額データを自社の財務・監視システムに取り込みたい場合（日次照合、残高アラート、モデル別コスト配賦など）、コンソールに手動ログインしてエクスポートする必要はありません。プラットフォームは 2 つのプログラマティックな照会チャネルを提供しており、組み合わせることで完全自動の照合が実現できます。
| チャネル | 認証情報 | 適した用途 |
|---|---|---|
① API トークン直接照会（/v1/dashboard/billing/*） |
お手元の sk-nex- API トークン |
残高監視、クォータアラート、当月消費合計の確認。ログイン不要。one-api / new-api エコシステムの残高照会ツールがそのまま使えます |
② アカウントログインで明細取得（/api/v1/obs/*、/api/v1/billing/*） |
コンソールアカウント（メール + パスワード） | 明細単位の照合：日別 / モデル別 / キー別集計、CSV / XLSX エクスポート、取引履歴と請求書 |
照合の基準：両チャネルは同一の課金ファクト（リクエスト単位の
usage_ledger）を読み取ります。金額はすべて USD、月の境界は組織に設定されたタイムゾーンに従います。明細エクスポートのcost_usdの合計がそのまま請求金額であり、二重帳簿は存在しません。
一、API トークンによる残高直接照会（日常監視に推奨）
Base URL：https://api.portal.aiin1.ai。認証はモデル呼び出しと完全に同じです（Authorization: Bearer sk-nex-...、API キーの 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 の旧課金 API と同じ構造のため、「OpenAI 残高照会」に対応したツール（ブラウザ拡張、new-api / one-api のチャネル残高監視など）は Base URL を
https://api.portal.aiin1.aiに向けるだけで動作します。
二、アカウントログインによる明細取得（照合 / エクスポート）
明細データはコンソールバックエンド API（Base URL：https://portal.aiin1.ai/api/v1）にあります。認証は短期セッショントークン方式です：コンソールアカウントで 1 回ログインし、15 分間有効な access_token を取得、その時間内に必要な取得をすべて完了させます。トークンリフレッシュの実装は不要です。
推奨：照合専用の一般メンバーアカウントを作成し（コンソール → チームメンバー → 招待）、二要素認証（TOTP）は有効にしないでください。TOTP 有効のアカウントはログイン時に
totp_codeの入力が必要となり、スクリプトには不向きです。レート制限：ログインエンドポイントは送信元 IP ごとにレート制限されています。「1 回ログイン → トークンを使い回して全データ取得」が正しいパターンです。リクエストごとの再ログインは避けてください。
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 キーで絞り込み |
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 |
集計キー（日付、モデル名、チーム / キーの ID と名前） |
request_count |
リクエスト数 |
prompt_tokens / completion_tokens / total_tokens |
入力 / 出力 / 合計トークン |
cache_creation_input_tokens / cache_read_input_tokens |
キャッシュ書き込み / ヒットトークン |
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
1 行 = 1 リクエストで、トークン実績に加えそのリクエスト時点で適用された単価と割引（*_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"
# 現在残高（トークンチャネル。独立した残高アラートジョブにも適します）
curl -sf https://api.portal.aiin1.ai/v1/dashboard/billing/credit_grants \
-H "Authorization: Bearer $NEXARA_API_KEY" > "balance-$DAY.json"三、よくある質問
Q：2 つのチャネルの数字が食い違うことはありますか？
ありません。残高チャネルの「当月消費額」と明細チャネルの cost_usd 合計は同一の帳簿に由来し、基準は一致しています。唯一の注意点はタイムゾーンです：月の境界と明細の時刻列は組織に設定されたタイムゾーンに従うため、貴社側で集計する際も同じタイムゾーンを使用してください。
Q：access_token の有効期限が切れたら？ 有効期間は意図的に 15 分としています。照合スクリプトは「ログイン → 取得 → 終了」で完結すべきです。1 回の取得が 15 分を超える場合（非常に大きな範囲のエクスポート）は、日付範囲を分割してバッチで取得してください。
Q：sk-nex- トークンで明細を直接取得できますか？
明細チャネルは現在アカウントログインのみ対応です。トークンによる明細照会が強く必要な場合はお問い合わせください。