接口定位:账单明细查询接口。本接口只查询用量记录,不创建生成任务,也不会修改账户余额。
国内环境统一使用 https://app-api.pixverseai.cn。API Key 与请求域名必须属于同一地域。
准备 API Key -> 设置筛选条件 -> 查询首批明细 -> 读取 items -> 根据 has_more 决定是否继续 -> 使用 next_cursor 查询下一页application/json| 参数 | 类型 | 是否必填 | 枚举值 / 示例 | 说明 |
|---|---|---|---|---|
start_time | string | 否 | 2026-06-03 00:00:00 | 查询开始时间,格式为 YYYY-MM-DD HH:mm:ss,时区为 UTC+8;不得晚于 end_time。 |
end_time | string | 否 | 2026-07-02 23:59:59 | 查询结束时间,格式为 YYYY-MM-DD HH:mm:ss,时区为 UTC+8;不得早于 start_time。单次查询时间跨度最大为 30 天。 |
creation_type | array[string] | 否 | 见下方枚举;[] 表示查询全部类型 | 生成类型或对应的 API 能力。 |
credits_status | string | 否 | consume、refund | Credits 变动类型:consume 表示消耗,refund 表示返还。 |
limit | integer | 否 | 2;范围 1-100 | 单次请求返回的最大记录数。官方文档未说明默认值。 |
cursor | string | 否 | 不传或上一页返回的 next_cursor | 分页游标。首次请求可不传;后续请求传入上一页的 next_cursor。如果填"cursor" 上面的筛选条件不会生效 |
creation_type 枚举| 枚举值 | 能力说明 |
|---|---|
text_to_video | 文生视频 |
image_to_video | 图生视频 |
transition | 首尾帧生成视频 |
lip_sync | 对口型 |
extend | 视频延长 |
expand | 视频扩幅 |
sound_effect | 音效生成 |
fusion | 视频参考 / Reference-to-Video |
restyle | 视频重绘 |
multi_transition | 多帧过渡视频 |
swap | 主体替换 |
agent | Agent 类能力;具体产品映射以实际返回为准 |
swap_mask | 主体替换 Mask |
avatar | 图片数字人 |
image_to_image | 图生图 |
mimic | 动作模仿 / Motion Control |
modify | 视频编辑 |
upscale | 超清视频 |
能力类型可能随平台能力更新而增加。客户端应兼容未知新值,不要把枚举写成无法扩展的封闭列表。
{}未设置时间范围时的默认查询窗口未公开。生产环境建议明确填写 start_time、end_time和limit。
has_more: true 时,表示还有更多记录。此时再次调用同一个接口,并将响应中的 next_cursor 原样填入请求 Body 的 cursor,即可获取下一页:首次请求(不传 cursor)
-> 返回 items、has_more: true、next_cursor
-> 再次请求同一接口,并传 cursor: next_cursor
-> 返回下一页 items
-> 重复请求,直到 has_more: false这不是另一个接口,而是重复调用同一个用量查询接口。传入 cursor后,服务端会复用首次查询的筛选条件,并忽略当前请求中的其他筛选参数。需要更换时间或能力筛选条件时,应重新发起不携带旧cursor的首次请求。
| 字段 | 填写建议 |
|---|---|
API-KEY | 使用正式 API Key,不要放在 URL Query、前端代码或公开文档中。 |
Ai-trace-id | 每次请求使用新的 UUID,便于日志追踪 和问题排查。 |
start_time / end_time | 使用 UTC+0 时间,格式必须一致;单次跨度不超过 30 天。 |
creation_type | 传 [] 查询全部类型;只查询指定能力时传一个或多个公开枚举值。 |
credits_status | 仅支持 consume、refund;不要填写展示文案或其他近义词。 |
limit | 仅允许 1-100。大批量导出时应结合游标分页,不要假设一次可返回全部记录。 |
cursor | 只能使用接口返回的 next_cursor 原样传递,不要自行拼接或解析。 |
| 字段 | 类型 | 是否必返 | 说明 |
|---|---|---|---|
ErrCode | integer | 是 | 业务错误码,0 表示成功。 |
ErrMsg | string | 是 | 业务信息;成功示例为 Success。 |
Resp | object | 是 | 用量明细响应对象。 |
Resp.items | array[object] | 是 | 当前页的用量记录。没有符合条件的记录时应按实际响应处理。 |
Resp.next_cursor | string | 是 | 下一页游标。has_more = true 时,将此值传入下一次请求。 |
Resp.has_more | boolean | 是 | 是否还有下一页。true 表示仍有更多记录,false 表示已到最后一页。 |
当前成功响应示例 返回布尔值。接口页面的 Schema 类型标注与示例存在差异,接入时应以实际响应为准。
Resp.items[] 记录字段items[] 的完整 Schema,因此可空性及所有可能取值应以实际响应为准。| 字段 | 示例类型 | 说明 |
|---|---|---|
record_id | string | 用量记录 ID。 |
api_key_name | string | 产生该记录的 API Key 名称;示例中可为空字符串。 |
video_id | string | null | 关联的视频任务 ID;非视频任务或无关联任务时可能为空。 |
image_id | string | null | 关联的图片任务 ID;非图片任务或无关联任务时可能为空。 |
creation_type | string | 产生用量的能力类型。 |
event_type | string | Credits 事件类型;示例为 consume。 |
credit_source | string | Credits 来源;示例为 package。 |
credits | integer | 本条记录对应的 Credits 数量。 |
created_at | string | 记录创建时间。示例格式为 YYYY-MM-DD HH:mm:ss。 |
model | string | 使用的模型版本,例如 v6。 |
quality | string | 使用的清晰度档位,例如 720p。 |
billing_duration_seconds | integer | 参与计费的时长,单位为秒;不按时长计费的记录可能为 0。 |
sound_effect_switch | boolean | 是否启用音效生成。 |
lip_sync_switch | boolean | 是否启用对口型。 |
generate_multi_shot_clip_switch | boolean | 是否启用多镜头片段生成。 |
generate_audio_switch | boolean | 是否启用音频生成。 |
{
"ErrCode": 0,
"ErrMsg": "Success",
"Resp": {
"items": [
{
"record_id": "123",
"api_key_name": "",
"video_id": "xx",
"image_id": null,
"creation_type": "text_to_video",
"event_type": "consume",
"credit_source": "package",
"credits": 45,
"created_at": "2026-08-05 10:42:41",
"model": "v6",
"quality": "720p",
"billing_duration_seconds": 0,
"sound_effect_switch": false,
"lip_sync_switch": false,
"generate_multi_shot_clip_switch": false,
"generate_audio_switch": true
}
],
"next_cursor": "",
"has_more": false
}
}示例中的 ID 和任务信息为占位数据,不应直接用于真实业务请求。
200。ErrCode 是否为 0,不要只根据 ErrMsg 文案判断成功。Resp.items 处理当前页记录。Resp.has_more = true 时,保存 Resp.next_cursor 并继续请求下一页。Resp.has_more = false 时,分页结束。created_at 的时区在官方页面中未单独说明;不要仅根据示例推断其一定为 UTC+0。credits_status 用于筛选,响应中的对应事件字段名为 event_type;不要把两个字段名混用。Resp.items[] 可能随能力类型返回不同的关联信息,客户端应兼容新增字段和可空字段。creation_type、model、quality 和开关字段应按实际响应展示,不建议客户端自行推导计费金额。curl --location 'https://app-api.pixverseai.cn/openapi/v2/account/billing/usage-detail' \
--header 'API-KEY: your-api-key' \
--header 'Ai-trace-id: your-ai-trace-id' \
--header 'Content-Type: application/json' \
--data '{
"start_time": "2026-08-01 00:00:00",
"end_time": "2026-08-19 23:59:59",
"creation_type": [
],
"credits_status": [
],
"limit": 20,
"cursor": ""
}'{
"ErrCode": 0,
"ErrMsg": "Success",
"Resp": {
"items": [
{
"record_id": "123",
"api_key_name": "",
"video_id": "xx",
"image_id": null,
"creation_type": "text_to_video",
"event_type": "consume",
"credit_source": "package",
"credits": 45,
"created_at": "2026-08-05 10:42:41",
"model": "v6",
"quality": "720p",
"billing_duration_seconds": 0,
"sound_effect_switch": false,
"lip_sync_switch": false,
"generate_multi_shot_clip_switch": false,
"generate_audio_switch": true
}
],
"next_cursor": "",
"has_more": false
}
}