API 参考 / 账务

查询账务分录

listLedger

GET/v1/ledger

下面的接口说明为英文原文。

listLedger

Markdown 文件在 Playground 试运行文档版本 r15

鉴权

在请求头带上项目 Key，例如 Authorization: Bearer $VIZO_API_KEY。Key 只放在服务端。

查询参数

查询参数
字段	说明
cursorstring可选	上一页返回的游标。最多 19 个字符
limitinteger可选	每页条数。最小 1, 最大 100, 默认 50

响应

200 OK

字段

说明

itemsobject[], 可为 null必填

items 的字段

items 的字段
created_atdate-time必填
creditsstring必填
fromstring必填
idstring必填
referencestring必填
tostring必填

next_cursorstring可选

作为 cursor 传入以读取下一页。最后一页为空。

错误

所有错误使用同一种响应体。联系支持时请附上 request_id。

错误响应体

字段

说明

errorobject必填

错误详情。

error 的字段

error 的字段
codestring必填	稳定的错误码，用它判断分支。
messagestring必填	可读的说明，不要解析它。
request_idstring必填	联系支持时请附上。
retryableboolean必填	仅 429 和 503 为 true。即便如此，重发创建请求前也要先查看近期任务。
task_idstring可选	错误所属的任务（如果有）。

错误
状态码	含义与处理
400	请求无法解析。对照上面的表格检查查询参数的取值。
401	Key 缺失、格式错误、已过期或已撤销。在服务端更正 Key 后继续。
403	Key 权限、邮箱验证、预算上限或账户限制阻止了操作。检查 Key 类型、权限和项目预算。
404	模型或资源不存在，或不在当前项目范围内。确认项目、ID 和模型是否已开通。
409	请求与当前状态冲突。重新读取资源，再决定是否重新发送。
422	字段或取值无效。对照字段表和模型页修改请求。
500	服务端出错，任务可能已经受理。不要直接重发，先查看近期任务。
503	服务暂时不可用。创建请求要先查看近期任务，确认没有受理，再重新提交。

请求示例

cURL

curl "https://api.vizoapi.com/v1/ledger?limit=20" \
  -H "Authorization: Bearer $VIZO_API_KEY"

Python

import os, requests

res = requests.get(
    "https://api.vizoapi.com/v1/ledger?limit=20",
    headers={"Authorization": f"Bearer {os.environ['VIZO_API_KEY']}"},
    timeout=60,
)
print(res.status_code, res.json())

Node.js

const res = await fetch("https://api.vizoapi.com/v1/ledger?limit=20", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
  },
});
console.log(res.status, await res.json());

响应 200

{
  "items": [
    {
      "created_at": "2026-11-02T08:01:43Z",
      "credits": "1400.000",
      "from": "wallet:held",
      "id": "gen_01JD8Z5QW3XR",
      "reference": "gen_01JD8Z5QW3XR",
      "to": "platform:settled"
    }
  ],
  "next_cursor": ""
}

响应 400

{
  "error": {
    "code": "invalid_request",
    "message": "The request could not be read.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

响应 401

{
  "error": {
    "code": "invalid_credentials",
    "message": "API key is missing, malformed, expired or revoked.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

响应 403

{
  "error": {
    "code": "scope_denied",
    "message": "The key does not allow this operation for this project.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

响应 404

{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is not available to this project.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

响应 409

{
  "error": {
    "code": "conflict",
    "message": "The request conflicts with the current state of the resource.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

响应 422

{
  "error": {
    "code": "invalid_input",
    "message": "Input does not match the published schema.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

响应 500

{
  "error": {
    "code": "request_failed",
    "message": "The request failed. Check recent generations before submitting again.",
    "retryable": false,
    "request_id": "9f2c41d07ab3e5c8"
  }
}

响应 503

{
  "error": {
    "code": "temporarily_unavailable",
    "message": "Service is temporarily unavailable.",
    "retryable": true,
    "request_id": "9f2c41d07ab3e5c8"
  }
}