REST API

金鑰自助查詢 API

用這把 API Key 查詢它自己的點數批次、用量紀錄與設定（V1.21.0 新增）。

三支端點共通：

唯讀端點：不改變任何狀態。
零餘額也可查詢：點數用盡時仍可查詢。
只回這把 API Key 自己的資料：同帳戶其他 API Key 的批次與紀錄不會出現。
回應不含 API Key 本身或其任何片段，也不含 Webhook 簽章密鑰。

相關端點：我的方案 API（計費制度、方案內容與可用點數）。

GET /api/v1/me/credit-lots

功能說明

列出這把 API Key 扣點時會動用的點數批次：只列仍有剩餘且未過期的批次，先到期的排前面。

批次分兩種來源：

`pool`	說明	何時列出
`key`	分配給這把 API Key 的專屬額度	這把 API Key 有分配專屬額度時
`account`	帳戶點數	這把 API Key 允許使用帳戶點數時

扣點時先用專屬額度，再用帳戶點數；同一種來源內，先到期的批次先扣。

批次加總可能大於實際可用點數：這把 API Key 有設定每月點數上限時，本月還能用的點數以上限為準。實際可用點數請看 GET /api/v1/me/plan 的 available_credit。

吃到飽的 API Key：方案內的用量不扣點。
綁定吃到飽方案的 API Key：回 {"data": []}。這類 API Key 無法開廣播（見廣播 API 的 plan_feature_not_allowed），沒有會動用的點數批次。
沒有方案內容的吃到飽授權（見我的方案 API 形狀 3）：不論是否允許使用帳戶點數，都列出帳戶點數的批次，廣播照點數計費時從這裡扣。

使用場景

在 UI 上顯示「還剩多少點、哪一批何時到期」
點數快到期前提醒使用者

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

此端點不需要任何請求參數。

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/me/credit-lots" \
  -H "X-API-Key: YOUR_API_KEY"

成功回應

HTTP 200

{
  "data": [
    {
      "pool": "key",
      "remaining_points": 12.5,
      "expires_at": "2026-10-02T23:59:59+08:00",
      "granted_at": "2026-07-01T10:15:00+08:00"
    },
    {
      "pool": "account",
      "remaining_points": 500.0,
      "expires_at": "2027-03-31T23:59:59+08:00",
      "granted_at": "2026-04-01T09:00:00+08:00"
    },
    {
      "pool": "account",
      "remaining_points": 5.0,
      "expires_at": null,
      "granted_at": "2026-01-15T14:30:00+08:00"
    }
  ]
}

沒有任何可用批次時回 {"data": []}。

回應欄位說明

欄位	類型	說明
`data`	array	批次清單，先到期的排前面；永不過期的排最後
`data[].pool`	string	來源：`key`（專屬額度）／`account`（帳戶點數）
`data[].remaining_points`	float	這一批的剩餘點數
`data[].expires_at`	string \| null	到期時間（ISO 8601）；永不過期為 `null`
`data[].granted_at`	string	這一批點數的撥入時間（ISO 8601）

特有錯誤碼

此端點無特有錯誤碼，僅可能回傳通用認證錯誤（如 401 auth_missing_api_key／auth_invalid_api_key）。

GET /api/v1/me/usage

功能說明

列出這把 API Key 的扣點紀錄，新的排前面。每一場錄音或廣播、每一次匯入／摘要／重翻各一列（不是每分鐘一列）。

只列扣點與退點；點數撥入與到期不在此清單。
進行中的錄音或廣播也會列出，points 為目前累計。
整場退點的紀錄仍會列出，refunded 為 true、points 為 0（不另外顯示原本應扣的點數）。
管理後台的扣點紀錄不列整場退點的紀錄，因此兩邊的筆數可能不同。

使用場景

在 UI 上呈現「點數花在哪裡」
對帳：以 task_id 對應自己的任務紀錄

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

Query 參數

參數	類型	必填	預設	說明
`page`	integer	否	`1`	頁碼，範圍 1～100000；超過最後一頁回空的 `data`
`per_page`	integer	否	`20`	每頁筆數，範圍 5～20

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/me/usage?page=1&per_page=20" \
  -H "X-API-Key: YOUR_API_KEY"

成功回應

HTTP 200

