帳單 API

將你自己工作區的用量與費用資料擷取到你自己的系統中，無需開啟控制台。帳單金鑰是一種 唯讀 憑證，作用範圍僅限一個工作區 - 它只能讀取帳單資料，不能做別的事。

建立帳單金鑰

1. 開啟 Console → Billing API keys （僅工作區所有者可用）。為其命名，可選擇限制到 IP 白名單或設定到期時間，然後複製金鑰 - 它以 sk-syn-bill- 並且只會顯示一次。
2. 將其作為 Bearer token 呼叫下方各端點。 可隨時在同一頁面撤銷它 - 撤銷會立即使其失效，且不影響工作區中的任何其他內容。
3. 金鑰與其建立者綁定：如果該建立者不再是工作區所有者，金鑰會停止運作並回傳 403 key_owner_not_authorized.

驗證

每次呼叫都需要 Authorization: Bearer sk-syn-bill-... ，並針對下方的 base URL 發起請求。帳單金鑰只能用於這些端點，而這些端點也只接受帳單金鑰 - 任何其他組合都會回傳 401 wrong_key_kind.

Authorization: Bearer sk-syn-bill-...

Base URL: https://synthorai.io/api/v1/billing

GET /usage - 匯總用量

GET /usage

按小時或按天預先彙總的資料，適合對帳與儀表板。資料來自小時彙總表，並補上自上次彙總以來新寫入的請求，因此最近的時間桶不會整整落後一個彙總週期。

在每一行中，api_key_id 與 api_key_name 只有在 group_by 包含 api_key 時才會出現，model 同理只有在包含 model 時才會出現。當某個桶沒有延遲取樣時，avg_latency_ms 可能為 null。

範例請求

curl "https://synthorai.io/api/v1/billing/usage?start=2026-09-01&end=2026-09-24&granularity=day" \
  -H "Authorization: Bearer sk-syn-bill-..."

範例回應

{
  "data": [
    {
      "bucket_start": "2026-09-23T00:00:00Z",
      "bucket_end": "2026-09-24T00:00:00Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "requests": 1280,
      "success_requests": 1265,
      "error_requests": 15,
      "errors_4xx": 12,
      "errors_429": 2,
      "errors_5xx": 1,
      "prompt_tokens": 512000,
      "completion_tokens": 98000,
      "cached_tokens": 210000,
      "cache_write_tokens": 8000,
      "reasoning_tokens": 4000,
      "cost_usd": 4.1732,
      "byok_list_price_usd": 0,
      "byok_requests": 0,
      "avg_latency_ms": 812,
      "final": true
    }
  ],
  "meta": {
    "generated_at": "2026-09-24T08:00:00Z",
    "data_complete_until": "2026-09-24T06:00:00Z",
    "timezone": "UTC",
    "currency": "USD",
    "next_cursor": null,
    "has_more": false
  }
}

GET /records - 逐請求行

GET /records

每個請求一行，用於增量同步到你自己的資料庫。請按 cursor 同步，絕不要按時間同步，並按 record_id 對收到的行去重 - 原因見下方「避免時間間隙」。

範例請求

curl "https://synthorai.io/api/v1/billing/records?start=2026-09-24T00:00:00Z&limit=500" \
  -H "Authorization: Bearer sk-syn-bill-..."

範例回應

{
  "data": [
    {
      "record_id": "rec_8f2a91c4",
      "request_id": "req_9f3c2b1a",
      "recorded_at": "2026-09-24T05:58:31Z",
      "completed_at": "2026-09-24T05:58:29Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "status": "success",
      "status_code": 200,
      "prompt_tokens": 812,
      "completion_tokens": 194,
      "cached_tokens": 512,
      "cache_write_tokens": 64,
      "cache_write_5m_tokens": 64,
      "cache_write_1h_tokens": 0,
      "cost_usd": 0.00412,
      "byok_list_price_usd": 0,
      "is_byok": false,
      "is_stream": true,
      "duration_ms": 1340,
      "ttft_ms": 210
    }
  ],
  "meta": {
    "next_cursor": "eyJvIjoiODgxNDA5MCJ9",
    "has_more": false,
    "window_final": true,
    "safe_until": "2026-09-24T05:58:31Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "data_complete_until": "2026-09-24T05:58:00Z"
  }
}

GET /records/export - 串流匯出

GET /records/export

篩選條件與 /records 相同，以換行分隔的 JSON（application/x-ndjson）串流回傳 - 專為大量補齊歷史資料設計，而非分頁列表。每個工作區同一時間只能有一個匯出串流；第二個會收到 429 too_many_concurrent_requests。

範例請求

curl -N "https://synthorai.io/api/v1/billing/records/export?cursor=eyJvIjoiODgxNDAzMiJ9" \
  -H "Authorization: Bearer sk-syn-bill-..."

範例回應

{"record_id":"rec_8f2a91c4","request_id":"req_9f3c2b1a","model":"claude-sonnet-5","status":"success","cost_usd":0.00412}
{"record_id":"rec_8f2a91c5","request_id":"req_9f3c2b1b","model":"claude-sonnet-5","status":"success","cost_usd":0.00398}
{"_meta":{"next_cursor":"eyJvIjoiODgxNDA5MSJ9","rows":2,"complete":true,"window_final":true,"generated_at":"2026-09-24T06:00:02Z"}}

該串流的最後一行是一個 _meta 物件：

GET /summary - 初步統計與異常

GET /summary

總量、按費用排名的模型與金鑰，以及該範圍的錯誤率，再加上一個 anomalies 清單（high_error_rate、rate_limited、data_not_final、rollup_delayed），每一項都帶有 info 或 warning 的嚴重級別以及一段易讀的說明文字。尚未定稿範圍內的數字仍可能變動 - 見下文。

