Skip to main content

接口概述

日志查询接口返回你账号下每一次 API 调用的明细记录,包括调用的模型、实际扣费、耗时、 是否流式、以及失败时的错误码。 它和余额查询 API 是互补的:余额查询告诉你「现在还剩多少钱」, 日志查询告诉你「钱花在哪了」。 三类典型用途:

自动对账

按时间段、按模型统计实际消费,与自己的业务账单核对

故障自查

查失败请求的错误码,定位是参数问题还是上游问题

报障提工单

拿到 request_id 给客服,能精确定位到那一次调用
控制台也能看日志(「日志」页面)。本接口是同一份数据的程序化入口,适合需要自动化对账、 定时导出、或接入自己监控系统的场景。手动查看请直接用控制台,见 如何查看我的调用记录
推荐用法:每天同步一次,把日志落到你自己的库里。这个接口是为「定时增量导出」设计的,不适合当成实时查询接口反复调用:
  • 每天跑一次,只拉「上次同步之后」的新记录,写进你自己的数据库或 CSV
  • 一次多取一些pageSize 最大 5000,别用默认的 10 —— 详见下方参数说明里的常见陷阱
  • 不要用它做全量回溯(例如一次性拉三个月),也不要在页面上做实时翻页
  • 不要并发调用,串行一页一页拉,页与页之间留 1 秒左右间隔
  • 时间窗跨度建议不超过 1 天;调用量大的账号按小时切
原因见下方「性能须知」一节:时间窗越老、翻页越深,单次请求的开销涨得很快, 超过服务端上限会直接返回错误,重试同样的参数也不会变快。 本页的 Python 示例已经按这个模式写好,可以直接拿去当每日定时任务用。

如何获取系统令牌

日志接口用系统令牌认证,与 API Key 不是一回事(详见文末注意事项)。
1

访问控制台

访问 api.apiyi.com/account/profile 个人中心页面
2

找到系统令牌

在页面最下方找到「账号选项 - 系统令牌」部分
3

生成 AccessToken

输入当前的账户密码后,会得到一个 AccessToken,该密钥可用于后续接口的查询数据
获取系统令牌

接口信息

请求说明

请求 Headers

查询参数

时间窗请当成必填参数。接口本身不强制这两个参数 —— 不传也能调通。但不传意味着让服务端在你账号的全部历史里 从最新往回找,历史调用量大的账号会直接撞上服务端上限、返回错误而不是慢一点这是本页最容易踩、后果也最直接的一个坑。我们把它标成「必传」不是因为服务端会拒绝, 而是因为不传的失败方式很难自己看出来:它不报「参数缺失」,只报超时。
pageSize 是本接口唯一使用驼峰命名的参数,写成 page_size 会被静默忽略。其余参数(model_nametoken_namestart_timestamprequest_id …)都是下划线命名, 只有这一个不是。写错不会报错,服务端会当作没传、回落到默认的每页 10 条 —— 很容易被误认为「上限就是 10」或者「我这段时间只有 10 次调用」。
超过 5000 会明确报错(每页条数不能超过 5000),不会静默截断。
pageSize 调大是这个接口最有效的一个优化。 按每页 10 条拉, 一个每天 50 万次调用的账号需要请求 5 万次;按每页 5000 条只要 100 次。 请求数少两个数量级,翻页深度也随之降下来 —— 参见下方「性能须知」。实测每页 5000 条的响应约 700 KB(gzip 后)、2.5 秒左右。 如果你的网络或内存吃紧,1000 是个稳妥的折中值。

性能须知

单次请求的开销不是固定的,取决于三个因素。按这三条来用,这个接口很快; 反着用,会直接撞上服务端 60 秒的单条查询上限并返回错误。 四条实用规则:
  1. 一定要传 start_timestampend_timestamp 不传时间窗是最贵的用法。
  2. pageSize 调大。 这是最省事的一条:每页 10 条改成每页 1000~5000 条, 请求数直接降两个数量级,偏移量也跟着降。
  3. 窗口切小、而不是把偏移量翻深。 真正贵的不是「第几页」而是「跳过了多少条」—— 这个开销是超线性增长的。与其在一个大窗口里一路翻下去, 不如切成 24 个一小时的小窗口,每个窗口的偏移量都从 0 开始。
  4. 拉历史数据一次拉完就落库,之后只做增量。 老数据的查询成本比新数据高得多, 反复回查同一段历史是纯浪费。
如果某个窗口用 pageSize=1000 还翻了几十页才结束,说明这段时间你的调用量很大 —— 把窗口对半切开分别拉,比继续往深处翻页快得多。下方 Python 示例里的 MAX_PAGES 就是干这件事的。

60 秒是硬上限,超了返回的是错误