{
  "data": [
    {
      "task_id": "9d3c2b1a-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "type": "recording",
      "points": 2.5,
      "in_progress": true,
      "refunded": false,
      "refund_reason": null,
      "occurred_at": "2026-09-29T14:02:11+08:00",
      "ended_at": null
    },
    {
      "task_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "import",
      "points": 6.0,
      "in_progress": false,
      "refunded": false,
      "refund_reason": null,
      "occurred_at": "2026-09-29T11:30:45+08:00",
      "ended_at": "2026-09-29T11:30:45+08:00"
    },
    {
      "task_id": "7f6e5d4c-3b2a-4c1d-9e8f-7a6b5c4d3e2f",
      "type": "recording",
      "points": 0,
      "in_progress": false,
      "refunded": true,
      "refund_reason": "no_audio",
      "occurred_at": "2026-09-28T16:20:00+08:00",
      "ended_at": "2026-09-28T16:23:00+08:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 20,
    "total": 63
  }
}

回應欄位說明

欄位	類型	說明
`data`	array	用量紀錄，新的排前面
`data[].task_id`	string \| null	對應的任務 ID；不屬於任何任務的用量（如不帶任務的摘要、摘要翻譯）為 `null`
`data[].type`	string	用量類型，見下表
`data[].points`	float	實際扣除的點數。進行中為目前累計；吃到飽方案內的用量為 `0`；整場退點後為 `0`
`data[].in_progress`	boolean	錄音或廣播是否仍在進行
`data[].refunded`	boolean	是否已整場退點
`data[].refund_reason`	string \| null	退點原因：`no_audio`（整場沒有收到音訊，自動退點）／`manual`（由服務窗口退點）；未退點為 `null`
`data[].occurred_at`	string \| null	錄音或廣播的開始時間；其他類型為扣點時間（ISO 8601）
`data[].ended_at`	string \| null	結束時間（ISO 8601）；進行中為 `null`；錄音與廣播以外的類型與 `occurred_at` 相同
`meta.current_page`	integer	目前頁碼
`meta.last_page`	integer	最後一頁頁碼
`meta.per_page`	integer	每頁筆數
`meta.total`	integer	總筆數

type 值

值	說明
`recording`	即時錄音
`broadcast`	廣播
`import`	音檔匯入
`summary`	AI 會議摘要
`regen_summary`	重新生成摘要
`retranslate`	全文重翻
`summary_translate`	摘要翻譯

之後可能新增 type 值，整合時請把未知的值當作一般用量顯示，不要解析失敗。

錯誤回應

HTTP	error_code	情境
422	`validation_failed`	`page` 不在 1～100000，或 `per_page` 不在 5～20，或不是整數

另可能回傳通用認證錯誤（如 401 auth_missing_api_key／auth_invalid_api_key）。

GET /api/v1/me/key

功能說明

查詢這把 API Key 的設定與本月點數花費。

使用場景

在 UI 上顯示這把 API Key 的名稱、到期日與每月點數上限的使用進度
確認 Webhook 網址、是否已設定來源 IP 限制

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

此端點不需要任何請求參數。

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/me/key" \
  -H "X-API-Key: YOUR_API_KEY"

成功回應

HTTP 200

{
  "data": {
    "name": "客服中心",
    "expires_at": "2027-03-31T23:59:59+08:00",
    "monthly_spend_limit": 200.0,
    "monthly_spent": 42.5,
    "max_concurrent_sessions": 3,
    "allow_account_pool": true,
    "webhook_url": "https://example.com/hook",
    "ip_restricted": true
  }
}

回應欄位說明

欄位	類型	說明
`data.name`	string	API Key 名稱
`data.expires_at`	string \| null	API Key 到期時間（ISO 8601）；不會到期為 `null`
`data.monthly_spend_limit`	float \| null	每月點數上限；未設定為 `null`
`data.monthly_spent`	float \| null	本月已花費點數（依帳號時區的當月，含專屬額度與帳戶點數）；未設定每月點數上限時為 `null`
`data.max_concurrent_sessions`	integer \| null	這把 API Key 的併發錄音上限；未另外設定為 `null`
`data.allow_account_pool`	boolean	是否允許使用帳戶點數
`data.webhook_url`	string \| null	Webhook 通知網址，只回協定、主機與路徑（有指定連接埠時一併回傳），不含網址中的帳號密碼、查詢參數與片段；路徑會原樣回傳，請勿把驗證用的 token 放在路徑中（請改用簽章驗證）；未設定為 `null`
`data.ip_restricted`	boolean	是否已設定來源 IP 限制（規則內容不回傳）

特有錯誤碼

此端點無特有錯誤碼，僅可能回傳通用認證錯誤（如 401 auth_missing_api_key／auth_invalid_api_key）。

版本：V1.24.1 最後更新：2026-09-29

音檔匯入 API

我的方案 API