用量统计Usage & Quota

查询当前账号的 API 调用量、配额使用情况和各项服务的用量明细。Query API consumption, quota usage, and per-service usage details for the current account.

快速概览

用量统计 API 提供两个核心端点：/v1/usage 用于查询账号级别的汇总用量与配额，/v1/usage/details 用于按服务维度查看每日/每小时的消耗明细。支持自定义日期范围、按服务过滤、以及按天/小时粒度的统计分析。可通过配置 配额告警 Webhook 在用量达到阈值时自动推送通知。 The Usage API provides two core endpoints: /v1/usage for account-level usage summary and quota status, and /v1/usage/details for per-service daily/hourly consumption details. Supports custom date ranges, per-service filtering, and daily/hourly granularity. Configure quota alert webhooks for automatic threshold notifications.

认证方式

Authentication

所有 API 请求均需要在 HTTP 请求头中携带有效的 API Token 进行身份认证。请在 控制台 获取您的 Access Token。

All API requests require a valid API Token in the HTTP request header for authentication. Obtain your Access Token from the Console.

Authorization: Bearer {access_token}

请求头

Request Headers

HeaderHeader类型Type必填Required说明Description
AuthorizationstringrequiredBearer Token 认证信息Bearer token authentication

服务名称参考

Service Name Reference

服务标识Service ID服务名称Service Name计费单位Billing Unit
text_translation文本翻译Text Translation字符数/请求数Characters / Requests
document_translation文档翻译Document Translation字符数/文件数Characters / Files
image_translation图片翻译Image Translation图片张数Images
speech_translation语音翻译Speech Translation秒数/请求数Seconds / Requests
speech_recognition语音识别Speech Recognition秒数/请求数Seconds / Requests
video_translation视频翻译Video Translation秒数/请求数Seconds / Requests
tts语音合成Text-to-Speech字符数/请求数Characters / Requests
subtitle字幕翻译Subtitle Translation字符数Characters
website_translation网站翻译Website Translation字符数/页面数Characters / Pages
code_translation代码翻译Code Translation字符数Characters
ai_polishing语言润色AI Polishing字符数/请求数Characters / Requests
grammar_check语法纠错Grammar Check字符数/请求数Characters / Requests
language_detect语言识别Language Detection请求数Requests

总览

Overview / Summary

GET/v1/usage

查询账号在当前周期内的汇总用量、配额状态及按服务分类的用量明细。

Query account-level aggregated usage, quota status, and per-service breakdown for the current period.

参数Parameter类型Type必填Required说明Description
start_datestringoptional起始日期 (YYYY-MM-DD)，默认本月 1 日Start date (YYYY-MM-DD), default 1st of current month
end_datestringoptional结束日期 (YYYY-MM-DD)，默认今天End date (YYYY-MM-DD), default today
servicestringoptional按服务过滤，如 text_translation；不传则返回所有服务Filter by service, e.g. text_translation; omit to return all services

响应字段

Response Fields

字段Field类型Type说明Description
codeinteger状态码，0 表示成功Status code; 0 = success
messagestring操作结果描述Result description
data.total_charactersinteger周期内累计消耗的总字符数Total characters consumed in the period
data.total_secondsinteger周期内语音/视频类服务累计消耗的秒数Total seconds consumed by speech/video services in the period
data.total_imagesinteger周期内图片翻译累计消耗的图片数Total images consumed by image translation in the period
data.total_requestsinteger周期内所有 API 累计请求次数Total API requests in the period
data.quota_totalinteger账号套餐的字符配额总数Total character quota of the account plan
data.quota_usedinteger已使用的字符配额Used character quota
data.quota_used_percentfloat配额使用百分比，范围 0~100Quota usage percentage, range 0~100
data.quota_statusstring配额状态：normal / warning / exceededQuota status: normal / warning / exceeded
data.breakdownarray按服务拆分的用量明细列表Per-service usage breakdown list
data.breakdown[].servicestring服务标识，如 text_translationService ID, e.g. text_translation
data.breakdown[].charactersinteger该服务消耗的字符数（文本类服务）Characters consumed by this service (text-based)
data.breakdown[].secondsinteger该服务消耗的秒数（语音/视频类服务）Seconds consumed by this service (speech/video)
data.breakdown[].imagesinteger该服务消耗的图片数（图片翻译）Images consumed by this service (image translation)
data.breakdown[].requestsinteger该服务的请求次数API request count for this service
data.periodobject统计周期，包含 start 和 end 日期Statistics period with start and end dates

