AIGateway API の使い方
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/aigateway-api-usage/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
AIGateway は、Worker が内部から呼び出すためだけの境界ではありません。外部アプリケーション、社内システム、各種 SDK から直接利用できる REST API でもあります。このページでは AIGateway の概念ページを補完し、外部の呼び出し元向けにエンドポイント、認証方式、呼び出しモード、具体的なリクエスト例を紹介します。
AIGateway の呼び出しは Principal ごとにスコープ分離され、Agent または OIDC Human の bearer token が必要です。Responses API は OpenResponses 形式のリクエストを受け取り、JSON またはイベントストリームを返します。メディアやファイルのエンドポイントには、それぞれのスキーマと Content-Type を使います。上流 provider の認証情報は control plane が保管します。
認証
/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": "Hello" }'
受け付けられるトークンは次の 2 種類です。
- Agent token — 特定の Agent の model binding にスコープされたトークンです。外部連携が特定の Agent として処理を実行する場合に使用します。
- OIDC Human token —
ai_gateway.writeスコープを持つ OIDC Client から有効な Human に発行されるトークンです。その Client に許可されたモデルエイリアスのみを使用でき、subject_type = "oidc_human"として扱われます。
OIDC Human token を取得するには、Console で ai_gateway.write スコープを持つ OIDC Client を作成し、許可するグループとモデルエイリアスを設定したうえで、Authorization Code + PKCE でログインします。長期間利用する場合は offline_access を要求し、ローテーション式の Refresh Token を使用してください。利用する人間は許可されたグループに所属している必要があり、指定できるのはその Client のモデルエイリアスのみです(provider_id/model 形式の直接指定はできません)。
トークンからどのように Principal が解決されるかについては、Principal and AuthZ を参照してください。
ステートレスレスポンス(HTTP と SSE)
ステートレス呼び出しは、1 回のリクエストに対して 1 回のレスポンスが返るシンプルな方式です。入力全体を送ると、完了したレスポンスボディ全体が返されます。
curl https://ankole.example.com/api/v1/ai-gateway/responses \
-H "Authorization: Bearer $AIGATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "model": "primary", "input": "Summarize this thread.", "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": "Draft a release note.", "stream": true }'
HTTP と SSE のステートレス呼び出しでは、previous_response_id、conversation、および false 以外の store を拒否します。store は省略するか store: false を指定できます。ターンをまたいで会話を継続する場合は WebSocket を使用してください。
その他のエンドポイント
| エンドポイント | 用途 |
|---|---|
GET /models |
現在の認証主体から利用可能なモデルを一覧取得 |
POST /embeddings |
embedding を生成 |
POST /rerank |
ドキュメントを再ランク付け |
POST /web_search |
Web を検索 |
POST /web_fetch |
Web ページを取得 |
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、トークンの 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 言語モデルが未較正の確率で回答します。
このガイドではないもの
このページは AIGateway 全体の仕様書ではありません。全ルートの一覧、WebSocket 上のステートフルなライフサイクル、エラーレスポンスの詳細については AIGateway を参照してください。また、Ankole では専用のクライアント SDK を配布していないため、標準の HTTP クライアントや OpenResponses 互換クライアントから直接 REST API を呼び出してください。
次のステップ
- AIGateway の全仕様については、AIGateway を参照してください。
- Provider の解決ロジックとリクエスト準備の仕組みについては、Provider Runtime を参照してください。
- Console 側の管理 API については、Console API reference を参照してください。