OpenAPI 接口

认证

项目	说明
基础地址	`https://xhyapi.com/api/v1`
认证头	`x-api-key: s2o-...`（在「个人中心 → OpenAPI 密钥」创建，未开通请联系我们）
请求体	`Content-Type: application/json`

成功响应：

json

{ "code": 0, "message": "成功", "data": { } }

分页接口的 data 为 { "items": [], "total": 0, "page": 1, "page_size": 20, "pages": 1 }。

API Key

GET /keys

列出 API Key。

参数	类型	说明
`page` / `page_size`	int	分页
`search`	string	按名称或 Key 搜索
`status`	string	`active` / `inactive` / `quota_exhausted` / `expired`
`group_id`	int	按分组过滤

POST /keys

创建 API Key。建议携带 Idempotency-Key 请求头，重试时不会重复创建。

字段	类型	必填	说明
`name`	string	是	名称
`group_id`	int	否	分组 ID，见 `GET /groups/available`
`quota`	number	否	总额度（元），`0` 为不限额
`expires_in_days`	int	否	有效天数，不传为永不过期
`ip_whitelist`	string[]	否	允许调用的 IP / CIDR
`rate_limit_5h` / `rate_limit_1d` / `rate_limit_7d`	number	否	窗口内消费上限（元），`0` 为不限

bash

curl -X POST https://xhyapi.com/api/v1/keys \
  -H "x-api-key: $S2O" -H "Content-Type: application/json" \
  -H "Idempotency-Key: user-1001-open" \
  -d '{"name":"user-1001","group_id":1,"quota":50}'

返回 API Key 对象：

字段	说明
`id`	Key ID
`key`	`sk-` 密钥，用于调用模型
`name` / `group_id` / `status`	名称 / 分组 / 状态
`quota` / `quota_used`	总额度 / 已用额度（元）
`expires_at`	过期时间，`null` 为永不过期
`last_used_at` / `last_used_ip`	最近使用时间 / IP
`created_at` / `updated_at`	创建 / 更新时间

GET /keys/:id

查看单个 API Key，返回 API Key 对象。

PUT /keys/:id

修改 API Key，只传需要修改的字段。

字段	类型	说明
`quota`	number	总额度（元）。累计值，不是增量；`0` 为不限额。调高到超过 `quota_used` 后，已用尽的 Key 自动恢复
`status`	string	`active` / `inactive`
`name`	string	名称
`group_id`	int	分组 ID
`expires_at`	string	过期时间（ISO 8601）
`ip_whitelist`	string[]	IP 白名单，空数组为清空
`reset_quota`	bool	将 `quota_used` 清零
`rate_limit_5h` / `rate_limit_1d` / `rate_limit_7d`	number	同创建

bash

curl -X PUT https://xhyapi.com/api/v1/keys/123 \
  -H "x-api-key: $S2O" -H "Content-Type: application/json" \
  -d '{"quota":150}'

DELETE /keys/:id

删除 API Key。

账户与分组

方法	路径	说明
GET	`/user/profile`	账户信息，`balance` 为账户余额。所有 Key 共用该余额扣费
GET	`/groups/available`	可用分组
GET	`/groups/rates`	分组倍率

用量

方法	路径	说明
GET	`/usage`	用量明细（分页）
GET	`/usage/stats`	用量汇总
GET	`/usage/:id`	单条用量记录
GET	`/user/api-keys/:id/usage/daily`	单个 Key 按日用量，参数 `days`
POST	`/usage/dashboard/api-keys-usage`	批量查询 Key 用量，请求体 `{"api_key_ids":[1,2]}`，最多 100 个
GET	`/usage/dashboard/stats` · `/trend` · `/models` · `/snapshot-v2`	统计概览 / 趋势 / 按模型 / 快照

/usage、/usage/stats 参数：api_key_id、start_date、end_date（YYYY-MM-DD）、model、page、page_size。

限流

每账号 240 次/分钟；用量类接口另限 60 次/分钟。超出返回 429，按响应头 Retry-After（秒）重试。

错误码

认证类错误码在 code（字符串）；业务类错误 code 为 HTTP 状态码，错误码在 reason。

HTTP	错误码	说明
401	`INVALID_OPEN_API_KEY`	密钥无效或已删除
401	`USER_INACTIVE`	账号已停用
403	`USER_OPEN_API_DISABLED`	未开通 OpenAPI
403	`OPEN_API_IP_FORBIDDEN`	来源 IP 不在密钥白名单内
403	`OPEN_API_ROUTE_FORBIDDEN`	接口未开放
409	`IDEMPOTENCY_KEY_CONFLICT`	同一 `Idempotency-Key` 对应了不同的请求内容
429	`RATE_LIMITED`	触发限流
400 / 404	见 `reason`	参数错误 / 资源不存在
500	`INTERNAL_ERROR`	服务端异常

OpenAPI 接口 ​

认证 ​

API Key ​

GET /keys ​

POST /keys ​

GET /keys/:id ​

PUT /keys/:id ​

DELETE /keys/:id ​

账户与分组 ​

用量 ​

限流 ​

错误码 ​