响应示例

Response Examples

示例 1：正常用量（配额充足）

Example 1: Normal Usage

{
  "code": 0,
  "message": "success",
  "data": {
    "total_characters": 1250000,
    "total_seconds": 18000,
    "total_images": 500,
    "total_requests": 3865,
    "quota_total": 5000000,
    "quota_used": 1250000,
    "quota_used_percent": 25.0,
    "quota_status": "normal",
    "breakdown": [
      { "service": "text_translation", "characters": 800000, "requests": 3200 },
      { "service": "document_translation", "characters": 350000, "requests": 45 },
      { "service": "speech_translation", "seconds": 18000, "requests": 120 },
      { "service": "image_translation", "images": 500, "requests": 500 }
    ],
    "period": { "start": "2026-07-01", "end": "2026-07-20" }
  }
}

示例 2：配额预警（即将用尽）

Example 2: Quota Warning

{
  "code": 0,
  "message": "success",
  "data": {
    "total_characters": 4500000,
    "total_requests": 15800,
    "quota_total": 5000000,
    "quota_used": 4500000,
    "quota_used_percent": 90.0,
    "quota_status": "warning",
    "quota_reset_at": "2026-08-01T00:00:00Z",
    "breakdown": [
      { "service": "text_translation", "characters": 3200000, "requests": 12500 },
      { "service": "document_translation", "characters": 800000, "requests": 110 },
      { "service": "ai_polishing", "characters": 500000, "requests": 3190 }
    ],
    "period": { "start": "2026-07-01", "end": "2026-07-22" }
  }
}

示例 3：配额超限

Example 3: Quota Exceeded

{
  "code": 0,
  "message": "success",
  "data": {
    "total_characters": 5120000,
    "total_requests": 20100,
    "quota_total": 5000000,
    "quota_used": 5120000,
    "quota_used_percent": 102.4,
    "quota_status": "exceeded",
    "quota_reset_at": "2026-08-01T00:00:00Z",
    "overtraffic_enabled": true,
    "overtraffic_used": 120000,
    "breakdown": [
      { "service": "text_translation", "characters": 3800000, "requests": 16500 },
      { "service": "document_translation", "characters": 950000, "requests": 150 },
      { "service": "image_translation", "images": 1200, "requests": 1200 },
      { "service": "ai_polishing", "characters": 370000, "requests": 2250 }
    ],
    "period": { "start": "2026-07-01", "end": "2026-07-22" }
  }
}

示例 4：按指定服务过滤

Example 4: Filtered by Service

{
  "code": 0,
  "message": "success",
  "data": {
    "total_characters": 800000,
    "total_requests": 3200,
    "quota_total": 5000000,
    "quota_used": 1250000,
    "quota_used_percent": 25.0,
    "quota_status": "normal",
    "breakdown": [
      { "service": "text_translation", "characters": 800000, "requests": 3200 }
    ],
    "period": { "start": "2026-07-01", "end": "2026-07-20" }
  }
}

请求示例

Request Examples

基础汇总查询

Basic Summary Query

# 查询本月汇总用量
curl "https://api.itranslator.cc/v1/usage" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 查询指定日期范围汇总
curl "https://api.itranslator.cc/v1/usage?start_date=2026-07-01&end_date=2026-07-22" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 仅查询文本翻译服务的用量
curl "https://api.itranslator.cc/v1/usage?service=text_translation" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

按服务查询明细

Per-Service Details

GET/v1/usage/details

查询指定服务在时间范围内的逐日或逐时用量消耗明细，适合用于生成报表或分析用量高峰。

Query daily or hourly usage consumption details for a specific service within a time range; ideal for reporting and peak analysis.

