Felo API PlatformFelo API Platform

OpenAPI 計費與錯誤

供應商：Felo · 以平台餘額付款

驗證與設定計費與錯誤

本頁適用於 /api/v1/data/*，也就是 Felo OpenAPI 平台專屬 API。呼叫會使用 平台餘額，這是以 USD 計價的服務點數餘額。它們不會消耗 Felo Pro 點數。較早的 Felo APIs 位於 /v2，使用 Pro 點數。

讀取目前價格

curl -sS https://openapi.felo.ai/api/v1/data/prices

這個公開端點不需要金鑰。請依操作 ID 匹配其項目，並讀取目前費率與計費單位；不要假設每個操作成本都相同，也不要把範例中的費率固定寫入你的應用程式。

操作 ID計費單位
web.search, web.read, chat請求
x.user.info, x.user.search, x.user.tweets, x.tweet.search, x.tweet.replies回傳結果
ppt.generate生成頁面
ppt.export匯出請求
ppt.generate.status, ppt.generate.historical, ppt.export.status, ppt.delete不會產生新費用

免費的狀態查詢不代表底層生成或匯出也免費。對於 X，分頁與巢狀回傳記錄可能會增加可計費用量。

餘額與預留

在執行前，服務可能會為該操作預留足夠的餘額。成功的工作會從該預留金額中結算；確認失敗則會釋放。對於非同步任務，回傳 ID 並不代表計費已經完成。

PPT 頁面計價會在建立時預留 10 頁。成功生成會結算實際輸出並釋放未使用的資金。生成與匯出是分開計費的。請參閱 PPT 工作流程 了解重複匯出的行為。

如果執行或結算結果不確定，預留金額可能會在服務進行對帳時維持待定。不要把每一次逾時或 5xx 都視為沒有任何工作發生，或重送請求就一定免費。

請在 Console Billing 檢視你的可用餘額與用量。如需帳戶層級加值說明，請參閱 Billing and Credits。

透過 API 查詢錢包用量

帳戶擁有者可以使用 Felo 登入權杖 檢視錢包呼叫紀錄。這個憑證不同於 Data API 呼叫所使用的 API Key；不要以 FELO_API_KEY 取代它。

curl -sS 'https://openapi.felo.ai/api/wallet/usage?call_type=data' \
  -H 'Authorization: Bearer YOUR_FELO_LOGIN_TOKEN'

紀錄位於 data.items；call_type=data 會過濾能力呼叫。請將用量與帳戶目前價格比對。讀取紀錄不會提交另一個生成任務。Console Billing 仍可用於帳戶檢視與加值。

防禦性地讀取錯誤

請先檢查 HTTP 狀態。錯誤可以使用以下任一種格式；下列值僅供說明：

{"error":{"code":"invalid_parameter","message":"Check the request fields"},"request_id":"example-request-id"}
{"status":402,"code":"INSUFFICIENT_BALANCE","message":"Insufficient balance","request_id":"example-request-id"}

請在有提供時讀取 error.code / error.message，否則讀取 code / message。若有回傳，請保留 request_id。成功回應會依操作而不同；不要強行把它們都放進同一種錯誤或 data 封裝中。

決定下一步要做什麼

HTTP 狀態常見原因下一步
400缺少或無效參數重試前先修正請求
401金鑰缺失、無效、已撤銷或已過期檢查金鑰與驗證標頭
402平台餘額不足檢查可用餘額與待處理預留；必要時加值
404資源缺失或此帳戶無法存取檢查 ID 與建立帳戶
409操作與目前任務狀態衝突，或執行尚未確認讀取錯誤代碼並查詢既有任務；不要立即重複提交
410資源已過期或已刪除使用已儲存的檔案；僅在需要時建立新任務
429速率限制或 API 金鑰配額已超過檢查重設資訊；降低頻率或等待配額重設
502 / 503 / 504上游、可用性、逾時或結算失敗在重試付費操作前，先確認工作是否已經存在

execution_unconfirmed（409）與 billing_settlement_pending（503）需要特別小心：不要立刻重新提交付費工作。請查詢已知任務或使用 request ID 聯絡支援。成功的 HTTP 狀態但回傳空結果，與錯誤回應不同。

在不產生重複工作的情況下重試

  • 對於唯讀任務與匯出狀態查詢，請使用有上限的退避，並在有提供時遵守 Retry-After。
  • 若建立請求失敗但你已有儲存的 task_id，請先查詢該任務，再建立另一個。
  • 如果連線在你收到 ID 之前失敗，結果可能未知。不要假設重新送出就能自動去重。
  • 對於 429，請區分短期速率限制與 API 金鑰配額視窗；反覆重試無法重設配額。
  • 在你設定的截止時間後停止重試，並向呼叫端顯示可操作的錯誤。

如需支援，請提供端點、約略時間、HTTP 狀態與 request ID。切勿包含完整 API 金鑰。

需要協助嗎？