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

# 额度使用情况查询

> 查询当前 API Key 对应账号的剩余积分，以及各项 API 权限在当前周期内的额度使用情况。

查询当前 `AIBase-API-Key` 对应账号的剩余积分（`points`）与各项 API 权限的额度使用情况（`permissions`），用于在批量调用前确认配额、或在自动化流程中做额度水位监控。

<Info>
  **执行模式：SYNC · 同步，且不走统一任务入口。**
  本接口是独立的 `GET` 端点：不使用 `POST /v1/openapi/tasks`，也**不需要传 `apiCode`**，服务端在当前 HTTP 响应中直接返回结果，无需轮询任务状态。
</Info>

## 接口速查

| 项目             | 当前接口约定                                         |
| -------------- | ---------------------------------------------- |
| 接口状态           | 已上线                                            |
| 请求方式           | `GET`                                          |
| 请求地址           | `https://api.aibase.cn/v1/openapi/quota/usage` |
| 业务标识           | 无（不使用 `apiCode`）                               |
| 执行模式           | **SYNC · 同步**（直接返回结果）                          |
| 身份认证           | Header `AIBase-API-Key`                        |
| 请求体 / Query 参数 | 无                                              |
| 调用限制           | 以账号权限和控制台显示为准                                  |

<Check>
  调用前需要完成两项准备：创建 API Key、仅在服务端读取密钥。
</Check>

## 请求头

<ParamField header="AIBase-API-Key" type="string" required>
  AIBase 开放平台 API Key，例如 `AIBase_xxx`。请仅在服务端保存和使用。
</ParamField>

<ParamField header="AIBase-Request-Id" type="string">
  可选的客户端请求标识。建议为每次调用生成唯一值，方便排查链路问题。
</ParamField>

## 请求参数