参数Parameter类型Type必填Required说明Description
servicestringrequired服务名称，如 text_translation、ai_polishingService name, e.g. text_translation, ai_polishing
start_datestringrequired起始日期 (YYYY-MM-DD)Start date (YYYY-MM-DD)
end_datestringrequired结束日期 (YYYY-MM-DD)End date (YYYY-MM-DD)
granularitystringoptionaldaily（默认）/ hourly；hourly 仅在 7 天内可用daily (default) / hourly; hourly only available within 7 days

明细响应字段

Details Response Fields

字段Field类型Type说明Description
codeinteger状态码，0 表示成功Status code; 0 = success
messagestring操作结果描述Result description
data.servicestring查询的服务标识Queried service ID
data.granularitystring统计粒度：daily / hourlyGranularity: daily / hourly
data.total_charactersinteger周期内该服务消耗的总字符数Total characters consumed by this service
data.total_requestsinteger周期内该服务的总请求次数Total requests for this service
data.datapointsarray时间序列数据点列表Time-series datapoint list
data.datapoints[].datestring日期 (YYYY-MM-DD) 或时间 (YYYY-MM-DD HH:00)Date (YYYY-MM-DD) or time (YYYY-MM-DD HH:00)
data.datapoints[].charactersinteger该时间点消耗的字符数Characters consumed at this timepoint
data.datapoints[].requestsinteger该时间点的请求次数Requests at this timepoint

明细响应示例

Details Response Example

按天统计

Daily Breakdown

{
  "code": 0,
  "message": "success",
  "data": {
    "service": "text_translation",
    "granularity": "daily",
    "total_characters": 800000,
    "total_requests": 3200,
    "datapoints": [
      { "date": "2026-07-01", "characters": 42000, "requests": 168 },
      { "date": "2026-07-02", "characters": 38500, "requests": 152 },
      { "date": "2026-07-03", "characters": 51000, "requests": 205 },
      ...
    ],
    "period": { "start": "2026-07-01", "end": "2026-07-20" }
  }
}

按小时统计

Hourly Breakdown

{
  "code": 0,
  "message": "success",
  "data": {
    "service": "text_translation",
    "granularity": "hourly",
    "total_characters": 56000,
    "total_requests": 225,
    "datapoints": [
      { "date": "2026-07-22 09:00", "characters": 12000, "requests": 48 },
      { "date": "2026-07-22 10:00", "characters": 18500, "requests": 73 },
      { "date": "2026-07-22 11:00", "characters": 15500, "requests": 62 },
      { "date": "2026-07-22 12:00", "characters": 10000, "requests": 42 }
    ],
    "period": { "start": "2026-07-22", "end": "2026-07-22" }
  }
}

明细查询代码示例

Details Query Code Examples

# 按天查询文本翻译用量
curl "https://api.itranslator.cc/v1/usage/details?service=text_translation&start_date=2026-07-01&end_date=2026-07-20&granularity=daily" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 按小时查询语音翻译用量
curl "https://api.itranslator.cc/v1/usage/details?service=speech_translation&start_date=2026-07-22&end_date=2026-07-22&granularity=hourly" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

配额告警 Webhook

Quota Alert Webhook

可在 控制台 中配置 Webhook 地址，当配额使用率达到设定阈值时自动推送告警。当前支持 80%、90%、95%、100% 四个预警级别。

Configure a Webhook URL in the Console to receive automatic alerts when quota usage reaches set thresholds. Supports 80%, 90%, 95%, and 100% warning levels.

{
  "event": "quota_warning",
  "account_id": "acc_xxxxx",
  "plan": "pro",
  "quota_total": 5000000,
  "quota_used": 4500000,
  "quota_used_percent": 90.0,
  "threshold": 90,
  "quota_reset_at": "2026-08-01T00:00:00Z",
  "top_services": [
    { "service": "text_translation", "characters": 3200000, "percent": 71.1 },
    { "service": "document_translation", "characters": 800000, "percent": 17.8 },
    { "service": "ai_polishing", "characters": 500000, "percent": 11.1 }
  ],
  "timestamp": "2026-07-22T14:30:00Z"
}

使用限制

Usage Limits

限制项Limit Item上限Cap说明Notes
日期查询范围Date range365 天daysstart_date 到 end_date 最大跨度Max span from start_date to end_date
小时粒度范围Hourly range7 天daysgranularity=hourly 时最大查询范围Max query range for granularity=hourly
单次返回记录数Max records returned744按小时查询 31 天 × 24 小时31 days × 24 hours for hourly queries
请求频率Rate limit30 次/分钟req/min用量统计类接口独立限频Separate rate limit for usage APIs