服务端对单次查询有 60 秒的执行上限。超过这个时间,你拿到的不是一个慢响应, 而是一个错误 —— 已经花掉的时间不会给你任何数据。 以下三种用法很可能触发它,请直接避开,不要靠重试去碰运气: 重试同样的参数不会变快,只会再等 60 秒。正确的反应是把时间窗缩小、 或者把 pageSize 调大以减少翻页 —— 换句话说,让服务端每次要处理的数据量变小。

日志类型 type

统计花费时务必带上 type=2 不传 type 会把充值、系统赠送记录一起返回, 这些记录的 quota 虽然是 0,但 model_nametoken_name 也是空的, 直接遍历求和或按模型分组会得到错误结果。用到视频类异步模型(Seedance 等)的账号,请再拉一遍 type=11:任务失败时预扣额以负数退款行退回,只算 type=2 会把失败单的预扣额当成消费。

响应说明

成功响应示例

关键响应字段

other 字段存的是一段 JSON 字符串而不是嵌套对象,取用前需要再解析一次 (Python 用 json.loads(),JavaScript 用 JSON.parse())。里面包含 billing_type(计费方式)、request_path(实际调用的端点)、group_ratio(分组倍率)、 model_ratio(模型倍率)、usage(用量明细)等。视频类异步任务的结算记录里另有 final_quota(该任务最终总额)、original_quota(提交时的预扣额)、 adjustment_quota(本条记录的差额)、actual_tokens(实际用量),见下方常见问题。

额度换算

换算规则

500,000 额度 = $1.00 美金 (USD)
计算公式: 美金金额 = quota ÷ 500,000 示例:
  • quota: 7500 → $0.015 USD
  • quota: 22500 → $0.045 USD
  • quota: 18 → $0.000036 USD
这与余额查询 API 是同一套换算口径,可以直接对齐。

错误响应

HTTP 401 - 认证失败

原因: 系统令牌无效、已过期,或误把 API Key(sk- 开头)当成系统令牌使用。 解决方法: 回控制台重新生成系统令牌,确认 Authorization 里填的是不带 Bearer 前缀的裸值。

代码示例

cURL 示例(单页,快速验证)

必须添加 --compressed 选项,因为 API 返回的是 gzip 压缩内容,否则会得到乱码。
这条命令用来验证令牌配好了没有。真正的对账请用下面的每日同步脚本。

Python 示例:每日增量同步(可直接当定时任务用)

下面这段是推荐的标准用法:每天跑一次,只拉上次同步之后的新记录,写进本地 SQLite。 重复运行是安全的(按 request_id 去重),中断之后重跑会从断点继续。
输出示例:
落库之后,按模型、按天、按令牌的各种统计都在你自己的库里做,不需要再回头查接口。 这既快得多,也避免了「日志保留期到了、想查的数据已经不在」的问题。

Node.js 示例(单个时间窗)

同样的思路:按小时切窗口、串行翻页、翻太深就把窗口切小。
fetch 会自动处理 gzip 解压,Node.js 侧无需额外配置(Python 的 requests 同理)。 只有 curl 需要显式加 --compressed

典型场景

场景一:每日对账(推荐做法)

把上面的 Python 脚本挂成每天一次的定时任务,日志落到本地库; 统计花费、按模型分组、按令牌拆分这些事,全部在你自己的库里用 SQL 做。 这样做有三个好处:查询是本地的所以很快;不受日志保留期影响; 也不会因为反复回查历史数据而拖慢接口。 如果只想同步某个模型的记录,在请求参数里加 model_name 即可。

场景二:找出失败的调用

落库之后直接查本地表:
被网关拒绝的请求(参数错误等)quota 为 0,不产生扣费。日志里能看到 error_code, 方便你区分「调用失败了」和「调用成功但结果不满意」。

场景三:报障时提供 request_id

在日志里定位到出问题的那次调用,把 request_id 提供给客服,可以精确查到该次请求的 完整链路。这比描述「大概几点调用 xx 模型失败了」高效得多。

常见问题

先检查这三件事,绝大多数慢查询都出在这里:
  1. 有没有传 start_timestamp / end_timestamp 不传时间窗是最贵的用法, 服务端会在你的全部历史里回溯。
  2. 时间窗是不是太老或太宽? 查一个月前的数据比查昨天贵得多; 跨度也建议压到 1 天以内,量大的账号按小时切。
  3. p 是不是已经翻到几千页? 翻页开销是超线性增长的。 正确的做法是把时间窗切小、让每个窗口只翻几十页,而不是在一个大窗口里往深处翻。