本接口为 `GET` 请求，**无请求体，也无需传递任何 Query 参数**。账号身份完全由请求头 `AIBase-API-Key` 决定，因此不同 API Key 查询到的是各自账号的额度数据。

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.aibase.cn/v1/openapi/quota/usage \
    --header "AIBase-API-Key: ${AIBASE_API_KEY}"
  ```

  ```python Python theme={null}
  import os
  import requests

  api_key = os.environ["AIBASE_API_KEY"]
  response = requests.get(
      "https://api.aibase.cn/v1/openapi/quota/usage",
      headers={"AIBase-API-Key": api_key},
      timeout=30,
  )

  response.raise_for_status()
  payload = response.json()
  if payload.get("code") != 200:
      raise RuntimeError(f"AIBase API error: {payload}")

  data = payload["data"]
  print("剩余积分:", data["points"])
  for item in data["permissions"]:
      # totalLimit / usedCount / remainingCount 均可能为 None
      print(item["permissionName"], item["usedCount"], "/", item["totalLimit"])
  ```

  ```javascript Node.js theme={null}
  const apiKey = process.env.AIBASE_API_KEY;
  if (!apiKey) throw new Error("请先设置 AIBASE_API_KEY");

  const response = await fetch("https://api.aibase.cn/v1/openapi/quota/usage", {
    headers: {
      "AIBase-API-Key": apiKey,
    },
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const payload = await response.json();
  if (payload.code !== 200) throw new Error(`AIBase API error: ${JSON.stringify(payload)}`);

  console.log("剩余积分:", payload.data.points);
  for (const item of payload.data.permissions ?? []) {
    // totalLimit / usedCount / remainingCount 均可能为 null
    console.log(item.permissionName, item.usedCount, "/", item.totalLimit);
  }
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.aibase.cn/v1/openapi/quota/usage"))
      .header("AIBase-API-Key", System.getenv("AIBASE_API_KEY"))
      .GET()
      .build();

  HttpResponse<String> response = HttpClient.newHttpClient()
      .send(request, HttpResponse.BodyHandlers.ofString());
  ```
</RequestExample>

## 成功响应

<ResponseField name="code" type="integer" required>
  业务状态码。`200` 表示查询成功。
</ResponseField>

<ResponseField name="msg" type="string" required>
  响应说明，如 `成功`。
</ResponseField>

<ResponseField name="data" type="object" required>
  额度业务数据。注意：本接口的 `data` **直接就是额度对象**，不存在 `data.result` 层级。
</ResponseField>

<ResponseField name="data.points" type="integer" required>
  当前账号剩余积分。
</ResponseField>

<ResponseField name="data.permissions" type="object[]" required>
  当前账号可用的权限及额度使用情况列表。无权限时可能为空数组。
</ResponseField>

<ResponseField name="data.permissions[].permissionCode" type="string" required>
  权限或 API 能力的唯一编码，例如 `GEO_AI_QUESTIONS`。
</ResponseField>

<ResponseField name="data.permissions[].permissionName" type="string" required>
  权限或 API 能力名称，例如 `AI对话问题挖掘`。
</ResponseField>

<ResponseField name="data.permissions[].aiPlatforms" type="string[] | null" required>
  该权限支持或关联的大模型平台编码列表；不适用时为 `null`。
</ResponseField>

<ResponseField name="data.permissions[].totalLimit" type="integer | null" required>
  当前周期内总可用次数；无限制或不适用时为 `null`。
</ResponseField>

<ResponseField name="data.permissions[].usedCount" type="integer | null" required>
  当前周期已使用次数；不适用时为 `null`。
</ResponseField>

<ResponseField name="data.permissions[].remainingCount" type="integer | null" required>
  当前周期剩余可用次数；不适用时为 `null`。
</ResponseField>

<ResponseField name="timeStamp" type="integer" required>
  服务端响应时间戳，单位为毫秒。
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "msg": "成功",
    "data": {
      "permissions": [
        {
          "aiPlatforms": null,
          "totalLimit": 800,
          "permissionCode": "GEO_AI_QUESTIONS",
          "usedCount": 15,
          "remainingCount": 785,
          "permissionName": "AI对话问题挖掘"
        },
        {
          "aiPlatforms": [
            "aliyun",
            "baidu",
            "deepseek",
            "google",
            "gpt",
            "kimi",
            "perplexity",
            "quark",
            "tencent",
            "volcengine"
          ],
          "totalLimit": 600,
          "permissionCode": "GEO_RANK_QUERY",
          "usedCount": 6,
          "remainingCount": 594,
          "permissionName": "GEO排名查询"
        },
        {
          "aiPlatforms": [
            "aliyun",
            "baidu",
            "deepseek",
            "google",
            "gpt",
            "kimi",
            "perplexity",
            "quark",
            "tencent",
            "volcengine"
          ],
          "totalLimit": 30,
          "permissionCode": "GEO_BRAND_MONITOR",
          "usedCount": 5,
          "remainingCount": 25,
          "permissionName": "GEO 品牌得分检测"
        },
        {
          "aiPlatforms": [
            "aliyun",
            "baidu",
            "deepseek",
            "google",
            "gpt",
            "kimi",
            "perplexity",
            "quark",
            "tencent",
            "volcengine"
          ],
          "totalLimit": 60,
          "permissionCode": "GEO_URL_MENTION",
          "usedCount": 16,
          "remainingCount": 44,
          "permissionName": "GEO 推广链接检测"
        },
        {
          "aiPlatforms": [
            "aliyun",
            "baidu",
            "deepseek",
            "google",
            "gpt",
            "kimi",
            "perplexity",
            "quark",
            "tencent",
            "volcengine"
          ],
          "totalLimit": null,
          "permissionCode": "GEO_RANK_MONITOR",
          "usedCount": null,
          "remainingCount": null,
          "permissionName": "GEO 排名监测"
        },
        {
          "aiPlatforms": null,
          "totalLimit": null,
          "permissionCode": "GEO_RANK_MONITOR_EXPORT_DATA",
          "usedCount": null,
          "remainingCount": null,
          "permissionName": "导出数据"
        },
        {
          "aiPlatforms": null,
          "totalLimit": null,
          "permissionCode": "GEO_RANK_MONITOR_REPORT_GENERATION",
          "usedCount": null,
          "remainingCount": null,
          "permissionName": "生成报告"
        },
        {
          "aiPlatforms": null,
          "totalLimit": 1,
          "permissionCode": "PROMPTION_NEWS",
          "usedCount": 0,
          "remainingCount": 1,
          "permissionName": "7天AI产品栏目推荐席位"
        },
        {
          "aiPlatforms": null,
          "totalLimit": null,
          "permissionCode": "DEDICATED_CUSTOMER_SERVICE",
          "usedCount": null,
          "remainingCount": null,
          "permissionName": "专属客服"
        }
      ],
      "points": 94220
    },
    "timeStamp": 1789864739249
  }
  ```

  ```json 401（鉴权失败 · 结构示例，msg 文案以实际返回为准） theme={null}
  {
    "code": 401,
    "msg": "鉴权失败",
    "data": null,
    "timeStamp": 1789864739249
  }
  ```
</ResponseExample>

<Warning>
  官方文档未给出本接口的错误响应样例。上例仅用于说明失败时的结构：`code` 非 `200`、`data` 为 `null`；具体 `code`、`msg` 文案以实际返回为准，客户端应统一按「非 200 即失败」处理，不要依赖固定文案做分支判断。
</Warning>

## 权限编码对照（参考）

下表由权限名称与已开放业务接口整理得出，**官方接口文档未声明该映射关系，不作为接口契约依据**，实际以控制台显示为准。

| permissionCode      | permissionName | 对应业务接口（参考）                                                                     |
| :------------------ | :------------- | :----------------------------------------------------------------------------- |
| `GEO_AI_QUESTIONS`  | AI对话问题挖掘       | [AI 对话问题挖掘](/api-reference/question-discovery)（`geo.questions_corr_recommend`） |
| `GEO_RANK_QUERY`    | GEO排名查询        | [GEO 排名查询工具](/api-reference/ranking)（`geo.ranking`）                            |
| `GEO_BRAND_MONITOR` | GEO 品牌得分检测     | [GEO 品牌得分检测](/api-reference/brand-score)（`geo.brand`）                          |
| `GEO_URL_MENTION`   | GEO 推广链接检测     | [GEO 推广链接检测](/api-reference/geo-checker)（`geo.checker`）                        |
| `GEO_RANK_MONITOR`  | GEO 排名监测       | [GEO 排名监测](/api-reference/rank-monitor)（`geo.rank_monitor`）                    |

<Warning>
  `GEO_RANK_MONITOR_EXPORT_DATA`（导出数据）、`GEO_RANK_MONITOR_REPORT_GENERATION`（生成报告）、`PROMPTION_NEWS`、`DEDICATED_CUSTOMER_SERVICE` 属于平台侧功能权益，与开放 API 的 `apiCode` 无对应关系。
</Warning>

## 类型定义

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    public class AIBaseResponse<T> {
        private Integer code;
        private String msg;
        private T data;
        private Long timeStamp;
    }

    public class QuotaUsageData {
        private List<QuotaPermission> permissions;
        private Integer points;
    }

    public class QuotaPermission {
        private String permissionCode;
        private String permissionName;
        private List<String> aiPlatforms;   // 可能为 null
        private Integer totalLimit;         // 可能为 null
        private Integer usedCount;          // 可能为 null
        private Integer remainingCount;     // 可能为 null
    }
    ```

    完整响应类型为 `AIBaseResponse<QuotaUsageData>`。三个计数字段需使用包装类型 `Integer` 以兼容 `null`。
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    export interface AIBaseResponse<T> {
      code: number;
      msg: string;
      data: T | null;
      timeStamp: number;
    }

    export interface QuotaUsageData {
      permissions: QuotaPermission[];
      points: number;
    }

    export interface QuotaPermission {
      permissionCode: string;
      permissionName: string;
      aiPlatforms: string[] | null;
      totalLimit: number | null;
      usedCount: number | null;
      remainingCount: number | null;
    }
    ```
  </Tab>
</Tabs>

## 接入注意事项

1. 请求方式固定为 `GET`，接口地址固定为 `https://api.aibase.cn/v1/openapi/quota/usage`。
2. **本接口无需 `apiCode`，也无需请求体**，不要按统一任务入口的格式提交。
3. `AIBase-API-Key` 必须通过请求头传递，不要拼接在 URL 查询串中。
4. 先判断外层 `code` 是否为 `200`，成功后再读取 `data`；失败时 `data` 可能为 `null`。
5. **`data` 下没有 `result` 层级**，`points` 与 `permissions` 直接位于 `data` 之下。
6. `permissions[].totalLimit`、`usedCount`、`remainingCount` 以及 `aiPlatforms` 都可能为 `null`（表示无限制或不适用），客户端必须做空值兼容，不要用 `0` 兜底参与额度判断。
7. `permissions` 可能为空数组，遍历前先判空。
8. API Key 属于敏感凭证，应仅在服务端使用，避免在前端或日志中暴露查询结果。

<Tip>
  批量跑批前先调用本接口核对 `remainingCount`，可在提交前规避配额耗尽导致的失败；出现异常时按[联调排错清单](/platform/troubleshooting)逐项检查。
</Tip>