> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xuwuai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询授权

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

# 查询授权

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

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

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

## 创建 Token

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

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

<Warning>
  完整密钥只在创建、复制或轮换时返回。请立即交付给调用方，并保存在服务端密钥管理系统中。
</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 theme={null}
export BASE_URL="https://xuwuai.com"
export QUERY_TOKEN="qak-xxxxxxxxxxxxxxxx"

curl "$BASE_URL/api/query/v1/balance" \
  -H "Authorization: Bearer $QUERY_TOKEN"
```

### 统一响应 envelope

成功：

```json theme={null}
{
  "success": true,
  "message": "",
  "data": {}
}
```

失败：

```json theme={null}
{
  "success": false,
  "message": "当前 Token 未授权该权限点"
}
```

说明：

* 鉴权失败（Token 缺失、无效、禁用、过期、IP 不匹配）通常返回 HTTP `401` / `403`，body 仍使用上述 envelope。
* 权限不足、参数错误、范围拒绝等业务失败通常返回 HTTP `200`，`success=false`。
* 列表类接口的 `data` 形如：

```json theme={null}
{
  "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 theme={null}
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_<ULID>` / `image_<ULID>` / `video_<ULID>` 形式；带 `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_<ULID>`、`image_<ULID>`、`video_<ULID>`

仍受 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 theme={null}
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` 解析失败 |