配額與速率限制
Kaleidr 以兩種不同方式限制用量，兩者都會傳回 HTTP 429：
- 配額是組織在一個計費週期內可使用的總量。用盡後，必須等待週期重設或增加額度。
- 速率限制規定呼叫 API 的頻率。達到限制時，需放慢呼叫速度並等待幾秒鐘。
回應本文會指出觸發哪一種限制。本頁列出各類回應內容、每次呼叫的計費方式，以及各情況的處理方法。
兩個額度池
使用量依組織計算，分別歸入兩個額度池。
| 額度池 | 消耗額度的操作 | Free | Pro | Enterprise |
|---|---|---|---|---|
| AI 點數 | 聊天回覆、地點查詢、地址搜尋與設計分析 | 每週期 500,000 | 每週期 5,000,000 | 依合約客製化 |
| 地圖載入次數 | 每次 Tile 工作階段及每次檢視已發布或嵌入的地圖 | 每週期 50,000 | 每週期 50,000 | 基本額度相同；更高用量依合約約定 |
關於這兩個額度池，有三點容易產生誤解：
- AI 點數是整個組織共用的單一額度池。 API 金鑰與團隊使用 Kaleidr 自有應用程式所消耗的 AI 點數來自同一額度池。沒有獨立的 API 預算，所有金鑰共用額度。
- 週期以您的計費週期為準。 付費訂閱按訂閱當日起算的每月週期計算；沒有訂閱時則採曆月。週期於美國東部時間午夜切換。
- 加購套件可提高上限。 購買的 AI 點數包與地圖載入次數包會加到方案額度中，回應的
limit已包含這些加購額度。
方案變更會在數分鐘內套用至現有金鑰，無須建立新金鑰。
每種調用如何計費
| 調用 | 額度池 | 費用 |
|---|---|---|
POST /chat/control/stream, /chat/summary/stream, /chat/button/stream, /spot/overview/stream | AI 點數 | 回答消耗的輸入與輸出 token 總數。參見串流調用的計費方式。 |
POST /chat/control/route | 無 | 不收費。規劃路線時會暫時預留額度，完成後始終釋放。 |
POST /spot | AI 點數 | 每次調用按固定費用計費，無論是否找到內容：當 want 包含 content 或 photos 且本次呼叫需要取得內容時，按 /retrieval/poi/enrich 的費用計算；否則，當它包含 address 時，按 /retrieval/geocode/forward 的費用計算。先前請求已取得的內容不收費。僅請求地點、區域或邊界不收費。 |
GET /retrieval/poi/enrich | AI 點數 | 每次調用收取固定費用，即使未找到內容也會收費。 |
GET /retrieval/geocode/forward | AI 點數 | 每次調用收取較低的固定費用，即使沒有結果也會收費。如果查詢本身失敗，則不收費。 |
POST /design/analyze | AI 點數 | 每次成功調用收取固定費用；調用失敗不收費。 |
POST /design/apply-direct, GET /design/styles, /design/samples, /design/themes | 無 | 不收費。 |
POST /sdk/sessions，用於 chat、editor、viewer | 無 | 不收費。 |
POST /sdk/sessions，用於 tile | 地圖加載次數 | 每次交換計入一次地圖加載。 |
POST /sdk/share-sessions | 無 | 不收費。通過該會話發起的聊天調用計入地圖所有者的額度。 |
POST /inference-api/vendor/mapping/propose，即業務數據上傳 API 的欄位映射建議 | AI 點數 | 按生成建議所使用的 token 計費。調用使用賬戶登錄身份，而非 API 密鑰。點數用盡時傳回 429 quota_exceeded；此外，每個賬戶每小時最多可提交 30 次建議，這兩種 429 響應的本文不同。上傳、發佈、取消發佈和刪除不收費。 |
當前使用量和限制可在 kaleidr.com/billing 查看。
串流調用如何計費
串流調用只有在結束後才能確定實際成本，因此計費分為兩個步驟：
- 預留。 請求被接受時，系統會從額度池中預留固定數量的點數。如果剩餘額度不足以完成預留，請求會在生成任何回答之前以
quota_exceeded被拒絕。因此，即使實際費用可能更低，調用開始時仍需要足夠的可用額度。 - 結算。 流結束後，預留金額會替換為實際費用，即回答所使用的 token 數量。實際費用可能高於或低於預留金額。
如果主動中斷流，或流在回答完成前失敗，實際 token 數量無法確定，系統將按估算值收費：
| 流 | 未完成時的收費方式 |
|---|---|
/chat/control/stream | 取以下兩者較大值：所提交對話的估算量（請求中的 user 和 assistant 消息），或已輸出文本的估算量（後者計算至預留額度）。費用可能高於預留金額。 |
/chat/summary/stream, /chat/button/stream, /spot/overview/stream | 按已輸出文本估算，且絕不超過預留金額。 |
因此，提前關閉聊天流並不能讓長對話免費：即使幾乎未讀取回答，也至少會按請求本身的大小收費。請僅發送下一次回答所需的最近幾輪對話，以減小請求體積。參見讀取串流響應。
如果流運行期間達到額度限制，當前流不會中斷。系統在接收請求時進行檢查；下一次請求才會被拒絕。
被拒絕的請求不收費。 如果請求在處理前就被拒絕（原因包括速率限制、併發限制、驗證錯誤或請求本文超出大小限制），不會繼續佔用 AI 點數或併發名額。可以重試，而無需為此次拒絕付費。
單個密鑰的額度上限
密鑰可以設置月度上限（monthly_cap_tokens，通過密鑰管理 API 配置），用於限制該密鑰在一個計費週期內可消耗的組織 AI 點數。組織額度池仍是最終總上限。
如果某次請求會使密鑰超過其上限，系統也會傳回 quota_exceeded，但其中的 limit 和 used 表示該密鑰的額度值，而非組織額度池的值。
配額超出限制
HTTP/1.1 429 Too Many Requests
Retry-After: 1296000
Content-Type: application/json
{
"error": "quota_exceeded",
"detail": "Usage limit reached. Please try again later.",
"product": "b2b",
"meter": "b2b.tokens",
"tier": "pro",
"limit": 5000000,
"used": 4999100,
"remaining": 900,
"reset_at": "2026-11-01T04:00:00+00:00",
"period": "month",
"reset_in_seconds": 1296000
}
| 欄位 | 意義 |
|---|---|
error | 在此情況下固定為 quota_exceeded。請根據此欄位決定程式處理分支。 |
detail | 供使用者閱讀的說明文字。請勿以程式剖析此文字。 |
product, meter | 用來識別 API 的 AI 點數計數器。對於平台金鑰，固定為 b2b 與 b2b.tokens。 |
tier | 你所屬組織的方案。 |
limit, used, remaining | 共用點數額度的數值；如果呼叫因個別金鑰的上限而遭拒，則為該金鑰的數值。remaining 可能大於零：呼叫遭拒是因為餘額不足以完成暫時預留。 |
reset_at | 期間結束時間，以包含時區偏移量的 ISO 8601 時間戳記表示。請使用此值告知使用者服務何時恢復。 |
period | month。 |
reset_in_seconds | 距離 reset_at 的秒數，也就是點數額度重設期間的結束時間（訂閱計費週期；若沒有訂閱，則為曆月）。Retry-After 回應標頭會包含相同數值。 |
響應本文採用扁平結構：各欄位位於頂層，而不是包含在 detail 對象中。
使用會話權杖時
上述本文適用於使用服務器密鑰或舊版密鑰的請求。使用會話權杖的請求在訪客瀏覽器中運行，因此拒絕響應不會洩露組織的方案、已用額度或額度上限。無論會話由可公開密鑰交換而來，還是屬於已發佈地圖的訪客會話，都遵循這一規則。
{
"error": "quota_exceeded",
"detail": "Usage limit reached. Please try again later.",
"meter": "b2b.tokens",
"reset_at": "2026-11-01T04:00:00+00:00",
"reset_in_seconds": 1296000
}
| 欄位 | 服務器密鑰或舊版密鑰 | 會話權杖 |
|---|---|---|
error, detail | 是 | 是 |
meter | 是 | 是 |
reset_at, reset_in_seconds | 是 | 是 |
product, period | 是 | 否 |
tier | 是 | 否 |
limit, used, remaining | 是 | 否 |
HTTP 狀態、Retry-After 響應頭及其含義保持一致。在瀏覽器代碼中，應根據 error 分支處理並顯示 reset_at；不要嘗試讀取 limit、used 或 remaining。如需顯示用量數字，請在後端使用服務器密鑰讀取，或前往 kaleidr.com/billing 查看。
如果響應本文顯示 used: 0，而您知道組織此前有過活動，說明 API 無法讀取使用量，因此為安全起見拒絕了調用。此時應在數秒後重試，而不是等待 reset_at。
速率限制與併發限制
每次運行時調用前都會檢查三種限制。超過任一限制的請求會立即被拒絕，不會進入隊列。
| 限制 | 統計單位 | 適用範圍 |
|---|---|---|
| 每分鐘請求數 | 密鑰 | 在滾動的 60 秒窗口內，統計使用該密鑰及通過該密鑰交換的所有會話發起的每次運行時調用。使用同一可公開密鑰的網站訪客共享這一限額。 |
| 每分鐘會話交換次數 | 密鑰 | 針對 POST /sdk/sessions 的調用。其限額獨立計算，因此掛載嵌入組件不會佔用運行時請求數。 |
| 併發請求數 | 組織 | 組織所有密鑰同時進行的調用。串流請求在保持打開期間一直計入併發數量。 |
無法通過 API 密鑰頁面或密鑰管理 API 修改密鑰的每分鐘請求限制。如果流量需要更高的調用速率，請聯繫我們。
以下每種拒絕都使用相同的響應本文結構和響應頭：
HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json
{ "error": "rate_limited", "detail": "API key rate limit exceeded. Slow down." }
error | 含義 | 處理方式 |
|---|---|---|
rate_limited | 密鑰的每分鐘請求數或會話交換額度已用盡。 | 等待 Retry-After 指定的秒數後重試，並加入隨機抖動。 |
org_overloaded | 您的組織同時運行的調用過多。 | 等待某個進行中的調用結束後再試，關閉不再需要的流。 |
b2b_overloaded | API 對所有調用方的容量已達上限。 | 等待 Retry-After 指定的時間，再採用退避策略重試。 |
limiter_unavailable | 速率限制服務未能傳回結果。 | 稍後重試。降低請求速率無濟於事，因為問題並非您的調用頻率。 |
visitor_limit_reached | 某位已發佈地圖聊天訪客的每分鐘或每日請求次數過多。 | 告知訪客稍後再試，參見已發佈地圖上的聊天功能。 |
在網絡邊緣還會針對 IP 地址和憑據限制請求速率。被攔截的請求不會傳回本頁列出的 JSON 響應本文。對於沒有 Kaleidr 格式本文的 4xx 響應，應降低請求頻率並稍後重試。
地圖加載次數
每當 Kaleidr 地圖為訪客啓動時，都會計入一次地圖加載：
- 每次針對
product: "tile"的會話交換，包括 SDK 自動刷新以及組件的每次重新掛載； - 每次查看已發佈或嵌入的地圖。
嵌入式 Editor 的會話交換不計入地圖加載。相反，其攜 帶可公開密鑰的底圖請求（樣式、精靈圖和字體）會按批次統計：組織在一小時內每發起 20 次此類請求，事後增加一次地圖加載。這些請求不會因為超出額度而被拒絕。地圖瓦片數據本身不計入統計。
所有方案達到額度上限後都會停止加載。 額度池用盡後，下一次加載會被拒絕且不計數。付費方案也沒有額外緩衝額度；購買地圖加載包可以立即提高上限。
通過會話交換傳回的拒絕響應如下：
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{ "detail": "map_load_quota_exceeded" }
此響應本文將錯誤代 碼放在 detail 中，而不是採用上文的扁平配額響應結構，且沒有 Retry-After 響應頭。在週期重設或增加額度包之前，重試無法解決問題。網頁中的 Tile 嵌入組件將無法啓動，SDK 會記錄 kaleidr session exchange failed (429)。
直接請求地圖瓦片
底圖瓦片服務器並不是公開的瓦片 API。要顯示 Kaleidr 底圖，請使用受支持的Tile 產品。如果對 tile.kaleidr.com 的請求不是從允許來源上的 Kaleidr 嵌入組件發出，或者沒有有效的可公開密鑰，請求就會被拒絕：
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Cache-Control: no-store
Content-Type: application/json
{
"error": "tile_access_restricted",
"message": "Direct access to tile.kaleidr.com requires a Kaleidr publishable key. Mint a free one at kaleidr.com/api-keys and pass it as ?key= from an allowed origin. Kaleidr-hosted maps and embeds are unaffected.",
"docs": "https://docs.kaleidr.com/get-an-api-key"
}
此響應來自瓦片服務器而不是平台 API，因此使用 message 欄位，而平台 API 使用 detail。新建或修改的密鑰可能需要幾分鐘才能用於瓦片訪問。
串流響應中的 quota 事件
聊天流會在完成計費後報告額度池狀態。quota 是該流的最後一個事件，在 end 或 error 之後發送：
event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 184223, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}
這是使用服務器密鑰或舊版密鑰讀取流時收到的事件。如果使用會話權杖（由可公開密鑰交換得到，或由已發佈地圖的訪客會話提供）讀取流，則該事件不包含方案資訊和使用量數字：
event: quota
data: {"type": "quota", "meter": "b2b.tokens", "reset_at": "2026-11-01T04:00:00+00:00"}
| 欄位 | 服務器密鑰或舊版密鑰 | 會話權杖 |
|---|---|---|
type, meter, reset_at | 是 | 是 |
product, period | 是 | 否 |
tier | 是 | 否 |
used, limit | 是 | 否 |
使用服務器密鑰時，可以憑此事件更新使用量儀表，而無需第二次請求。但有三項限制：
- 事件沒有
remaining欄位。請自行計算limit - used。 - 此事件盡力發送，但不保證一定到達。流可能結束而未發送該事件，因此不要一直等待它。
- 該事件僅用於報告，而非提前預警。它絕不會出現在回答中途，也不能中斷流。
要收到該事件，請持續讀取，直到響應本文關閉。如果客戶端在 end 處停止，就會錯過該事件。
在代碼中處理 429
決定是否重試前，請先讀取響應本文。僅憑 HTTP 狀態碼無法確定是否應該重試。
| 收到的響應 | 是否重試？ | 何時重試 |
|---|---|---|
error: "quota_exceeded" | 否 | 等待 reset_at 所示時間，或增加點數、提高密鑰上限後再試。向用戶顯示額度已用盡的提示。 |
error: "rate_limited", "org_overloaded", "b2b_overloaded", "limiter_unavailable" | 是 | 等待 Retry-After 指定的秒數，加上隨機抖動，最多重試幾次。 |
error: "visitor_limit_reached" | 否 | 稍後再試，並告知訪客。 |
detail: "map_load_quota_exceeded" | 否 | 等待計費週期重設，或增加地圖加載包後再試。 |
error: "tile_access_restricted" | 否 | 修正嵌入方式：在允許來源上使用帶可公開密鑰的 Tile 產品。 |
const RETRYABLE = new Set(['rate_limited', 'org_overloaded', 'b2b_overloaded', 'limiter_unavailable']);
async function callKaleidr(url, init, attempt = 0) {
const res = await fetch(url, init);
if (res.status !== 429) return res;
const body = await res.json().catch(() => ({}));
if (RETRYABLE.has(body.error) && attempt < 3) {
const seconds = Number(res.headers.get('retry-after')) || 5;
await new Promise((resolve) => setTimeout(resolve, (seconds + Math.random()) * 1000));
return callKaleidr(url, init, attempt + 1);
}
const error = new Error(body.error || body.detail || 'rate limited');
error.status = 429;
error.code = body.error || body.detail;
error.resetAt = body.reset_at; // present for quota_exceeded
throw error;
}
在瀏覽器 中，可以通過 JavaScript 讀取平台 API 響應中的 Retry-After 響應頭。