配额状态说明

Quota Status Reference

状态Status含义MeaningAPI 调用影响Impact on API Calls
normal正常Normal配额使用率 ≤ 80%，一切正常Usage ≤ 80%, no impact
warning预警Warning配额使用率 > 80%，建议升级套餐或预充值Usage > 80%, consider upgrading or prepay
exceeded超限Exceeded配额已用尽，取决于是否开启超量使用；未开启时请求返回 403Quota exhausted; requests return 403 if overtraffic is disabled

最佳实践

Best Practices

建议Suggestion说明Description
定期拉取用量做监控 Periodic usage monitoring 建议每日定时调用 /v1/usage 接口，将数据存入监控系统，提前发现用量异常增长 Call /v1/usage daily, persist data to monitoring systems for early anomaly detection
配置多重告警阈值 Multi-threshold alerts 依次配置 80%/90%/95% 三档 Webhook 告警，在配额用完前有充足的升级和充值时间 Configure 80%/90%/95% three-tier webhook alerts for ample upgrade/prepay time before exhaustion
分服务追踪精细管控 Per-service tracking 通过 /v1/usage/details 对主要服务分别设置监控，快速定位高消耗服务并优化调用逻辑 Monitor each major service via /v1/usage/details; quickly locate high-consumption services and optimize
利用小时粒度分析高峰 Use hourly data for peak analysis 在业务高峰期时段使用 granularity=hourly 定位流量峰值，按需启用限流或横向扩容 Use granularity=hourly during peak hours to identify traffic spikes; enable throttling or scale as needed
缓存用量数据减少 API 调用 Cache usage data 用量数据有约 5 分钟的更新延迟，客户端可按 5~15 分钟间隔缓存，避免高频轮询 Usage data has ~5-min update latency; cache client-side at 5-15 min intervals to avoid frequent polling
将用量集成到业务后台 Integrate into backend 在管理后台嵌入用量仪表盘，方便运营和财务团队实时掌握 API 消费成本 Embed usage dashboards in admin panels for ops and finance teams to track API costs in real time

错误码

Error Codes

HTTP Code错误码Error Code说明Description
2000成功Success
4001001参数错误，请检查必填参数和参数格式Invalid parameter; check required fields and format
4001020日期格式无效，须为 YYYY-MM-DD 格式Invalid date format; must be YYYY-MM-DD
4001021start_date 晚于 end_datestart_date is later than end_date
4001022查询日期范围超出最大跨度（365 天）Date range exceeds max span (365 days)
4001023无效的 granularity，仅支持 daily 和 hourlyInvalid granularity; only daily and hourly supported
4001024hourly 粒度仅支持 7 天内的查询Hourly granularity only available for queries within 7 days
4001025未知的 service 参数，请查阅服务名称参考表Unknown service; see service name reference table
4012001认证失败，Token 无效或已过期Authentication failed; invalid or expired token
4032003无权限访问该资源，或配额已用尽且未开启超量使用Access denied, or quota exhausted with overtraffic disabled
4042004资源不存在Resource not found
4294001请求频率超限，请稍后重试Rate limit exceeded; please retry later
5005001服务器内部错误，请重试或联系技术支持Internal server error; retry or contact support
使用说明
  • 所有用量统计 API 均需使用 Bearer Token 鉴权，请在 控制台 获取。
  • All usage APIs require Bearer Token authentication; obtain from the Console.
  • 用量数据有约 5 分钟更新延迟，短时间内的高频轮询将返回相同结果。
  • Usage data has ~5-minute update latency; frequent polling in short intervals returns the same result.
  • 建议将用量查询与 配额告警 Webhook 结合使用，实现主动推送 + 按需拉取的双重监控。
  • Combine usage queries with quota alert webhooks for dual monitoring: proactive push + on-demand pull.
  • 如配额即将耗尽，可访问控制台自助升级套餐或预充值额度。
  • If quota is running low, upgrade your plan or prepay credit from the console.
← 语种列表Language List 游戏本地化Game Localization →