本文へスキップ
Ankole

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 を参照してください。