AIゲートウェイの設計2026年11月5日Flatkey Team

AIチャットボットAPI：適切なレイヤーを選び、安全に構築する

モデルAPIとチャットボットプラットフォームAPIの違い、チャットアシスタントの統合方法、コスト・セキュリティ・有人対応のテスト方法を解説します。

AIチャットボットAPIとは？

AIチャットボットAPIは、アプリケーションがユーザーメッセージを送信し、会話体験のための応答を受け取れるようにするプログラム用インターフェースです。この言葉は、2種類の異なる製品を指す場合があります。モデルAPIは、プロンプトと会話コンテキストから次の回答を生成します。チャットボットプラットフォームAPIは、会話の保存、チャネル、有人対応への引き継ぎ、ワークフロールール、分析も提供できます。料金を比較したり統合例をコピーしたりする前に、プロバイダーがどちらの意味でこの言葉を使っているか確認してください。

シンプルなサポートアシスタントの場合、リクエストパスは通常、chat UI → your server → model or chatbot API → your server → chat UIです。サーバーでキーを管理し、リクエストを検証し、ボットに使用を許可するコンテキストだけを付加し、応答をどう扱うかを決定する必要があります。API呼び出しは製品の一部にすぎません。信頼できるナレッジ、アクセス制御、安全なアクションワークフローが自動的に提供されるわけではありません。

このガイドは、開発者が適切なAPIレイヤーを選択し、最初の呼び出しを行い、コストを見積もり、実際のユーザーが利用する前にチャットボットをテストするのに役立ちます。また、Flatkeyのようなマルチモデルルーターがどこに適合するかも説明します。Flatkeyはモデル向けのAPIインターフェースを提供するものであり、すぐに使えるカスタマーサポート受信トレイや会話データベースの代替ではありません。

用途に合ったAPIレイヤーを選ぶ

必要なもの	まず使い始めるもの	引き続き自社で管理または検証する必要があるもの
アプリ内のカスタムチャットインターフェース	モデルAPIまたは互換ルーター	UI、ユーザーID、履歴、検索、セーフティ、評価
Webサイトやメッセージングチャネルをまたぐサポートボット	チャネルAPIと有人対応引き継ぎAPIを備えたチャットボットプラットフォーム	統合、エスカレーションポリシー、データ権限、レポート
社内文書に根拠づけられた回答	モデルAPIと検索、またはその機能を持つプラットフォーム	インデックスの品質、出典引用、文書権限、鮮度
レコード変更やメッセージ送信を行うツール呼び出し	ツール呼び出しをサポートするモデルAPIと自社サーバー側の実行機能	認可、確認、監査ログ、ロールバック
1つのクライアントの背後に複数のモデルまたはプロバイダー	互換ルーター	モデル選択、品質テスト、利用上限、プロバイダー固有の違い

最初の判断は、見た目ではなく運用上のものです。専用チャットボットプラットフォームは、チャネルと有人対応の作業を削減できる一方、アプリケーションのワークフローを制約する可能性があります。直接モデルAPIを使うと体験をより細かく制御できますが、チームはスタックのより多くの部分を構築する必要があります。ルーターは、チャットボット製品としての責任を自社に残したまま、モデル切り替えを簡素化できます。

チャットボットのリクエストが返信になるまで

ブラウザーは、会話識別子とともにメッセージをアプリケーションサーバーへ送信します。サーバーはユーザーを検証し、許可された会話コンテキストを読み込み、選択したモデルへのリクエストを作成します。モデルはテキスト、構造化出力、またはチャンクのストリームを返します。サーバーは結果を検証し、保持ポリシーに従ってターンを記録し、安全な応答をブラウザーに送信します。

会話状態は明示的に設計する必要があります。一部のAPIは、呼び出しごとにメッセージ履歴全体を受け取ります。一方で、プロバイダー管理の状態を提供するAPIもあります。OpenAI Responses documentationとGemini multi-turn documentationでは、コンテキストを引き継ぐ異なる方法が説明されています。プロバイダーがターンを保存、削除、分離する方法が他社と同じだと想定しないでください。選択したエンドポイントが履歴、切り詰め、削除、データ保持をどのように処理するかテストしてください。

