--- title: "开放接口概览" description: "在控制台自助签发只读密钥,通过开放接口将 XiuAI 账户数据接入监控、对账和团队内部报表。" image: "https://docs.xiu.ai/og.png" --- > XiuAI 文档索引 > 完整文档索引:https://docs.xiu.ai/llms.txt > 阅读前先通过索引确认当前可用页面。 # 开放接口概览 通过开放接口,你可以定期读取账户余额、同步请求记录,并按模型和调用密钥汇总费用,用于余额监控、费用对账和团队内部报表。 接口只读取密钥所属 XiuAI 账户的数据。它使用独立的只读密钥,不能调用模型、充值或修改账户。模型调用继续使用 [XiuAI API Key](/router/quickstart/)。 | 用途 | 请求 | 所需权限 | | --- | --- | --- | | 查询余额和累计消耗 | [`GET /open/v1/balance`](/open-api/balance/) | `balance:read` | | 同步逐条请求记录 | [`GET /open/v1/requests`](/open-api/requests/) | `usage:read` | | 按时间段汇总用量与费用 | [`GET /open/v1/requests/summary`](/open-api/summary/) | `usage:read` | 基址为 `https://api.xiu.ai`。所有请求使用 HTTPS,响应为 UTF-8 JSON。 ## 获取密钥 密钥在控制台自助签发,无需联系客服: 1. 登录 [XiuAI 控制台](https://router.xiu.ai/zh/console/open-api),进入「开放接口」页。 2. 点击「签发密钥」,填写名称,勾选所需权限,按需选择有效期。查询余额需要 `balance:read`;查询请求记录与费用汇总需要 `usage:read`。需要两类数据时两项都勾选。 3. 复制以 `xiu_sk_` 开头的完整密钥,保存到服务端的密钥管理服务或环境变量中。完整密钥只在签发时显示一次,关闭后只能查看末 4 位。 每个账户最多同时持有 10 把有效密钥。已有密钥缺少权限时,在控制台修改权限即可,无需更换密钥;遗失或怀疑泄露时,在控制台吊销并重新签发,吊销立即生效。密钥的所属账户和有效期在签发后不能修改。 管理员也可以为你的账户代签密钥,代签的密钥同样出现在你的控制台列表中,你可以修改或吊销。 `usage:read` 可以读取所属账户的全部请求记录。`keyName` 只用于筛选结果,不限制这把只读密钥的数据访问范围;它不提供项目或团队成员之间的权限隔离。 ## 认证与首次查询 每个请求都携带 `Authorization: Bearer` 请求头。不要通过 URL 参数或 Cookie 传递密钥。 将密钥注入服务端环境变量 `XIU_OPEN_API_KEY` 后,可运行: ```bash curl --fail-with-body --silent --show-error \ --connect-timeout 5 --max-time 15 \ https://api.xiu.ai/open/v1/balance \ -H "Authorization: Bearer $XIU_OPEN_API_KEY" ``` 成功时返回 HTTP `200` 和余额 JSON。收到 `401` 时,检查是否使用了以 `xiu_sk_` 开头的只读密钥,再到[控制台](https://router.xiu.ai/zh/console/open-api)核对密钥状态;收到 `403` 时,在控制台为这把密钥补充 `balance:read`。 只在服务端使用密钥,不要放入浏览器、移动应用、代码仓库、日志或工单。接口不返回 CORS 头,浏览器不能直接调用。需要在自己的页面展示数据时,由你的服务端读取后提供给页面。 首次查询成功后,可按[余额字段说明](/open-api/balance/)读取结果。需要同步调用数据时,继续查看[请求记录](/open-api/requests/)和 [Python 示例](/open-api/examples/)。 源文件:https://docs.xiu.ai/open-api/index.mdx