跳到正文
EN

开放接口概览

在控制台自助签发只读密钥,通过开放接口将 XiuAI 账户数据接入监控、对账和团队内部报表。

更新于 复核于
查看 Markdown

通过开放接口,你可以定期读取账户余额、同步请求记录,并按模型和调用密钥汇总费用,用于余额监控、费用对账和团队内部报表。

接口只读取密钥所属 XiuAI 账户的数据。它使用独立的只读密钥,不能调用模型、充值或修改账户。模型调用继续使用 XiuAI API Key。

用途 请求 所需权限
查询余额和累计消耗 GET /open/v1/balance balance:read
同步逐条请求记录 GET /open/v1/requests usage:read
按时间段汇总用量与费用 GET /open/v1/requests/summary usage:read

基址为 https://api.xiu.ai。所有请求使用 HTTPS,响应为 UTF-8 JSON。

获取密钥

密钥在控制台自助签发,无需联系客服:

  1. 登录 XiuAI 控制台,进入「开放接口」页。
  2. 点击「签发密钥」,填写名称,勾选所需权限,按需选择有效期。查询余额需要 balance:read;查询请求记录与费用汇总需要 usage:read。需要两类数据时两项都勾选。
  3. 复制以 xiu_sk_ 开头的完整密钥,保存到服务端的密钥管理服务或环境变量中。完整密钥只在签发时显示一次,关闭后只能查看末 4 位。

每个账户最多同时持有 10 把有效密钥。已有密钥缺少权限时,在控制台修改权限即可,无需更换密钥;遗失或怀疑泄露时,在控制台吊销并重新签发,吊销立即生效。密钥的所属账户和有效期在签发后不能修改。

管理员也可以为你的账户代签密钥,代签的密钥同样出现在你的控制台列表中,你可以修改或吊销。

usage:read 可以读取所属账户的全部请求记录。keyName 只用于筛选结果,不限制这把只读密钥的数据访问范围;它不提供项目或团队成员之间的权限隔离。

认证与首次查询

每个请求都携带 Authorization: Bearer 请求头。不要通过 URL 参数或 Cookie 传递密钥。

将密钥注入服务端环境变量 XIU_OPEN_API_KEY 后,可运行:

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_ 开头的只读密钥,再到控制台核对密钥状态;收到 403 时,在控制台为这把密钥补充 balance:read。

只在服务端使用密钥,不要放入浏览器、移动应用、代码仓库、日志或工单。接口不返回 CORS 头,浏览器不能直接调用。需要在自己的页面展示数据时,由你的服务端读取后提供给页面。

首次查询成功后,可按余额字段说明读取结果。需要同步调用数据时,继续查看请求记录和 Python 示例。

导航

输入关键词开始搜索

↑↓ 移动↵ 打开Esc 关闭