curl --request POST 'https://api.voicecheap.ai/v1/actions/usage_logs_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"view":"translation","fromDate":"2026-10-01","toDate":"2026-10-16","page":1,"pageSize":25}'
const input = {
view: 'translation',
fromDate: '2026-10-01',
toDate: '2026-10-16',
page: 1,
pageSize: 25,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/usage_logs_list', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/usage_logs_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"view": "translation", "fromDate": "2026-10-01", "toDate": "2026-10-16", "page": 1, "pageSize": 25},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"exportedAt": 1792152000000,
"scope": "user",
"plan": "pro",
"view": "translation",
"filters": {
"view": "translation",
"lipSyncUsage": "all",
"translationStatuses": [],
"billingState": "all",
"fromDate": "2026-10-01",
"toDate": "2026-10-16"
},
"pagination": {
"page": 1,
"pageSize": 25,
"totalItems": 1,
"totalPages": 1
},
"totals": {
"translationBaseMinutes": 2,
"lipSyncExtraMinutes": 0,
"lipSyncProExtraMinutes": 0,
"lipSyncPro2ExtraMinutes": 0,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2
},
"rows": [
{
"projectId": "project_123",
"projectName": "Product launch",
"workId": "work_123",
"translatedVersionId": "version_123",
"sourceLanguage": "english",
"targetLanguage": "french",
"startedAt": 1792065600000,
"endedAt": 1792065720000,
"startedByUserId": "user_123",
"translationStatus": "completed",
"lipSyncUsage": "none",
"lipSyncStatus": "not_used",
"runNumber": 1,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2,
"billingState": "charged"
}
]
}
}
用量和活动
列出媒体用量
分页获取翻译和口型同步的分钟消耗、扣除和退还历史记录,可按日期、语言、状态和项目筛选。
POST
/
v1
/
actions
/
usage_logs_list
curl --request POST 'https://api.voicecheap.ai/v1/actions/usage_logs_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"view":"translation","fromDate":"2026-10-01","toDate":"2026-10-16","page":1,"pageSize":25}'
const input = {
view: 'translation',
fromDate: '2026-10-01',
toDate: '2026-10-16',
page: 1,
pageSize: 25,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/usage_logs_list', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/usage_logs_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"view": "translation", "fromDate": "2026-10-01", "toDate": "2026-10-16", "page": 1, "pageSize": 25},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"exportedAt": 1792152000000,
"scope": "user",
"plan": "pro",
"view": "translation",
"filters": {
"view": "translation",
"lipSyncUsage": "all",
"translationStatuses": [],
"billingState": "all",
"fromDate": "2026-10-01",
"toDate": "2026-10-16"
},
"pagination": {
"page": 1,
"pageSize": 25,
"totalItems": 1,
"totalPages": 1
},
"totals": {
"translationBaseMinutes": 2,
"lipSyncExtraMinutes": 0,
"lipSyncProExtraMinutes": 0,
"lipSyncPro2ExtraMinutes": 0,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2
},
"rows": [
{
"projectId": "project_123",
"projectName": "Product launch",
"workId": "work_123",
"translatedVersionId": "version_123",
"sourceLanguage": "english",
"targetLanguage": "french",
"startedAt": 1792065600000,
"endedAt": 1792065720000,
"startedByUserId": "user_123",
"translationStatus": "completed",
"lipSyncUsage": "none",
"lipSyncStatus": "not_used",
"runNumber": 1,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2,
"billingState": "charged"
}
]
}
}
分页获取翻译和口型同步的分钟消耗、扣除和退还历史记录,可按日期、语言、状态和项目筛选。
所需权限:
POST https://api.voicecheap.ai/v1/actions/usage_logs_list
身份验证和权限
string
必填
在此请求头中发送 VoiceCheap API 密钥。也支持通过 Authorization: Bearer 发送同一 API 密钥。OAuth 访问令牌仅适用于 MCP,此 REST 端点不接受 OAuth
访问令牌。
usage:read.
需要有效的付费订阅。权限不会改变团队角色、资源归属、媒体额度或套餐限制。
参数
string
文本值。允许的值: “translation”, “project”. 默认值: “translation”.
string
文本值。最小长度: 1. 最大长度: 200. 匹配模式:
^[^/]+$.string
文本值。最小长度: 1. 最大长度: 200.
string
文本值。最小长度: 2. 最大长度: 64.
string
文本值。允许的值: “all”, “none”, “standard”, “pro”, “pro_2”.
array
值列表。项目结构请参阅完整输入架构。最多项目数: 4.
string
文本值。允许的值: “all”, “charged”, “refunded”, “refund_pending”.
string
文本值。格式: “date”. 匹配模式:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$.string
文本值。格式: “date”. 匹配模式:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$.integer
整数值。最小值: 1. 最大值: 100000. 默认值: 1.
integer
整数值。最小值: 1. 最大值: 100. 默认值: 25.
完整输入架构
完整输入架构
以下 JSON Schema 保留了发现接口公开的确切字段名、嵌套类型、默认值、范围和可接受值。其他跨字段规则列于操作说明中。
{
"type": "object",
"properties": {
"view": {
"default": "translation",
"type": "string",
"enum": ["translation", "project"]
},
"translatedVersionId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/]+$"
},
"project": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"targetLanguage": {
"type": "string",
"minLength": 2,
"maxLength": 64
},
"lipSyncUsage": {
"type": "string",
"enum": ["all", "none", "standard", "pro", "pro_2"]
},
"translationStatuses": {
"maxItems": 4,
"type": "array",
"items": {
"type": "string",
"enum": ["in_progress", "completed", "failed", "timed_out"]
}
},
"billingState": {
"type": "string",
"enum": ["all", "charged", "refunded", "refund_pending"]
},
"fromDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"toDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"page": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"pageSize": {
"default": 25,
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"additionalProperties": false
}
请求示例
请将示例资源标识符和媒体键替换为账户返回的值。重试同一次修改操作时,请保持请求标识符不变。curl --request POST 'https://api.voicecheap.ai/v1/actions/usage_logs_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"view":"translation","fromDate":"2026-10-01","toDate":"2026-10-16","page":1,"pageSize":25}'
const input = {
view: 'translation',
fromDate: '2026-10-01',
toDate: '2026-10-16',
page: 1,
pageSize: 25,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/usage_logs_list', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/usage_logs_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"view": "translation", "fromDate": "2026-10-01", "toDate": "2026-10-16", "page": 1, "pageSize": 25},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
响应
首次执行成功时返回 HTTP 200,操作结果位于 data 下。重放请求时可能改为返回已保存的请求状态。示例展示了一种支持的响应,并未包含所有可选字段。 返回分页的翻译或项目用量行、规范化筛选条件,以及所有匹配行的分钟总数。{
"data": {
"exportedAt": 1792152000000,
"scope": "user",
"plan": "pro",
"view": "translation",
"filters": {
"view": "translation",
"lipSyncUsage": "all",
"translationStatuses": [],
"billingState": "all",
"fromDate": "2026-10-01",
"toDate": "2026-10-16"
},
"pagination": {
"page": 1,
"pageSize": 25,
"totalItems": 1,
"totalPages": 1
},
"totals": {
"translationBaseMinutes": 2,
"lipSyncExtraMinutes": 0,
"lipSyncProExtraMinutes": 0,
"lipSyncPro2ExtraMinutes": 0,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2
},
"rows": [
{
"projectId": "project_123",
"projectName": "Product launch",
"workId": "work_123",
"translatedVersionId": "version_123",
"sourceLanguage": "english",
"targetLanguage": "french",
"startedAt": 1792065600000,
"endedAt": 1792065720000,
"startedByUserId": "user_123",
"translationStatus": "completed",
"lipSyncUsage": "none",
"lipSyncStatus": "not_used",
"runNumber": 1,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2,
"billingState": "charged"
}
]
}
}
结果字段
| 字段 | 说明 |
|---|---|
data.exportedAt | 结果生成时间,以 Unix 毫秒时间戳表示。 |
data.scope | 个人账户使用 user;当前账户拥有或加入的团队使用 team。 |
data.plan | 工作区所有者的套餐。 |
data.view | 与所请求视图对应的 translation 或 project。 |
data.filters | 已应用的规范化筛选条件;分页信息单独返回。 |
data.pagination.page | 根据可用页码范围调整后返回的页码。 |
data.pagination.pageSize | 每页行数。 |
data.pagination.totalItems | 分页前匹配行的总数。 |
data.pagination.totalPages | 页数;即使结果为空,也至少为一页。 |
data.totals.translationBaseMinutes | 匹配行收取的基础翻译分钟数总计。 |
data.totals.lipSyncExtraMinutes | 额外计费的 Standard 口型同步分钟数。 |
data.totals.lipSyncProExtraMinutes | 额外计费的 Pro 口型同步分钟数。 |
data.totals.lipSyncPro2ExtraMinutes | 额外扣除的 Pro 2 口型同步分钟数。 |
data.totals.totalChargedMinutes | 退还前扣除的总分钟数。 |
data.totals.refundedMinutes | 已退还的分钟数。 |
data.totals.netUsedMinutes | 扣除的分钟数减去退还的分钟数。 |
data.rows | 翻译视图中的翻译行,或项目视图中的项目汇总。 |
data.rows[].projectId | 项目标识符。 |
data.rows[].projectName | 项目显示名称。 |
data.rows[].workId | 翻译视图中包含的语言内容标识符。 |
data.rows[].translatedVersionId | 翻译视图中包含的翻译版本标识符。 |
data.rows[].sourceLanguage | 源语言。 |
data.rows[].targetLanguage | 翻译视图中的目标语言。 |
data.rows[].startedAt | 翻译视图中的翻译开始时间戳,单位为毫秒。 |
data.rows[].endedAt | 翻译视图中可选的翻译或口型同步结束时间戳,单位为毫秒。 |
data.rows[].startedByUserId | 翻译视图中可选的发起账户标识符。 |
data.rows[].translationStatus | 翻译视图中的 in_progress、completed、failed 或 timed_out。 |
data.rows[].lipSyncUsage | 翻译视图中的 none、standard、pro 或 pro_2。 |
data.rows[].lipSyncStatus | 翻译视图中的 not_used、in_progress、completed、failed 或 timed_out。 |
data.rows[].runNumber | 翻译视图中,此项目和目标语言下的翻译执行编号。 |
data.rows[].createdAt | 项目视图中的项目创建时间戳,单位为毫秒。 |
data.rows[].targetLanguages | 项目视图中项目汇总所涵盖的目标语言。 |
data.rows[].runCount | 项目视图中,该项目匹配的翻译执行次数。 |
data.rows[].translationSummary | 项目视图中的计数:inProgress、completed、failed、timedOut 和 retryCount。 |
data.rows[].lipSyncSummary | 项目视图中的计数:inProgress、completed、failed、timedOut、retryCount 和 notUsed。 |
data.rows[].totalChargedMinutes | 此行退还前扣除的总分钟数。 |
data.rows[].refundedMinutes | 此行已退还的分钟数。 |
data.rows[].netUsedMinutes | 此行扣除的分钟数减去退还的分钟数。 |
data.rows[].billingState | charged、refunded 或 refund_pending。 |
操作说明
- view 默认为 translation,page 默认为 1,pageSize 默认为 25;pageSize 不得超过 100。
- 日期筛选使用 YYYY-MM-DD,并按 Europe/Paris 的翻译开始日期进行比较。fromDate 不能晚于 toDate。
- project 不区分大小写地搜索项目名称和 ID。translatedVersionId 在 translation 视图中以子字符串匹配版本 ID,在 project 视图中会被忽略。
- 总计涵盖分页前所有匹配的翻译行。项目视图会按项目汇总这些行。
- 公开行会省略发起用户的电子邮件地址和原始处理错误消息。
用量
每次成功调用消耗一次月度 API/MCP 调用额度。媒体额度和操作本身的生成限额也适用。错误
| HTTP 状态 | 代码 | 含义或恢复方式 |
|---|---|---|
| 400 | CREDENTIAL_IN_QUERY | 凭证通过 access_token 或 api_key 查询参数提供。请在标头中发送凭证。 |
| 400 | VALIDATION_ERROR | JSON 对象包含不受支持的字段、无效值,或缺少必需参数。 |
| 401 | API_KEY_EXPIRED | API 密钥已过期。 |
| 401 | INVALID_API_KEY | 请提供有效且未过期的 API 密钥。 |
| 401 | INVALID_CREDENTIAL | Authorization 标头格式错误或与 x-api-key 冲突。 |
| 401 | MISSING_CREDENTIAL | 未提供可用的请求头凭据,或其长度超过 4096 个字符。 |
| 401 | USER_NOT_FOUND | 该凭据对应的账户已不存在。 |
| 403 | AMBIGUOUS_TEAM_API_KEY | 此凭据对应的用户属于多个团队,因此计费上下文不明确。 |
| 403 | INSUFFICIENT_SCOPE | 请授予全部所需权限,或选择其他凭据。 |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | 无法验证该账户的集成限制。 |
| 403 | SUBSCRIPTION_REQUIRED | 请使用有效的付费订阅。 |
| 403 | TEAM_MEMBERSHIP_INVALID | 账户当前的团队成员关系与此连接的工作区不匹配。请刷新成员关系并重新连接。 |
| 403 | TEAM_OWNER_NOT_FOUND | 找不到实际生效的团队所有者账户。 |
| 404 | ACCOUNT_NOT_FOUND | 找不到账户或当前工作区账户。 |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | 请等待月度额度重置,或更改套餐。 |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | 如果提供了 Retry-After,请等待其指定的时间,并采用退避重试。 |
| 500 | INTERNAL_ERROR | 在决定是否重试修改操作前,请检查已保存的请求状态和资源历史记录。 |
| 503 | SERVER_RESTARTING | 服务器正在重启。请稍后重试;对于修改操作,请保持请求标识符不变。 |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["usage:read"]
}
}
此页面对您有帮助吗?