プロバイダーがリモートスレッドIDを提供する場合でも、安定した内部会話IDを保持してください。これにより、アプリで権限を適用し、再試行、メッセージ、コスト、有人対応への引き継ぎを関連付ける場所を確保できます。タスクに必要な履歴だけを保存してください。長いトランスクリプトはレイテンシーと課金対象の入力を増やし、ボットが古い指示を繰り返す原因にもなります。

最初のAIチャットボットAPI統合

小規模で公開されたヘルプセンターに関する質問への回答など、1つのタスクから始めてください。許可するトピック、応答スタイル、フォールバック回答、人間の連絡先オプションを表示するタイミングを定義します。次に、この最小限のサーバー側パスを構築します。

スコープを限定したAPIキーを作成し、サーバー側のシークレットストアまたは保護された環境変数に保存します。ブラウザーJavaScript、モバイルバンドル、公開リポジトリに絶対に含めないでください。
文書化されたチャット対応モデルとエンドポイントを選択します。現在のモデルカタログで、コンテキスト上限、ツールサポート、ストリーミング、料金を確認してください。
自社の認証済みエンドポイントでユーザーのメッセージを受け取ります。長さとレートを制限し、会話IDを検証し、その会話にアクセスできないユーザーからのメッセージは拒否します。
小さなシステム指示と、直近の関連コンテキストをAPIに送信します。文書を使用する場合は、ナレッジベース全体をすべてのプロンプトに入れるのではなく、許可された少数のパッセージを取得してください。
成功、タイムアウト、レート制限、プロバイダーエラーを個別に処理します。アプリで安全に表示できるメッセージを返し、診断のためにリクエストIDを保持します。
応答を表示する前、またはツールを実行する前に検証します。ターンを保存し、レイテンシー、エラー、トークンまたはユニット使用量、モデルIDを自社のテレメトリーに出力します。

Flatkey APIドキュメントでは、OpenAI互換ルーターと現在のモデルカタログを確認できます。Flatkeyクイックスタートでは、そのルーターを介した最初のリクエストを取り上げています。正確なモデルIDとエンドポイント形式についてはライブドキュメントを参照してください。ブログからコピーしたコードサンプルは、モデルより長く残る可能性があります。チャットボットプラットフォームのチャネル機能や有人対応への引き継ぎ機能が必要な場合は、モデルルーターがそれらを提供すると想定せず、そのプラットフォームのAPIを個別に確認してください。

小さなリクエスト契約

独自のエンドポイントでは、conversation_id と message を受け取り、reply、request_id、およびステータスを返すようにできます。クライアントに任意のプロバイダーURLを選ばせたり、APIキーを渡させたりしないでください。サーバーがサポート対象のモデルを選択し、制御下にあるポリシーとコンテキストを付加します。

ストリーミングでは、検証済みの出力チャンクだけをユーザーに転送し、切断を処理してください。ブラウザーが接続を閉じても、必ずしもプロバイダー呼び出しがキャンセルされるとは限りません。部分的な返信を保存するか、再試行するか、そのターンを未完了としてマークするかを定義してください。構造化されたツール呼び出しでは、引数を信頼できない入力として扱い、アクションを許可するかどうかはアプリケーションに判断させてください。

検索、ツール、有人対応への引き継ぎ

企業固有の質問に答えるチャットボットには、信頼できる情報源が必要です。検索は、ヘルプセンター、ポリシーライブラリ、製品カタログから関連する文章を選び、モデルに渡すことができます。難しいのはベクトル検索だけではありません。取得した文章は、最新で関連性があり、そのユーザーに表示可能でなければなりません。情報源に答えがない質問でテストしてください。ボットはポリシーを捏造するのではなく、答えがないと伝えるか、エスカレーションすべきです。

ツールの使用は重要性を高めます。モデルは、チケット更新、返金、予約、または送信メッセージを提案する場合があります。サーバーは、実行者の権限を確認し、ツール引数を検証し、ビジネスルールを適用し、何が起きたかを記録する必要があります。取り消し不可能なアクションでは、確認ステップまたは人によるレビューを使用してください。会話型インターフェースはセキュリティ境界ではありません。

リリース前に引き継ぎを定義してください。ボットが拒否すべき質問、人間の担当者が受け取るコンテキスト、ユーザーが引き継ぎの発生をどのように認識するかを明確にします。チャットボットプラットフォームはこのワークフローを提供する場合があります。モデルAPIだけを使用する場合は、自分で構築する必要があります。引き継ぎが発生する頻度と、会話コンテキストが担当者による問題解決に役立ったかを測定してください。