重试同样的参数不会变快。 遇到超时请按上面三条调整参数, 而不是原样重试 —— 原样重试只会再等一次。
十有八九是参数名写成了下划线的 page_size正确的写法是驼峰 pageSize。这是本接口唯一一个驼峰参数,其余(model_nametoken_namestart_timestamp 等)都是下划线,很容易顺手写错。 写错不会报错,服务端会当作没传、回落到默认的每页 10 条。
最大 5000,超过会明确报错。数据量大时仍然需要翻页(p=0p=1 …), 翻到返回空数组为止 —— 上面的 Python 与 Node.js 示例已经封装好这个逻辑。
可以,传 request_id 即可,命中时只返回那一条:
排查某一次具体调用时,这比按时间段拉一堆记录再筛要快得多。
不是。部分字段属于平台内部信息,普通账号视角下为空或 0,属正常现象, 不影响对账与排障需要的字段(quotamodel_nameerror_coderequest_id 等都是完整的)。
接口返回的是分组的标识符,控制台显示的是分组的展示名,两者可能不同。 例如接口返回 default,控制台显示「Default」。完整的对应关系可以从公开接口 https://api.apiyi.com/api/pricingusable_group 字段获取,它是一个「标识符 → 展示名」的映射表。如果你要让自己的报表和控制台显示一致, 需要自己做一次映射。
quota 为准。quota 是本次调用实际扣除的额度,是唯一可用于对账的字段。 响应体里的 token 数在部分按次计费的模型(如出图、视频类)上可能是占位值, 不参与计价 —— 这类模型的计价方式在 other.billing_type 里会标为 by_count
请按「只有最近 30 天可查」来设计你的同步逻辑。实际可查询的范围通常比 30 天更长,但我们不对保留期做承诺 —— 它会随日志清理策略调整,而且不会单独通知。把 30 天当成规划下限, 你的对账流程就不会因为清理策略变化而断掉。另外,越老的时间窗查询成本越高,即使数据还在,查起来也慢得多。所以正确的用法是每天同步一次、把数据落到你自己的库里,历史统计在本地做。 需要长期留存的账单数据,请务必自行归档,不要依赖这个接口回查。
原因: API 返回的是 gzip 压缩内容(Content-Encoding: gzip),curl 没有自动解压。解决方案: 添加 --compressed 选项:
Python 的 requests 与 Node.js 的 fetch 会自动解压,无需额外配置。
Seedance 等异步视频任务按「提交时预扣、完成后多退少补」计费,所以一条视频在日志里是两条记录: 预扣行(completion_tokens 为 0、有 request_id)和结算行(completion_tokens 是实际用量、 request_id 为空quota 只记差额)。两条记录里都没有 task_id,本接口没法按任务逐单配对。要查一条视频的真实消费,请用任务接口按 task_id 查,返回的 quota 就是两条之和:
注意它的分页参数是下划线 page_sizep 从 1 开始,与本接口相反。 失败的任务 quota 仍显示预扣额,真实消费为 0(日志里有 type=11 的负数退款行)。 完整说明见 如何按 task_id 查一条 Seedance 视频的真实消费
不会。日志查询接口不消耗任何配额。

注意事项

系统令牌不是 API Key,两者不能互换
  • API Keysk- 开头)用于 /v1/* 推理端点,拿去调 /api/log/self 会返回 401
  • 系统令牌(一串不带前缀的字符)用于 /api/* 管理端点,拿去调 /v1/chat/completions 会返回 Invalid token
系统令牌的权限范围覆盖整个账号,请像保管账号密码一样保管它:存进密钥管理工具而不是代码, 不要提交进代码仓库,定期轮换。
日志响应里含有你自己的 API Key 明文日志记录会返回发起该次调用的令牌信息。不要把日志的原始响应直接贴到公开场合、 截图发群、或转交给第三方,导出前先剔除敏感字段。特别提醒:这段明文不带 sk- 前缀,常见的密钥扫描工具可能扫不出来, 不要依赖自动化检查兜底。
建议的调用节奏
  • 每天同步一次即可,不需要更频繁;同步的是「上次之后的增量」
  • pageSize 用 1000~5000,不要用默认的 10 —— 这一条比其它几条加起来都管用
  • 串行调用,页与页之间间隔 1 秒左右,不要并发
  • 客户端超时设成 60 秒(服务端单条查询的上限也是 60 秒)
  • 每个时间窗的跨度不超过 1 天;调用量大的账号按小时切
  • 遇到超时先缩小时间窗再重试,原样重试不会变快
这些不是硬性配额,而是能让你自己拿到结果最快的用法。 按这个节奏用,一个普通账号同步一天的日志通常在一分钟内跑完; 即使是每天几十万次调用的重度账号,一天也只需要一百次左右的请求。
我们保留未来对本接口引入调用频率限制的权利。目前没有对它设置频率限制,但请不要按「永远不限」来设计你的定时任务。 按上面这个节奏(每天一次、串行、pageSize 调大)用,即使将来加了限流也不会影响到你。

相关文档