接入说明
调用格式、令牌规则、错误码与限流一、调用格式
所有调用统一走网关 https://ai.angh.cn:54003/api,不经服务平台。令牌可放在地址参数或 Authorization 头。
# 1) 不带 do:返回该 Skill 的完整功能清单
curl "https://ai.angh.cn:54003/api?token=<令牌>"
# 2) 调用具体功能(GET 传参)
curl "https://ai.angh.cn:54003/api?token=<令牌>&do=catalog"
# 3) POST + JSON 参数
curl -X POST "https://ai.angh.cn:54003/api?token=<令牌>&do=run" \
-H 'content-type: application/json' -d '{"script":"agentic_check.py"}'
# 4) 请求头传令牌(推荐,避免令牌出现在 URL 与日志里)
curl -H "Authorization: Bearer <令牌>" "https://ai.angh.cn:54003/api?do=catalog"
二、令牌规则
- 只有申请时报备的 IP 能调用,换网络会返回 403
ip_not_allowed;出口 IP 变化请联系管理员改 IP,不必重新申请。 - 授权到期自动失效,默认 24 小时,需要继续使用请重新申请。
- 令牌等同于口令:不要写进前端代码、不要提交到 Git、不要贴到公开聊天。
- 一枚令牌只绑定一个 Skill;同一账号对同一 Skill 同时只能有一份生效授权。
- 管理员可以随时调整 IP、时长与配额,或撤销授权;Skill 关闭对外时该 Skill 的全部令牌立即失效。
三、错误码
| 错误码 | HTTP | 含义 |
|---|---|---|
| token_invalid | 403 | 令牌不存在或校验失败 |
| token_expired | 403 | 令牌已过期 |
| token_exhausted | 403 | 总次数已用尽 |
| account_inactive | 403 | 账号被停用 |
| ip_not_allowed | 403 | 来源 IP 不在授权名单内 |
| skill_not_open | 403 | 该 Skill 已停止对外 |
| rate_limited | 429 | 超过每分钟或每日频率上限 |
| project_forbidden | 403 | 令牌与所调用的业务归属不匹配 |
四、限流与配额
- 默认每日 200 次、总计 2000 次,审批时可由管理员调整。
- 默认每分钟 30 次;超限返回 429
rate_limited,退避重试即可。 - 审计网关对单个来源限速 50 请求/秒(突发 100)、并发 60;超限由网关直接 429。
- 注册、找回口令等页面操作在本平台侧按来源 IP 限流,避免被批量利用。