获取用量扣减情况

查询当前账号的 Credits 消耗与返还明细。接口支持按时间、能力类型和 Credits 状态筛选，并通过游标连续获取多页记录。

接口定位：账单明细查询接口。本接口只查询用量记录，不创建生成任务，也不会修改账户余额。

接口地址

国内环境统一使用 https://app-api.pixverseai.cn。API Key 与请求域名必须属于同一地域。

接入流程

准备 API Key -> 设置筛选条件 -> 查询首批明细 -> 读取 items -> 根据 has_more 决定是否继续 -> 使用 next_cursor 查询下一页

请求参数

Body 参数

请求体类型：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`	视频延长
`sound_effect`	音效生成
`fusion`	视频参考 / Reference-to-Video
`restyle`	视频重绘
`multi_transition`	多帧过渡视频
`swap`	主体替换
`agent`	Agent 类能力；具体产品映射以实际返回为准
`swap_mask`	主体替换 Mask
`avatar`	图片数字人
`image_to_image`	图生图
`mimic`	动作模仿 / Motion Control
`modify`	视频编辑
`upscale`	超清视频

能力类型可能随平台能力更新而增加。客户端应兼容未知新值，不要把枚举写成无法扩展的封闭列表。

最小请求示例

所有 Body 筛选字段均为可选，因此最小 JSON 请求体可写为：

{}

未设置时间范围时的默认查询窗口未公开。生产环境建议明确填写 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 和任务信息为占位数据，不应直接用于真实业务请求。

响应判断

先检查 HTTP 状态码是否为 200。

再检查 ErrCode 是否为 0，不要只根据 ErrMsg 文案判断成功。

遍历 Resp.items 处理当前页记录。

当 Resp.has_more = true 时，保存 Resp.next_cursor 并继续请求下一页。

当 Resp.has_more = false 时，分页结束。

注意事项

单次时间范围最大为 30 天。查询更长周期时，应拆分时间窗口后分别分页。

created_at 的时区在官方页面中未单独说明；不要仅根据示例推断其一定为 UTC+0。

分页游标应原样传递。携带游标时，当前请求中的其他筛选条件会被忽略。

请求字段 credits_status 用于筛选，响应中的对应事件字段名为 event_type；不要把两个字段名混用。

Resp.items[] 可能随能力类型返回不同的关联信息，客户端应兼容新增字段和可空字段。

creation_type、model、quality 和开关字段应按实际响应展示，不建议客户端自行推导计费金额。

Credits 明细用于用量核对；最终扣费与返还仍以账户账本及适用的商务协议为准。

获取用量扣减情况