接入说明

调用格式、令牌规则、错误码与限流

一、调用格式

所有调用统一走网关 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_invalid403令牌不存在或校验失败
token_expired403令牌已过期
token_exhausted403总次数已用尽
account_inactive403账号被停用
ip_not_allowed403来源 IP 不在授权名单内
skill_not_open403该 Skill 已停止对外
rate_limited429超过每分钟或每日频率上限
project_forbidden403令牌与所调用的业务归属不匹配

四、限流与配额

  • 默认每日 200 次、总计 2000 次,审批时可由管理员调整。
  • 默认每分钟 30 次;超限返回 429 rate_limited,退避重试即可。
  • 审计网关对单个来源限速 50 请求/秒(突发 100)、并发 60;超限由网关直接 429。
  • 注册、找回口令等页面操作在本平台侧按来源 IP 限流,避免被批量利用。