计费与错误处理

本页适用于 /api/v1/data/* 下的 Felo OpenAPI 平台专属接口。调用使用平台余额，即以美元计价的服务额度，不消耗 Felo Pro 积分。原 /v2 Felo APIs 使用 Pro 积分。

查看当前价格

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

此公开接口无需密钥。按操作 ID 查找条目，读取当前单价和计费单位。不要假设所有接口价格相同，也不要把文档示例中的价格写死在应用里。

查询状态免费不代表生成或导出免费。X 接口翻页以及返回的嵌套记录，可能增加计费量。

余额与预留费用

执行前，服务可能先预留本次操作所需余额。成功后结算，确认失败后释放预留。异步任务返回 ID 时，并不代表费用已完成最终结算。

PPT 按页定价时，创建先预留十页费用；生成成功后按实际产出结算，多余预留会释放。生成和导出分别计费。重复导出的行为见 PPT 完整流程。

执行结果或结算状态不确定时，预留可能继续保留，等待服务核对。不要把所有超时或 5xx 都理解为“没有执行、没有费用”，也不要立即重复提交付费操作。

在控制台 Billing查看可用余额和用量。账户充值说明见计费与额度。

通过 API 查询钱包用量

账户所有者可以使用 Felo 登录 token 查询钱包调用记录。这里的认证凭据与调用 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 用于筛选能力调用。结合账户当前价格与实际用量核对费用；查询记录不等于发起新的生成任务。需要人工查看或充值时，仍可使用控制台 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 外层。

按错误采取下一步

execution_unconfirmed（409）与 billing_settlement_pending（503）需要特别处理：不要立即重提付费操作，先查询已知任务，或携带请求 ID 联系支持。HTTP 成功但返回空结果，与错误响应也要分开处理。

避免重试产生重复任务

• 查询任务或导出状态时，使用有上限的退避重试；返回 Retry-After 时遵循它。
• 创建请求失败但已经拿到 task_id 时，先查询该任务，不要再创建。
• 连接在收到 ID 前断开，执行结果可能不确定。不能假设重发请求会自动去重。
• 遇到 429，区分短期限流与 API Key 配额窗口；不断重试不能恢复配额。
• 达到设定等待期限后停止重试，向调用方展示可处理的错误。

联系支持时提供接口、发生时间、HTTP 状态和请求 ID，不要提供完整 API Key。