跳到正文
Ankole

AIGateway API 使用

面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/aigateway-api-usage/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

AIGateway 不仅是内部 Worker 调用的模型边界,也是一套可直接供外部应用、企业业务系统和各类 SDK 调用的 REST API。本页作为 AIGateway 架构文档的实战补充,通过完整请求示例说明外部调用方如何完成鉴权、选择调用模式并访问常用端点。

AIGateway 按调用主体隔离数据与权限,调用方须出示 Agent 或 OIDC 人类 Bearer Token。Responses API 接受 OpenResponses 格式的请求,并返回 JSON 或事件流;媒体与文件端点使用各自的 Schema 和 Content-Type。上游 Provider 凭据保存在控制面内。

鉴权

访问 /api/v1/ai-gateway 下的任意端点都必须在请求头中携带 Bearer Token:

curl https://ankole.example.com/api/v1/ai-gateway/responses \
  -H "Authorization: Bearer $AIGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "model": "primary", "input": "你好" }'

网关接受以下两类令牌:

  • Agent Token:权限范围限定在单个 Agent 的模型绑定内,适用于外部集成代表特定 Agent 发起调用的场景。
  • OIDC 人类令牌:由声明了 ai_gateway.write 作用域的 OIDC 客户端为活跃人类用户(Human)签发;请求只能使用该客户端配置的模型别名,subject_type = "oidc_human"。

获取 OIDC 人类令牌的方法:先在控制台中创建带有 ai_gateway.write 作用域的 OIDC 客户端,配置允许访问的权限组与模型别名,再通过授权码加 PKCE 流程登录;需要长期调用时可申请 offline_access,配合轮换式 Refresh Token 使用。人类用户必须属于客户端允许的权限组,且只能传入客户端公开的模型别名,不能使用原始的 provider_id/model 选择符。

关于令牌如何解析为系统主体,请参阅 主体与 AuthZ。

无状态响应(HTTP 和 SSE)

无状态调用采用“一次请求、一次响应”模式。提交完整输入后,接口直接返回完整的 JSON 响应体:

curl https://ankole.example.com/api/v1/ai-gateway/responses \
  -H "Authorization: Bearer $AIGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "model": "primary", "input": "总结这段对话。", "store": false }'

如需流式接收生成内容,在请求体中加入 "stream": true,同一端点即切换为 Server-Sent Events(SSE)流:

curl -N https://ankole.example.com/api/v1/ai-gateway/responses \
  -H "Authorization: Bearer $AIGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "model": "primary", "input": "起草一份发布说明。", "stream": true }'

无状态 HTTP 与 SSE 拒绝 previous_response_id、conversation,以及值不为 false 的 store。可以省略 store,也可以显式设置 store: false;如需跨回合持久化续接对话,请使用 WebSocket 端点。

其它端点

端点 用途
GET /models 列出当前主体可用的模型
POST /embeddings 生成向量嵌入(Embedding)
POST /rerank 对文档列表重排序
POST /web_search 搜索公开网页
POST /web_fetch 抓取网页正文
POST /decisions 回答带类型的问题并给出概率
POST /images 生成或编辑图片
POST /audio/speech 把文本合成为语音
POST /audio/transcriptions 把音频转写为文本
POST /ocr 把 PDF 或文档图片识别为 Markdown
POST /videos 发起视频生成,再用 GET /videos/:id 读取任务、GET /videos/:id/content 读取文件
POST /audio/music 发起音乐生成,再用 GET /audio/music/:id 读取任务、GET /audio/music/:id/content 读取文件

各端点的详细参数说明请参阅 AIGateway 及用户指南中的对应功能页。

带概率的决策

应用需要概率而非生成文本时,可以调用 POST /decisions。decision.default 选择符解析 Pod/Site 的决策模型档案;也可以显式指定 provider_id/model,直接选择决策模型。

curl https://ankole.example.com/api/v1/ai-gateway/decisions \
  -H "Authorization: Bearer $AIGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decision.default",
    "state": {"ticket": "I was charged twice."},
    "questions": {
      "urgent": {"type": "noul", "instructions": "Does this need a reply today?"},
      "team": {
        "type": "choice",
        "instructions": "Which team owns this ticket?",
        "criteria": {"billing": "Payments and refunds", "support": "Product questions"}
      }
    }
  }'

score 问题的 criteria 包含 2 到 10 个有序等级标签。响应包含 model、answers 和 token usage,每个答案都带有概率。TypeSafe、Azure Foundry、OpenRouter、OpenAI、Google AI Studio 和 Cloudflare 的决策模型共用这一公开请求格式,但上游图像能力不同:SystemOne 接受 PNG/JPEG,Microsoft-Decision-1 仅支持文本,OpenAI 和 Google AI Studio 还支持 WebP。OpenAI 拒答或 Google 安全策略拦截时,网关返回 422 upstream_decision_refusal,不返回残缺答案。未配置决策模型档案时,由调用方的 light 语言模型作答,其概率未经校准。

本指南不是什么

本页不是完整的网关协议规范——全量路由表、WebSocket 有状态生命周期与错误码定义请查阅 AIGateway。同时,Ankole 也不单独维护专用客户端 SDK,调用方使用任意标准 HTTP 客户端或兼容 OpenResponses 的通用客户端即可直接接入。

下一步

  • 查阅完整的 AIGateway 路由契约与有状态连接规范,请参阅 AIGateway。
  • 了解底层 Provider 的路由解析与请求组装机制,请参阅 Provider Runtime。
  • 查阅管理控制台的接口规范,请参阅 Console API 参考。