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 参考。