查询授权
查询授权用于给外部系统签发只读查询 Token。它和模型调用 Token、个人资料访问令牌是三类不同凭证：查询授权 Token 以
qak- 开头。调用查询接口时使用 Authorization: Bearer <查询授权 Token>。创建 Token
在控制台进入「查询授权」，点击「创建 Token」：- 填写 Token 名称。
- 选择可读用户范围（见下表）。
- 勾选需要开放的只读权限。
- 管理员可为日志、异步任务配置「不包含字段」；所有 Token 都可配置 IP 白名单。
- 设置有效期并创建。
可读用户范围
控制台与scope_type 一一对应，请按下列三种范围理解数据可见边界：
规则补充：
- 控制台上 当前用户 Token 仅普通用户侧可创建；请求中的
user_id会被忽略，始终读签发者自己。 - 指定用户 Token 仅管理员可创建，且必须至少选择一个可读用户；范围外
user_id返回无权限，不返回任何范围外数据。 - 签发者账号被禁用后，其签发的 Token 一律不可用；全部用户 / 指定用户 的管理员 Token 在签发者不再具备管理员角色时同样不可用。
channel、channel_error仅 全部用户 范围可授权。
权限点
当前版本只有资源级「读」权限。勾选
log、task 或 channel_error 的「读」后，即可读取该资源的列表、详情，以及创建和下载导出任务；不存在额外的详情或导出授权层。
调用约定
认证
统一响应 envelope
成功：- 鉴权失败（Token 缺失、无效、禁用、过期、IP 不匹配）通常返回 HTTP
401/403，body 仍使用上述 envelope。 - 权限不足、参数错误、范围拒绝等业务失败通常返回 HTTP
200，success=false。 - 列表类接口的
data形如：
分页
user_id 规则
指定用户 / 全部用户示例：
时间参数
日志、异步任务和渠道错误的列表 / 导出支持以下时间参数：start_time / end_time 支持：
YYYY-MM-DD（按北京时间补齐当天开始 / 结束）YYYY-MM-DD HH:mm:ss、YYYY-MM-DDTHH:mm:ss- RFC3339
- Unix 秒
- 兼容旧参数：
start_timestamp/end_timestamp（Unix 秒，成对）、range=24h|last_24h|7d|last_7d|month|current_month。新接入请优先使用time_preset或start_time/end_time。 - 四种传法（
time_preset、start_time/end_time、start_timestamp/end_timestamp、range）两两互斥，混用返回时间范围参数不能同时使用两种传法。 - 日志、异步任务最大跨度 31 天；渠道错误最大跨度 30 天。超限返回
查询时间跨度超过允许范围。
查询接口总览
接口字段
以下字段均为 Query API 白名单投影，不直接透传数据库对象。敏感字段会脱敏；密钥、Cookie、私钥、渠道凭证和模型调用令牌明文不会原样返回。balance、model_tokens、logs 和 logs/{id} 支持可选参数 currency=CNY。不传时响应与原合同完全一致；传入后保留全部原始 quota 字段，并在同级新增 amounts：
- 换算公式：
quota / 当前 QuotaPerUnit × 7，结果为 JSON number，四舍五入到 6 位小数。 amounts.currency固定为CNY，amounts.quota_per_unit为本次请求读取的配置快照，amounts.usd_cny_rate固定为7。amounts中以相同字段名返回对应人民币金额。日志的remain_quota原值为空时金额也为空；不限额 Token 的剩余和额度上限金额为null，实际用量金额正常换算。- 其他币种会明确报错；请求人民币金额时若
QuotaPerUnit <= 0，请求失败而不会返回伪造金额。
GET /api/query/v1/balance
请求参数
响应
data
GET /api/query/v1/balance_alert
仅 当前用户 范围可授权。
请求参数
响应
data
未配置时可能返回空对象 {}。已配置时：
GET /api/query/v1/model_tokens
支持范围：当前用户、全部用户。
请求参数
响应
data.data[]
不返回完整
setting 与明文 key。不限额 Token 的 current_month_used 取月度计数器与当月成功消费日志聚合的较大值。
GET /api/query/v1/logs
列表直接返回完整字段（与详情字段合同一致）。
请求参数
响应
data.data[]
GET /api/query/v1/logs/{id}
路径参数 id 为日志数字 ID。响应 data 与列表单项相同，也支持可选参数 currency=CNY。超出 Token 用户范围时返回无权限。
GET /api/query/v1/tasks
列表同样返回完整字段（含快照投影）。
请求参数
响应
data.data[]
不会返回原始
properties、data、upstream_raw。旧任务若无历史快照，可能省略 user_request / platform_create / platform_final。
GET /api/query/v1/tasks/{id}
路径 id 兼容：
- 数据库数字 ID
- 公共任务 ID：
task_<ULID>、image_<ULID>、video_<ULID>
data 与列表单项相同。
GET /api/query/v1/users
支持范围：指定用户、全部用户。
请求参数
响应
data.data[]
不返回密码、access token、邀请码等敏感资料字段。
GET /api/query/v1/customer_pricing
支持范围：指定用户、全部用户。必须定位到唯一用户。
请求参数
规则：
user_id与keyword至少提供其一；有user_id时优先精确 ID。- 无匹配：
未找到匹配的用户 - 多命中：
关键词匹配到多个用户，请使用用户 ID 精确查询 - 命中用户不在 Token 范围：无权限
data
models[]：
GET /api/query/v1/channels
仅 全部用户。
请求参数
响应
data.data[]
不返回渠道密钥、上游地址、代理、内部扩展配置、模型映射和内部备注。
GET /api/query/v1/channel_errors
仅 全部用户。
请求参数（常用）
另支持
token_id、error_source、customer_exposure_policy、leakage_risk、transport_error_type、pending_review、real_traffic_only、operational_upstream_only、exclude_compliance_errors、upstream_request_id、upstream_provider_key、upstream_error_fingerprint 等筛选参数。
响应 data.data[]（列表摘要）
GET /api/query/v1/channel_errors/{id}
在列表字段基础上额外返回：
字段排除（不包含字段）
控制台上仅管理员在创建 / 编辑 指定用户 或 全部用户 Token 时，可对log、task 配置「不包含字段」。控制台默认「未排除」。
额外规则：
- 当前用户 Token 即使未配置排除，也默认不返回渠道与成本等级。
- 排除后，对应筛选条件会静默失效，避免侧信道。
- 任务的
user_request是业务请求快照，不属于用户身份字段；排除user时仍可返回该快照，但快照内的user_id、username等身份字段会继续移除，密钥继续脱敏。
导出任务
创建导出
创建时的查询参数与对应列表接口相同（时间范围、过滤条件、
user_id 等）。
响应 data
轮询、下载、取消
- 导出按 ID 游标稳定扫描；单个任务最多 10,000 行、CSV 最多 16 MiB，超限失败并提示缩小范围。
- 下载时会重新检查当前资源读权限、用户范围和字段排除；任一授权收窄后不能下载旧产物。
- 取消运行中任务后，扫描会在下一个检查点（每 25 行或分页边界）停止。
- 任务过期后，数据库中的 CSV 内容会清空。
download成功时直接返回 CSV 文件流，不是 JSON envelope。
source_ip、remain_quota、请求 ID、价格与计费等结构化字段（JSON 单元格）；任务导出在基础列上增加 fail_reason。user_request / platform_create / platform_final / result_urls 属于列表与详情接口，不进入任务导出 CSV。