配额与用量
GVR 通过用户账户的 remainingRequests 值,按 API 密钥跟踪请求用量。
各操作的请求消耗
处理成功后才会扣除配额。成功返回性别 unknown 也会消耗配额。
| 操作 | 配额消耗 |
|---|---|
| 标准语音性别文件分析 | 1 个请求 |
| 标准语音性别 URL 分析 | 1 个请求 |
| 语音性别 V2(改进的语音检测分析) | 1 个请求 |
| 语音性别 V3(高级说话人分析) | 2 个请求 |
| 语音年龄、伪造语音、语音情绪、音频质量、说话人验证、图像或单个人名分析 | 每次成功的 API 调用 1 个请求 |
| CSV 验证 | 不消耗请求;仅检查配额是否足以处理所有行 |
| CSV 处理 | 每处理一行消耗 1 个请求 |
CSV API
CSV 处理有所不同,因为一个文件可能包含多行。API 会先检查行数,并在处理时每行消耗一个请求。
如果文件的行数超过该密钥的剩余请求数,API 会在处理 CSV 之前拒绝该请求。
响应元数据
许多成功的 API 响应都包含更新后的配额信息:
{
"remainingRequests": 2999
}
您可以使用此值在应用中显示用量,或在用户配额用尽之前触发升级提示。
配额错误
文件和 CSV 端点可能返回结构化的速率限制响应:
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "You have exceeded your free tier limit of 50 requests.",
"detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
"details": {
"limit": 50,
"used": 50,
"reset_date": "2026-07-01T00:00:00.000Z"
},
"suggested_action": "Please upgrade to a premium plan to continue using the API."
}
}
单次姓名端点可能返回:
{
"error": "Insufficient remaining requests"
}
实用建议
- 调用 API 前先验证必填字段。
- 遇到验证错误时避免循环重试。
- 每次 API 响应后,以
remainingRequests作为配额的权威依据。 - 对于 CSV 流程,请在开始大型处理任务前先验证 CSV。