Skip to content

查询授权 ​

为外部系统签发只读查询 Token,安全读取余额、日志、异步任务和运营数据

查询授权 ​

查询授权用于给外部系统签发只读查询 Token。它和模型调用 Token、个人资料访问令牌是三类不同凭证:

令牌类型主要用途常见路径
模型调用 Token调用模型能力/v1/*、/kling/*、/vidu/*
个人资料访问令牌查询当前登录用户的个人资料与余额/api/user/*
查询授权 Token面向外部系统只读查询账号、日志、任务和运营数据/api/query/v1/*

INFO

查询授权 Token 以 qak- 开头。调用查询接口时使用 Authorization: Bearer <查询授权 Token>。

创建 Token ​

在控制台进入「查询授权」,点击「创建 Token」:

  1. 填写 Token 名称。
  2. 选择可读用户范围(见下表)。
  3. 勾选需要开放的只读权限。
  4. 管理员可为日志、异步任务配置「不包含字段」;所有 Token 都可配置 IP 白名单。
  5. 设置有效期并创建。

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
}

分页 ​

参数类型说明
pageint页码,默认 1
sizeint每页条数,默认 30,最大 100
orderstring部分列表支持排序字段,见各接口说明

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/balanceaccount_balance账户余额与当日消费
GET/api/query/v1/balance_alertbalance_alert余额预警
GET/api/query/v1/model_tokensmodel_token模型调用令牌配置与掩码
GET/api/query/v1/logslog日志列表(完整字段)
GET/api/query/v1/logs/{id}log日志详情
POST/api/query/v1/logs/export_jobslog创建日志导出任务
GET/api/query/v1/taskstask异步任务列表(完整字段)
GET/api/query/v1/tasks/{id}task异步任务详情
POST/api/query/v1/tasks/export_jobstask创建异步任务导出任务
GET/api/query/v1/usersuser用户资料概要
GET/api/query/v1/customer_pricingcustomer_pricing客户价格配置
GET/api/query/v1/channelschannel渠道概要(仅全部用户)
GET/api/query/v1/channel_errorschannel_error渠道错误列表(仅全部用户)
GET/api/query/v1/channel_errors/{id}channel_error渠道错误详情
POST/api/query/v1/channel_errors/export_jobschannel_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_idint指定用户 / 全部用户必填目标用户 ID;当前用户范围忽略
currencystring否仅支持 CNY;返回同级 amounts 人民币金额对象

响应 data

字段类型说明
quotaint当前剩余额度(原始值)
used_quotaint累计已用额度(原始值)
balance_quotaint当前剩余余额,等于 quota
quota_unitstring固定 "quota"
displayobject金额展示对象;Query API 当前固定 enabled=false
today_used_quotaint北京时间当日已消费额度

GET /api/query/v1/balance_alert ​

仅 当前用户 范围可授权。

请求参数

参数类型必填说明
user_idint否当前用户范围固定本人

响应 data

未配置时可能返回空对象 {}。已配置时:

字段类型说明
idint规则 ID
user_idint用户 ID
target_typestring目标类型(账户级)
target_idint目标 ID
enabledbool是否启用
threshold_quotaint阈值额度
recipientsarray通知接收人
ever_enabledbool是否曾经启用
last_sent_daystring最近发送日
consecutive_daysint连续触发天数
created_atint创建时间(Unix 秒)
updated_atint更新时间(Unix 秒)

GET /api/query/v1/model_tokens ​

支持范围:当前用户、全部用户。

请求参数

参数类型必填说明
user_idint否全部用户范围可指定目标用户;当前用户固定本人
token_idint否模型调用令牌 ID 精确过滤
token_namestring否令牌名称精确过滤
groupstring否归属分组精确过滤
page / sizeint否分页
currencystring否仅支持 CNY;为 quota 字段返回同级 amounts

响应 data.data[]

字段类型说明
idint令牌 ID
user_idint所属用户
key_maskstring密钥掩码,不返回明文 key
statusint状态
name / token_namestring名称
created_timeint创建时间
accessed_timeint最近访问时间
expired_timeint过期时间,-1 表示不限制
remain_quotaint剩余额度字段
remaining_quotaint计算后的可用额度
unlimited_quotabool是否不限额
used_quotaint已用额度
monthly_quotaint月额度
current_month_usedint当月已用
temporary_quotaint临时额度
lifetime_usedint终身已用
usage_ratefloat使用率
group / packagestring分组
group_idint分组 ID
ip_whitelistarrayIP 白名单
model_permissionsarray允许的模型
rate_limit.rpm / rate_limit.tpmint速率限制
current_month_used_sourcestring仅不限额 Token:counter_or_consume_logs
current_month_used_sinceint仅不限额 Token:北京时间月初基线(Unix 秒)
balance_alert*object / 标量令牌余额预警摘要;始终返回,未配置时为 enabled=false、threshold=0 等零值

不返回完整 setting 与明文 key。不限额 Token 的 current_month_used 取月度计数器与当月成功消费日志聚合的较大值。

GET /api/query/v1/logs ​

列表直接返回完整字段(与详情字段合同一致)。

请求参数

参数类型说明
user_idint指定用户 / 全部用户可选;当前用户忽略;排除 user 字段后静默失效
time_preset / start_time+end_timestring时间范围,见上文
log_typeint日志类型
token_namestring模型调用令牌名称
model_namestring模型名
model_namesstring模型多选,重复参数或逗号分隔,任一命中
model_groupstring模型分组
request_idstring请求 ID
task_idstring关联任务 ID
usernamestring仅指定用户 / 全部用户;排除 user 字段后静默失效
channel_idint仅指定用户 / 全部用户;排除 channel 字段后静默失效
cost_levelint仅指定用户 / 全部用户,0–3;排除 cost_level 后静默失效
page / size / order—分页与排序
currencystring仅支持 CNY;为 quota 字段返回同级 amounts

响应 data.data[]

字段类型说明
idint日志 ID
created_atint创建时间
typeint日志类型
token_namestring模型调用令牌名称
model_namestring模型名
api_modelstringAPI 模型
billing_skustring计费 SKU
quotaint消费额度
prompt_tokensint输入 tokens
completion_tokensint输出 tokens
request_timeint请求耗时
is_streambool是否流式
outcome / error_code / error_type / customer_safe_message—终态失败相关字段(有则返回)
user_id / username—未排除用户字段时返回
channel_id / channel—指定用户 / 全部用户且未排除渠道时返回;当前用户默认不返回
cost_level_snapshotint / null指定用户 / 全部用户且未排除成本等级时返回;当前用户默认不返回
contentstring内容(已脱敏)
source_ipstring来源 IP
request_id / platform_request_id / upstream_request_idstring请求追踪 ID
platform_priceobject平台价摘要
customer_priceobject客户价摘要
billingobject计费明细白名单投影
upstream_usageobject上游 usage
remain_quotaint / null当时剩余额度

GET /api/query/v1/logs/{id} ​

路径参数 id 为日志数字 ID。响应 data 与列表单项相同,也支持可选参数 currency=CNY。超出 Token 用户范围时返回无权限。

GET /api/query/v1/tasks ​

列表同样返回完整字段(含快照投影)。

请求参数

参数类型说明
user_idint指定用户 / 全部用户可选;当前用户忽略
time_preset / start_time+end_timestring时间范围
task_idstring上游第三方任务 ID(部分平台任务可能为空)
platform_task_idstring公共任务 ID,须为 task_ / image_ / video_ 形式;带 image_ / video_ 前缀时按对应任务类型过滤
statusstring任务状态
task_kindstring任务类型
platformstring平台
actionstring动作
api_modelstring模型
error_categorystring错误分类
usernamestring仅指定用户 / 全部用户;排除用户字段后静默失效
channel_id / channel_namestring仅指定用户 / 全部用户;排除渠道后静默失效
cost_levelint仅指定用户 / 全部用户;排除成本等级后静默失效
page / size / order—分页与排序

响应 data.data[]

字段类型说明
idint数据库任务 ID
created_at / updated_atint时间
platform_task_idstring公共任务 ID(task_ / image_ / video_ 前缀)
task_idstring上游第三方任务 ID(部分平台任务可能为空)
external_task_idstring外部任务 ID
platformstring平台
task_kindstring任务类型
actionstring动作
statusstring状态
progressint进度
quotaint额度
submit_time / start_time / finish_timeint提交 / 开始 / 完成时间
api_model / billing_modelstring模型
brand_namestring品牌
user_id / username—未排除用户字段时返回
channel_id / channel_name—指定用户 / 全部用户且未排除渠道时返回;当前用户默认不返回
cost_level_snapshot—指定用户 / 全部用户且未排除成本等级时返回
fail_reasonstring失败原因(已脱敏)
user_requestobject业务请求快照(有持久化时返回;内部身份字段与密钥继续脱敏)
platform_createobject平台创建快照
platform_finalobject平台终态快照
result_urlsstring[]成功任务去重后的结果 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_idint精确过滤;范围外返回无权限
keywordstring用户名 / 展示名 / 企业名称 / 备注 / 分组 / 邮箱 / 联系方式包含匹配
page / sizeint分页

响应 data.data[]

字段类型说明
idint用户 ID
usernamestring用户名
display_namestring展示名
roleint角色
statusint状态
quotaint剩余额度
used_quotaint已用额度
request_countint请求数
groupstring分组
display_currencystring展示币种
company_namestring企业名称
remarkstring备注
created_timeint创建时间

不返回密码、access token、邀请码等敏感资料字段。

GET /api/query/v1/customer_pricing ​

支持范围:指定用户、全部用户。必须定位到唯一用户。

请求参数

参数类型说明
user_idint精确用户 ID
keywordstring用户 ID / 用户名 / 展示名解析唯一用户

规则:

  • user_id 与 keyword 至少提供其一;有 user_id 时优先精确 ID。
  • 无匹配:未找到匹配的用户
  • 多命中:关键词匹配到多个用户,请使用用户 ID 精确查询
  • 命中用户不在 Token 范围:无权限

响应 data

字段类型说明
userobject用户概要,字段同 users 列表项
configured_model_countint已配置模型数
modelsarray模型价格列表

models[]:

字段类型说明
model_id / modelstring模型标识
global_priceobject全局价,如 type / input / output;无全局价配置时为空对象 {}
customer_priceobject客户价;含 configured、groups、skus
groups / skusarray分组与 SKU 配置

GET /api/query/v1/channels ​

仅 全部用户。

请求参数

参数类型说明
idint渠道 ID
namestring渠道名称包含匹配
typeint模型厂商类型
statusint启停状态
modelsstring模型名多选,重复参数或逗号分隔,任一命中
page / sizeint分页

响应 data.data[]

字段类型说明
id / type / status / name—基础信息
weightint权重
created_time / test_time / response_timeint时间与响应时延
balance / balance_updated_time—渠道余额
modelsstring支持模型
tagstring标签
used_quotaint已用额度
priorityint优先级
auto_priority_enabled / auto_priority_degraded / auto_priority_degraded_at / auto_priority_degrade_reason—自动优先级与降级摘要
test_model / only_chat / pre_cost / cost_level—测试与成本配置
compatible_responsebool兼容响应
first_token_timeout_msint首 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_idint渠道 ID
user_idint用户 ID
usernamestring用户名 / 展示名包含匹配;为数字时同时按用户 ID 精确匹配
token_namestring模型调用令牌名称
model_namestring模型名
error_type / error_category / error_codestring错误分类
request_id / platform_request_idstring请求 ID
request_pathstring请求路径
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_idstring请求 ID
error_source / error_type / error_category / error_codestring错误分类
customer_exposure_policy / customer_safe_message—客户侧暴露策略与安全提示
leakage_risk / transport_error_typestring风险与传输错误类型
model_name / request_pathstring模型与路径
request_time / is_stream / first_response_ms—时延与流式标记
pending_reviewbool待复核

GET /api/query/v1/channel_errors/{id} ​

在列表字段基础上额外返回:

字段类型说明
error_msgstring错误消息(已脱敏)
upstream_request_idstring上游请求 ID
request_host / request_domainstring请求域名
upstream_provider_keystring上游供应商键
upstream_error_fingerprintstring上游错误指纹
classification_reasonstring分类原因
request_body / response_bodystring请求 / 响应正文(已脱敏)
upstream_response_body / platform_response_bodystring上游 / 平台响应正文
upstream_request_headers / upstream_request_bodystring上游请求头与请求体

字段排除(不包含字段) ​

控制台上仅管理员在创建 / 编辑 指定用户 或 全部用户 Token 时,可对 log、task 配置「不包含字段」。控制台默认「未排除」。

排除值效果
user列表、详情、导出不返回 user_id、username
channel列表、详情、导出不返回渠道 ID、渠道名称或渠道对象
cost_level列表、详情、导出不返回成本等级字段

额外规则:

  • 当前用户 Token 即使未配置排除,也默认不返回渠道与成本等级。
  • 排除后,对应筛选条件会静默失效,避免侧信道。
  • 任务的 user_request 是业务请求快照,不属于用户身份字段;排除 user 时仍可返回该快照,但快照内的 user_id、username 等身份字段会继续移除,密钥继续脱敏。

导出任务 ​

创建导出 ​

方法路径权限
POST/api/query/v1/logs/export_jobslog
POST/api/query/v1/tasks/export_jobstask
POST/api/query/v1/channel_errors/export_jobschannel_error(仅全部用户)

创建时的查询参数与对应列表接口相同(时间范围、过滤条件、user_id 等)。

响应 data

字段类型说明
idstring导出任务 ID
resourcestring资源:log / task / channel_error
statusstringpending / running / succeeded / failed / canceled
file_namestring文件名
row_countint导出行数
error_msgstring失败原因
created_atint创建时间
finished_atint完成时间
expires_atint过期时间

轮询、下载、取消 ​

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 解析失败

Fhddos AI 用户文档