Appearance
查询授权
为外部系统签发只读查询 Token,安全读取余额、日志、异步任务和运营数据
查询授权
查询授权用于给外部系统签发只读查询 Token。它和模型调用 Token、个人资料访问令牌是三类不同凭证:
| 令牌类型 | 主要用途 | 常见路径 |
|---|---|---|
| 模型调用 Token | 调用模型能力 | /v1/*、/kling/*、/vidu/* |
| 个人资料访问令牌 | 查询当前登录用户的个人资料与余额 | /api/user/* |
| 查询授权 Token | 面向外部系统只读查询账号、日志、任务和运营数据 | /api/query/v1/* |
INFO
查询授权 Token 以 qak- 开头。调用查询接口时使用 Authorization: Bearer <查询授权 Token>。
创建 Token
在控制台进入「查询授权」,点击「创建 Token」:
- 填写 Token 名称。
- 选择可读用户范围(见下表)。
- 勾选需要开放的只读权限。
- 管理员可为日志、异步任务配置「不包含字段」;所有 Token 都可配置 IP 白名单。
- 设置有效期并创建。
WARNING
完整密钥只在创建、复制或轮换时返回。请立即交付给调用方,并保存在服务端密钥管理系统中。
可读用户范围
控制台与 scope_type 一一对应,请按下列三种范围理解数据可见边界:
| 控制台名称 | scope_type | 可读数据范围 | 适用场景 |
|---|---|---|---|
| 当前用户 | user | 仅签发者自己的数据 | 普通用户自助接入 |
| 指定用户 | admin_selected | 仅 allowed_user_ids 中的用户 | 客户成功、代理商或内部系统开放部分客户数据 |
| 全部用户 | admin_all | 平台范围内全部用户 | 管理员运营分析、内部对账、渠道治理 |
规则补充:
- 控制台上 当前用户 Token 仅普通用户侧可创建;请求中的
user_id会被忽略,始终读签发者自己。 - 指定用户 Token 仅管理员可创建,且必须至少选择一个可读用户;范围外
user_id返回无权限,不返回任何范围外数据。 - 签发者账号被禁用后,其签发的 Token 一律不可用;全部用户 / 指定用户 的管理员 Token 在签发者不再具备管理员角色时同样不可用。
channel、channel_error仅 全部用户 范围可授权。
权限点
| 权限 ID | 说明 | 当前用户 | 指定用户 | 全部用户 |
|---|---|---|---|---|
account_balance | 账户余额 | 支持 | 支持 | 支持 |
balance_alert | 余额预警 | 支持 | 不支持 | 不支持 |
model_token | 模型调用令牌配置与掩码 | 支持 | 不支持 | 支持 |
log | 调用日志 | 支持 | 支持 | 支持 |
task | 异步任务 | 支持 | 支持 | 支持 |
user | 用户资料概要 | 不支持 | 支持 | 支持 |
customer_pricing | 客户价格配置 | 不支持 | 支持 | 支持 |
channel | 渠道概要 | 不支持 | 不支持 | 支持 |
channel_error | 渠道错误 | 不支持 | 不支持 | 支持 |
当前版本只有资源级「读」权限。勾选 log、task 或 channel_error 的「读」后,即可读取该资源的列表、详情,以及创建和下载导出任务;不存在额外的详情或导出授权层。
调用约定
认证
bash
export BASE_URL="https://aiapi.fhddos.com"
export QUERY_TOKEN="qak-xxxxxxxxxxxxxxxx"
curl "$BASE_URL/api/query/v1/balance" \
-H "Authorization: Bearer $QUERY_TOKEN"统一响应 envelope
成功:
json
{
"success": true,
"message": "",
"data": {}
}失败:
json
{
"success": false,
"message": "当前 Token 未授权该权限点"
}说明:
- 鉴权失败(Token 缺失、无效、禁用、过期、IP 不匹配)通常返回 HTTP
401/403,body 仍使用上述 envelope。 - 权限不足、参数错误、范围拒绝等业务失败通常返回 HTTP
200,success=false。 - 列表类接口的
data形如:
json
{
"data": [],
"page": 1,
"size": 20,
"total_count": 100
}分页
| 参数 | 类型 | 说明 |
|---|---|---|
page | int | 页码,默认 1 |
size | int | 每页条数,默认 30,最大 100 |
order | string | 部分列表支持排序字段,见各接口说明 |
user_id 规则
| 接口 | 当前用户 | 指定用户 / 全部用户 |
|---|---|---|
balance | 忽略 user_id,固定本人 | 必须传 user_id |
balance_alert | 固定本人(该权限仅当前用户可授权) | — |
customer_pricing | 不支持该权限 | 必须传 user_id,或用 keyword 解析到唯一用户 |
logs、tasks、model_tokens | 固定本人 | 可选;不传则按 Token 可读范围返回 |
users | 不支持该权限 | 可选;不传则按 Token 可读范围返回 |
channels、channel_errors | 不支持 | 仅全部用户;不按 user_id 做主查询条件(渠道错误可另用筛选参数) |
指定用户 / 全部用户示例:
bash
curl "$BASE_URL/api/query/v1/balance?user_id=123" \
-H "Authorization: Bearer $QUERY_TOKEN"
curl "$BASE_URL/api/query/v1/logs?user_id=123&time_preset=24h&page=1&size=20" \
-H "Authorization: Bearer $QUERY_TOKEN"时间参数
日志、异步任务和渠道错误的列表 / 导出支持以下时间参数:
| 参数 | 说明 |
|---|---|
| (不传) | 默认最近 24 小时 |
time_preset=today | 北京时间当天 00:00:00–23:59:59 |
time_preset=1h | 最近 1 小时 |
time_preset=24h | 最近 24 小时 |
time_preset=7d | 最近 7 天 |
start_time + end_time | 自定义时间范围,必须成对传入 |
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 天。超限返回
查询时间跨度超过允许范围。
查询接口总览
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
GET | /api/query/v1/balance | account_balance | 账户余额与当日消费 |
GET | /api/query/v1/balance_alert | balance_alert | 余额预警 |
GET | /api/query/v1/model_tokens | model_token | 模型调用令牌配置与掩码 |
GET | /api/query/v1/logs | log | 日志列表(完整字段) |
GET | /api/query/v1/logs/{id} | log | 日志详情 |
POST | /api/query/v1/logs/export_jobs | log | 创建日志导出任务 |
GET | /api/query/v1/tasks | task | 异步任务列表(完整字段) |
GET | /api/query/v1/tasks/{id} | task | 异步任务详情 |
POST | /api/query/v1/tasks/export_jobs | task | 创建异步任务导出任务 |
GET | /api/query/v1/users | user | 用户资料概要 |
GET | /api/query/v1/customer_pricing | customer_pricing | 客户价格配置 |
GET | /api/query/v1/channels | channel | 渠道概要(仅全部用户) |
GET | /api/query/v1/channel_errors | channel_error | 渠道错误列表(仅全部用户) |
GET | /api/query/v1/channel_errors/{id} | channel_error | 渠道错误详情 |
POST | /api/query/v1/channel_errors/export_jobs | channel_error | 创建渠道错误导出任务 |
GET | /api/query/v1/export_jobs/{id} | 任务归属当前 Token | 查询导出任务状态 |
GET | /api/query/v1/export_jobs/{id}/download | 任务归属当前 Token,并重新校验对应资源读权限 | 下载导出结果 |
POST | /api/query/v1/export_jobs/{id}/cancel | 任务归属当前 Token | 取消未结束的导出任务 |
接口字段
以下字段均为 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
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
user_id | int | 指定用户 / 全部用户必填 | 目标用户 ID;当前用户范围忽略 |
currency | string | 否 | 仅支持 CNY;返回同级 amounts 人民币金额对象 |
响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
quota | int | 当前剩余额度(原始值) |
used_quota | int | 累计已用额度(原始值) |
balance_quota | int | 当前剩余余额,等于 quota |
quota_unit | string | 固定 "quota" |
display | object | 金额展示对象;Query API 当前固定 enabled=false |
today_used_quota | int | 北京时间当日已消费额度 |
GET /api/query/v1/balance_alert
仅 当前用户 范围可授权。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
user_id | int | 否 | 当前用户范围固定本人 |
响应 data
未配置时可能返回空对象 {}。已配置时:
| 字段 | 类型 | 说明 |
|---|---|---|
id | int | 规则 ID |
user_id | int | 用户 ID |
target_type | string | 目标类型(账户级) |
target_id | int | 目标 ID |
enabled | bool | 是否启用 |
threshold_quota | int | 阈值额度 |
recipients | array | 通知接收人 |
ever_enabled | bool | 是否曾经启用 |
last_sent_day | string | 最近发送日 |
consecutive_days | int | 连续触发天数 |
created_at | int | 创建时间(Unix 秒) |
updated_at | int | 更新时间(Unix 秒) |
GET /api/query/v1/model_tokens
支持范围:当前用户、全部用户。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
user_id | int | 否 | 全部用户范围可指定目标用户;当前用户固定本人 |
token_id | int | 否 | 模型调用令牌 ID 精确过滤 |
token_name | string | 否 | 令牌名称精确过滤 |
group | string | 否 | 归属分组精确过滤 |
page / size | int | 否 | 分页 |
currency | string | 否 | 仅支持 CNY;为 quota 字段返回同级 amounts |
响应 data.data[]
| 字段 | 类型 | 说明 |
|---|---|---|
id | int | 令牌 ID |
user_id | int | 所属用户 |
key_mask | string | 密钥掩码,不返回明文 key |
status | int | 状态 |
name / token_name | string | 名称 |
created_time | int | 创建时间 |
accessed_time | int | 最近访问时间 |
expired_time | int | 过期时间,-1 表示不限制 |
remain_quota | int | 剩余额度字段 |
remaining_quota | int | 计算后的可用额度 |
unlimited_quota | bool | 是否不限额 |
used_quota | int | 已用额度 |
monthly_quota | int | 月额度 |
current_month_used | int | 当月已用 |
temporary_quota | int | 临时额度 |
lifetime_used | int | 终身已用 |
usage_rate | float | 使用率 |
group / package | string | 分组 |
group_id | int | 分组 ID |
ip_whitelist | array | IP 白名单 |
model_permissions | array | 允许的模型 |
rate_limit.rpm / rate_limit.tpm | int | 速率限制 |
current_month_used_source | string | 仅不限额 Token:counter_or_consume_logs |
current_month_used_since | int | 仅不限额 Token:北京时间月初基线(Unix 秒) |
balance_alert* | object / 标量 | 令牌余额预警摘要;始终返回,未配置时为 enabled=false、threshold=0 等零值 |
不返回完整 setting 与明文 key。不限额 Token 的 current_month_used 取月度计数器与当月成功消费日志聚合的较大值。
GET /api/query/v1/logs
列表直接返回完整字段(与详情字段合同一致)。
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
user_id | int | 指定用户 / 全部用户可选;当前用户忽略;排除 user 字段后静默失效 |
time_preset / start_time+end_time | string | 时间范围,见上文 |
log_type | int | 日志类型 |
token_name | string | 模型调用令牌名称 |
model_name | string | 模型名 |
model_names | string | 模型多选,重复参数或逗号分隔,任一命中 |
model_group | string | 模型分组 |
request_id | string | 请求 ID |
task_id | string | 关联任务 ID |
username | string | 仅指定用户 / 全部用户;排除 user 字段后静默失效 |
channel_id | int | 仅指定用户 / 全部用户;排除 channel 字段后静默失效 |
cost_level | int | 仅指定用户 / 全部用户,0–3;排除 cost_level 后静默失效 |
page / size / order | — | 分页与排序 |
currency | string | 仅支持 CNY;为 quota 字段返回同级 amounts |
响应 data.data[]
| 字段 | 类型 | 说明 |
|---|---|---|
id | int | 日志 ID |
created_at | int | 创建时间 |
type | int | 日志类型 |
token_name | string | 模型调用令牌名称 |
model_name | string | 模型名 |
api_model | string | API 模型 |
billing_sku | string | 计费 SKU |
quota | int | 消费额度 |
prompt_tokens | int | 输入 tokens |
completion_tokens | int | 输出 tokens |
request_time | int | 请求耗时 |
is_stream | bool | 是否流式 |
outcome / error_code / error_type / customer_safe_message | — | 终态失败相关字段(有则返回) |
user_id / username | — | 未排除用户字段时返回 |
channel_id / channel | — | 指定用户 / 全部用户且未排除渠道时返回;当前用户默认不返回 |
cost_level_snapshot | int / null | 指定用户 / 全部用户且未排除成本等级时返回;当前用户默认不返回 |
content | string | 内容(已脱敏) |
source_ip | string | 来源 IP |
request_id / platform_request_id / upstream_request_id | string | 请求追踪 ID |
platform_price | object | 平台价摘要 |
customer_price | object | 客户价摘要 |
billing | object | 计费明细白名单投影 |
upstream_usage | object | 上游 usage |
remain_quota | int / null | 当时剩余额度 |
GET /api/query/v1/logs/{id}
路径参数 id 为日志数字 ID。响应 data 与列表单项相同,也支持可选参数 currency=CNY。超出 Token 用户范围时返回无权限。
GET /api/query/v1/tasks
列表同样返回完整字段(含快照投影)。
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
user_id | int | 指定用户 / 全部用户可选;当前用户忽略 |
time_preset / start_time+end_time | string | 时间范围 |
task_id | string | 上游第三方任务 ID(部分平台任务可能为空) |
platform_task_id | string | 公共任务 ID,须为 task_ / image_ / video_ 形式;带 image_ / video_ 前缀时按对应任务类型过滤 |
status | string | 任务状态 |
task_kind | string | 任务类型 |
platform | string | 平台 |
action | string | 动作 |
api_model | string | 模型 |
error_category | string | 错误分类 |
username | string | 仅指定用户 / 全部用户;排除用户字段后静默失效 |
channel_id / channel_name | string | 仅指定用户 / 全部用户;排除渠道后静默失效 |
cost_level | int | 仅指定用户 / 全部用户;排除成本等级后静默失效 |
page / size / order | — | 分页与排序 |
响应 data.data[]
| 字段 | 类型 | 说明 |
|---|---|---|
id | int | 数据库任务 ID |
created_at / updated_at | int | 时间 |
platform_task_id | string | 公共任务 ID(task_ / image_ / video_ 前缀) |
task_id | string | 上游第三方任务 ID(部分平台任务可能为空) |
external_task_id | string | 外部任务 ID |
platform | string | 平台 |
task_kind | string | 任务类型 |
action | string | 动作 |
status | string | 状态 |
progress | int | 进度 |
quota | int | 额度 |
submit_time / start_time / finish_time | int | 提交 / 开始 / 完成时间 |
api_model / billing_model | string | 模型 |
brand_name | string | 品牌 |
user_id / username | — | 未排除用户字段时返回 |
channel_id / channel_name | — | 指定用户 / 全部用户且未排除渠道时返回;当前用户默认不返回 |
cost_level_snapshot | — | 指定用户 / 全部用户且未排除成本等级时返回 |
fail_reason | string | 失败原因(已脱敏) |
user_request | object | 业务请求快照(有持久化时返回;内部身份字段与密钥继续脱敏) |
platform_create | object | 平台创建快照 |
platform_final | object | 平台终态快照 |
result_urls | string[] | 成功任务去重后的结果 URL(可用时返回) |
不会返回原始 properties、data、upstream_raw。旧任务若无历史快照,可能省略 user_request / platform_create / platform_final。
GET /api/query/v1/tasks/{id}
路径 id 兼容:
- 数据库数字 ID
- 公共任务 ID:
task_、image_、video_
仍受 Token 用户范围约束。响应 data 与列表单项相同。
GET /api/query/v1/users
支持范围:指定用户、全部用户。
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
user_id | int | 精确过滤;范围外返回无权限 |
keyword | string | 用户名 / 展示名 / 企业名称 / 备注 / 分组 / 邮箱 / 联系方式包含匹配 |
page / size | int | 分页 |
响应 data.data[]
| 字段 | 类型 | 说明 |
|---|---|---|
id | int | 用户 ID |
username | string | 用户名 |
display_name | string | 展示名 |
role | int | 角色 |
status | int | 状态 |
quota | int | 剩余额度 |
used_quota | int | 已用额度 |
request_count | int | 请求数 |
group | string | 分组 |
display_currency | string | 展示币种 |
company_name | string | 企业名称 |
remark | string | 备注 |
created_time | int | 创建时间 |
不返回密码、access token、邀请码等敏感资料字段。
GET /api/query/v1/customer_pricing
支持范围:指定用户、全部用户。必须定位到唯一用户。
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
user_id | int | 精确用户 ID |
keyword | string | 用户 ID / 用户名 / 展示名解析唯一用户 |
规则:
user_id与keyword至少提供其一;有user_id时优先精确 ID。- 无匹配:
未找到匹配的用户 - 多命中:
关键词匹配到多个用户,请使用用户 ID 精确查询 - 命中用户不在 Token 范围:无权限
响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
user | object | 用户概要,字段同 users 列表项 |
configured_model_count | int | 已配置模型数 |
models | array | 模型价格列表 |
models[]:
| 字段 | 类型 | 说明 |
|---|---|---|
model_id / model | string | 模型标识 |
global_price | object | 全局价,如 type / input / output;无全局价配置时为空对象 {} |
customer_price | object | 客户价;含 configured、groups、skus |
groups / skus | array | 分组与 SKU 配置 |
GET /api/query/v1/channels
仅 全部用户。
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
id | int | 渠道 ID |
name | string | 渠道名称包含匹配 |
type | int | 模型厂商类型 |
status | int | 启停状态 |
models | string | 模型名多选,重复参数或逗号分隔,任一命中 |
page / size | int | 分页 |
响应 data.data[]
| 字段 | 类型 | 说明 |
|---|---|---|
id / type / status / name | — | 基础信息 |
weight | int | 权重 |
created_time / test_time / response_time | int | 时间与响应时延 |
balance / balance_updated_time | — | 渠道余额 |
models | string | 支持模型 |
tag | string | 标签 |
used_quota | int | 已用额度 |
priority | int | 优先级 |
auto_priority_enabled / auto_priority_degraded / auto_priority_degraded_at / auto_priority_degrade_reason | — | 自动优先级与降级摘要 |
test_model / only_chat / pre_cost / cost_level | — | 测试与成本配置 |
compatible_response | bool | 兼容响应 |
first_token_timeout_ms | int | 首 token 超时 |
retry_enabled / retry_max_attempts / retry_interval_ms | — | 重试配置 |
failover_enabled / failover_max_channels / failover_timeout_ms / failover_cooldown_seconds | — | 故障转移配置 |
不返回渠道密钥、上游地址、代理、内部扩展配置、模型映射和内部备注。
GET /api/query/v1/channel_errors
仅 全部用户。
请求参数(常用)
| 参数 | 类型 | 说明 |
|---|---|---|
| 时间参数 | — | 见时间参数章节,最大 30 天 |
channel_id | int | 渠道 ID |
user_id | int | 用户 ID |
username | string | 用户名 / 展示名包含匹配;为数字时同时按用户 ID 精确匹配 |
token_name | string | 模型调用令牌名称 |
model_name | string | 模型名 |
error_type / error_category / error_code | string | 错误分类 |
request_id / platform_request_id | string | 请求 ID |
request_path | string | 请求路径 |
page / size / order | — | 分页与排序 |
另支持 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[](列表摘要)
| 字段 | 类型 | 说明 |
|---|---|---|
id / created_at | — | 错误 ID 与时间 |
channel_id / channel_name | — | 渠道 |
user_id / token_id / token_name | — | 用户与令牌引用 |
request_id / platform_request_id | string | 请求 ID |
error_source / error_type / error_category / error_code | string | 错误分类 |
customer_exposure_policy / customer_safe_message | — | 客户侧暴露策略与安全提示 |
leakage_risk / transport_error_type | string | 风险与传输错误类型 |
model_name / request_path | string | 模型与路径 |
request_time / is_stream / first_response_ms | — | 时延与流式标记 |
pending_review | bool | 待复核 |
GET /api/query/v1/channel_errors/{id}
在列表字段基础上额外返回:
| 字段 | 类型 | 说明 |
|---|---|---|
error_msg | string | 错误消息(已脱敏) |
upstream_request_id | string | 上游请求 ID |
request_host / request_domain | string | 请求域名 |
upstream_provider_key | string | 上游供应商键 |
upstream_error_fingerprint | string | 上游错误指纹 |
classification_reason | string | 分类原因 |
request_body / response_body | string | 请求 / 响应正文(已脱敏) |
upstream_response_body / platform_response_body | string | 上游 / 平台响应正文 |
upstream_request_headers / upstream_request_body | string | 上游请求头与请求体 |
字段排除(不包含字段)
控制台上仅管理员在创建 / 编辑 指定用户 或 全部用户 Token 时,可对 log、task 配置「不包含字段」。控制台默认「未排除」。
| 排除值 | 效果 |
|---|---|
user | 列表、详情、导出不返回 user_id、username |
channel | 列表、详情、导出不返回渠道 ID、渠道名称或渠道对象 |
cost_level | 列表、详情、导出不返回成本等级字段 |
额外规则:
- 当前用户 Token 即使未配置排除,也默认不返回渠道与成本等级。
- 排除后,对应筛选条件会静默失效,避免侧信道。
- 任务的
user_request是业务请求快照,不属于用户身份字段;排除user时仍可返回该快照,但快照内的user_id、username等身份字段会继续移除,密钥继续脱敏。
导出任务
创建导出
| 方法 | 路径 | 权限 |
|---|---|---|
POST | /api/query/v1/logs/export_jobs | log |
POST | /api/query/v1/tasks/export_jobs | task |
POST | /api/query/v1/channel_errors/export_jobs | channel_error(仅全部用户) |
创建时的查询参数与对应列表接口相同(时间范围、过滤条件、user_id 等)。
响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 导出任务 ID |
resource | string | 资源:log / task / channel_error |
status | string | pending / running / succeeded / failed / canceled |
file_name | string | 文件名 |
row_count | int | 导出行数 |
error_msg | string | 失败原因 |
created_at | int | 创建时间 |
finished_at | int | 完成时间 |
expires_at | int | 过期时间 |
轮询、下载、取消
bash
curl "$BASE_URL/api/query/v1/export_jobs/{job_id}" \
-H "Authorization: Bearer $QUERY_TOKEN"
curl "$BASE_URL/api/query/v1/export_jobs/{job_id}/download" \
-H "Authorization: Bearer $QUERY_TOKEN" \
-o query-export.csv
curl -X POST "$BASE_URL/api/query/v1/export_jobs/{job_id}/cancel" \
-H "Authorization: Bearer $QUERY_TOKEN"规则:
- 导出按 ID 游标稳定扫描;单个任务最多 10,000 行、CSV 最多 16 MiB,超限失败并提示缩小范围。
- 下载时会重新检查当前资源读权限、用户范围和字段排除;任一授权收窄后不能下载旧产物。
- 取消运行中任务后,扫描会在下一个检查点(每 25 行或分页边界)停止。
- 任务过期后,数据库中的 CSV 内容会清空。
download成功时直接返回 CSV 文件流,不是 JSON envelope。
导出列使用独立 CSV 合同:日志导出会包含 source_ip、remain_quota、请求 ID、价格与计费等结构化字段(JSON 单元格);任务导出在基础列上增加 fail_reason。user_request / platform_create / platform_final / result_urls 属于列表与详情接口,不进入任务导出 CSV。
常见错误
message | 含义 |
|---|---|
Token 无效 | Token 缺失、格式错误或密钥不匹配 |
查询 API Token 不存在 | Token 已删除或不存在 |
Token 已禁用 | Token 已被关闭;或签发者账号被禁用、管理员签发者失去管理员角色 |
Token 已过期 | Token 超过有效期 |
当前来源 IP 不允许访问 | 请求来源不在 IP 白名单 |
当前 Token 未授权该权限点 | 未勾选对应资源的「读」,或范围不允许该权限 |
当前 Token 不允许访问该用户数据 | user_id / 资源不在 Token 可读范围 |
user_id 不能为空 | 余额等需要明确目标用户的接口未传 user_id |
时间范围参数不能同时使用两种传法 | 时间参数互斥冲突 |
查询时间跨度超过允许范围 | 超过 31 天(日志/任务)或 30 天(渠道错误) |
未找到匹配的用户 / 关键词匹配到多个用户,请使用用户 ID 精确查询 | customer_pricing 的 keyword 解析失败 |