models_count 與 keys_count 給出 top_models 與 top_keys 背後的總數，而這兩個清單最多列出按費用排名前 20 的項目。範圍預設為 end 之前的 30 天，用於 start 被省略的情況。

範例請求

curl "https://synthorai.io/api/v1/billing/summary?start=2026-09-17&end=2026-09-24" \
  -H "Authorization: Bearer sk-syn-bill-..."

範例回應

{
  "data": {
    "totals": { "requests": 48210, "cost_usd": 132.55, "error_rate": 0.021 },
    "models_count": 6,
    "keys_count": 3,
    "top_models": [ { "model": "claude-sonnet-5", "cost_usd": 88.10, "byok_list_price_usd": 0 } ],
    "top_keys": [ { "api_key_id": 42, "api_key_name": "prod-backend", "cost_usd": 61.30, "byok_list_price_usd": 0 } ],
    "anomalies": [
      { "type": "data_not_final", "severity": "info", "message": "The last 2 hours of this range are not yet final." }
    ]
  },
  "meta": {
    "generated_at": "2026-09-24T06:00:02Z",
    "data_complete_until": "2026-09-24T04:00:00Z"
  }
}

GET /freshness - 資料完整度

GET /freshness

回傳 data_complete_until, latest_recorded_at, safe_until 和 pipeline_lag_seconds - 在把剛剛擷取的範圍視為已定稿之前，請先輪詢這個端點。safe_until 是呼叫方可信為已完整的最新 recorded_at；比它更新的行可能仍在到達中。

範例請求

curl "https://synthorai.io/api/v1/billing/freshness" \
  -H "Authorization: Bearer sk-syn-bill-..."

範例回應

{
  "data": {
    "data_complete_until": "2026-09-24T04:00:00Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "safe_until": "2026-09-24T05:58:31Z",
    "pipeline_lag_seconds": 47
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z" }
}

GET /balance - 工作區目前可用餘額

GET /balance

回傳工作區目前可用餘額，與主控台顯示的可用餘額一致。專為輪詢設計：每 30 到 60 秒查一次就足夠。它有獨立的速率限制，輪詢不會佔用資料類端點的額度；餘額為零時照常回傳。

範例請求

curl "https://synthorai.io/api/v1/billing/balance" \
  -H "Authorization: Bearer sk-syn-bill-..."

範例回應

{
  "data": {
    "available_usd": 1284.37,
    "debt_usd": 0,
    "source": "live",
    "voucher": null,
    "scheduled_credits": [
      { "amount_usd": 250, "release_at": "2026-10-01T00:00:00Z" }
    ],
    "scheduled_credit_total_usd": 250
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z", "currency": "USD" }
}

錯誤

每個錯誤都是 {"error": {"type", "message", "hint"}}:

{
  "error": {
    "type": "range_too_large",
    "message": "the requested range exceeds this endpoint's cap",
    "hint": "narrow start/end to at most 31 days, or sync /records with a cursor instead"
  }
}

速率限制與上限

絕不會回傳： channel_id, upstream_request_id, usage_raw, other, content, ip_address, user_agent, cost_detail.

避免時間間隙

請求完成後會非同步寫入日誌（通常幾秒鐘，積壓時會更久），而 /usage 與 /summary 讀取的按小時匯總表是按批次寫入的。最近幾個小時的資料總是有一點不完整。/usage 與 /summary 會補上自上次彙總以來新寫入的請求（meta.live_tail 為 true）；彙總落後太多時不再補（meta.live_tail 為 false），最近的時間桶是不完整的。

data_complete_until 取以下兩者中較早的一個：按小時匯總表的水位線減去目前的處理延遲，或尚未被匯總的最早請求 - 再減去 30 分鐘的安全餘量，並向下取整到小時。

每個 /usage 行都帶有一個 final 標誌： true ，即當其所在的桶結束時間早於或等於 data_complete_until （/freshness 回傳的值）時成立。已定稿的桶不會再變化。

• 聚合資料: 按 (bucket_start, api_key_id, model) 將每一行 upsert 到你自己的儲存中，並在某個桶仍為 final: false 時重新擷取它。絕不要用新總量減去舊總量的方式來推算增量。
• 原始行: 按 cursor 同步，絕不要按時間同步。請保留 next_cursor，並在下一次呼叫時從它繼續，同時按 record_id（每行穩定的不透明 id）對收到的行去重，以防某次續傳重複送達同一行。晚於約 5 分鐘的行會被暫時保留 - safe_until 即最新已記錄行的時間減去 5 分鐘 - 因此一個仍在提交中的行絕不會跑到已發出的游標位置之前，也就不會有資料落入間隙。統計請求數時，請依 request_id 去重計數。
• 限定窗口: 如果你查詢的是 start/end 範圍而不是按 cursor 同步，只有在 window_final 為 true 時才可信其為完整（只有當你提供了 end 且它早於或等於 safe_until 時才為 true）。如果 window_final 為 false，請稍後用相同範圍再次呼叫，或改為按 cursor 同步。時間窗的開始時間必須不晚於 safe_until；更晚的開始時間會回傳 400 start_too_recent，並帶 Retry-After 標頭。

建議的整合方式

• 每晚帳單處理: 每天呼叫一次 /usage，並使用 granularity=day；對上一次執行中仍為 final: false 的桶重新擷取。
• 逐請求明細: 每小時呼叫一次 /records，將 cursor 設為你儲存的上一次 next_cursor，並在 has_more 為 true 時持續翻頁，同時按 record_id 對收到的行去重。
• 儀表板: 對目前可見範圍呼叫 /summary，而不是自己聚合 /records - 它已經附帶了異常清單。

需要以程式化方式簽發或管理一般 API 金鑰，而不是讀取帳單資料？請參閱 Provisioning Keys。