AIチャットボットAPIの実際のコスト

モデルAPIの場合、月間モデルコストはおおよそ 受理された会話数 × 平均ターン数 × 1ターンあたりの課金対象入力・出力単位 × 現在の単価 です。これは見積もりの出発点であり、正式な価格提示ではありません。実際の請求には、キャッシュされた入力、検索、検索以外のツール、再試行、安全性チェック、画像または音声入力、より長い会話履歴も含まれる場合があります。チャットボットプラットフォームでは、シート、チャネル、ワークフロー実行、または会話に対する料金が追加される可能性があります。

自社のテストデータから小さなワークロード表を作成してください。会話あたりのメッセージ数、ターンごとのコンテキスト長、平均およびロングテールの出力サイズ、ユーザーが受け入れる返信の割合を記録します。単一のモデル応答だけでなく、解決済みの会話に価格を付けてください。再試行や引き継ぎを多く発生させる安価な呼び出しは、全体としてより高コストになる可能性があります。

レート制限は別の制約です。ピーク時の同時ユーザー数と1分あたりのターン数を見積もり、プロバイダーが制限を返した場合に何が起こるかをテストしてください。短時間の再試行をキューに入れることは合理的な場合がありますが、無制限の再試行ストームはコストを増大させ、障害を悪化させる可能性があります。フォールバックとして2つ目のモデルを追加する場合は、実際のユーザーをルーティングする前に、回答品質、ツール動作、応答形式を比較してください。

Flatkeyの料金ページは、同社のルーター経由で利用する現在のモデル料金の情報源です。コスト見積もりでルーターを使用する前に、そこで正確なモデルとリクエスト単位を確認してください。直接プロバイダーやチャットボットプラットフォームについても同様です。公開料金と無料利用枠は変更されます。

リリース前のセキュリティとプライバシーの確認

キーはサーバー上で保護し、プロバイダーが対応している場合はスコープを制限してください。会話や取得したドキュメントを閲覧できるユーザーを制限します。プロンプトをログに残すのが便利だからといって、トレースに個人データを含めないでください。会話、リクエスト、モデル出力をどのくらい保持するかを決定し、そのポリシーをプロバイダーの現在の処理条件と比較してください。

取得したウェブページやユーザーメッセージは、システムに対する権限を持つ命令ではなく、データとして扱ってください。悪意あるページには、ボットに秘密を明かさせたり、そのタスクを無視させたりするプロンプトインジェクションの文言が含まれることがあります。システムポリシーは取得コンテンツの外部に置き、ツールを必要最小限に制限し、提案されたすべてのアクションを検証してください。LLMアプリケーション向けOWASP Top 10は、このレビューのための実践的な脅威チェックリストを提供します。

実際の例で、危険または曖昧なケースをテストしてください。別の顧客の情報を求めるリクエスト、注文変更のリクエスト、競合する取得文章、利用できない情報源などです。ボットが複数の言語に対応する場合は、多言語の質問も含めてください。認証情報や生のプロバイダー応答を公開することなく、エスカレーションおよびエラーメッセージが有用であることを確認してください。

候補を半日で比較する方法

同じ30～50件の代表的な会話を、各候補に対して使用してください。単純なFAQ、複数ターンのフォローアップ、検索を必要とする質問、対象範囲外の質問、そしていくつかの敵対的入力を含めます。根拠に基づく正確性、証拠がない場合の回答拒否、応答レイテンシ、引き継ぎの品質、受け入れられた結果あたりのコスト、エラーの診断のしやすさを評価します。モデルが変更されたときに繰り返し実施できるよう、プロンプトと期待される結果を小規模な評価セットにまとめておきます。

必要なモデルが1つだけで、既存の直接プロバイダーのアカウントが要件を満たしている場合は、そこから始めてください。複数のサポート対象モデルにわたって一貫したクライアント形式が必要な場合は、同じ会話セットでルーターを評価します。チャネル、チケット管理、または有人対応への引き継ぎが主な要件である場合は、まずチャットボットプラットフォームを評価してください。最適なAIチャットボットAPIとは、実際に構築する製品にその責務が一致するものです。