OpenAI Chat Completions API：機能と使い方ガイド

AI搭載アプリケーションの構築は、モデルに応答を生成させるだけでは済みません。会話を管理し、応答を導き、すべてをアプリケーションに接続するための信頼できる方法も必要です。OpenAI Chat Completions APIでは、AIがメッセージをどのように処理し、回答を生成するかを開発者が制御できます。仕組みや自分のプロジェクトでの使い方を知りたい方に向けて、この記事では必要な情報を詳しく解説します。

OpenAI Chat Completions APIを使うと、開発者はOpenAIの言語モデルをアプリケーションやサービスに組み込めます。メッセージの連続から応答を生成し、会話、質問応答、コンテンツ生成、テキスト分析などのタスクに対応します。

Chat Completionsは引き続きサポートされています。新規プロジェクトでは、OpenAIはResponses APIを推奨しています。このガイドではChat Completionsに焦点を当て、メッセージ形式、リクエストパラメータ、対応SDKでの利用方法を解説します。

テキストのプロンプトを受け取る従来のCompletionsエンドポイント（/v1/completions）とは異なり、Chat Completionsは構造化されたメッセージのリストを受け取ります。各メッセージにはdeveloper、user、assistantなどのロールがあり、モデルが指示や会話の文脈を解釈するのに役立ちます。対応するロールとコンテンツタイプは、選択したモデルによって異なります。

開発者はAPIを使用して、次のようなさまざまなAI搭載機能を構築できます。

• 会話型アプリケーション： ユーザーメッセージに応答するAIチャットボット、バーチャルアシスタント、カスタマーサポートシステムを作成します。

• コンテンツ生成： 記事、商品説明、メール、要約などの文章コンテンツを生成します。

• テキスト分析： テキストを分類し、情報を抽出し、感情を分析し、文書内の要点を特定します。

• コーディング支援： コードスニペットを生成し、プログラミングの概念を説明し、開発者によるエラーのトラブルシューティングを支援します。

• 言語処理： さまざまな言語のテキストを翻訳、書き換え、簡略化、校正します。

このAPIは、言語モデルを既存のソフトウェアに柔軟に接続する手段を提供します。開発者は独自の言語モデルを構築・ホスティングすることなく、AIが生成した応答をアプリケーションに組み込めます。

Chat Completions APIは、リクエストとレスポンスのワークフローに従います。アプリケーションは、モデル識別子とメッセージのリストを含むリクエストをAPIエンドポイントに送信します。選択したモデルが入力を処理し、生成した応答を返します。

基本的なワークフローは、次の手順で構成されます。

1. 会話を準備する： アプリケーションはユーザーの入力を収集し、メッセージのリストに整理します。コンテキストを提供するために、以前の会話メッセージを含めることもできます。

2. APIリクエストを送信する： アプリケーションは、選択したモデルとメッセージリストを含むPOSTリクエストをhttps://api.openai.com/v1/chat/completionsに送信します。リクエストではAuthorization: Bearer <API_KEY>ヘッダーを使用します。Python SDKのclient.chat.completions.create()メソッドが、このリクエスト形式と認証を処理します。

3. 入力を処理する： モデルはメッセージを解釈し、その役割と内容を考慮して、指定されたコンテキストとパラメータに基づく応答を生成します。

4. 応答を受け取る： ストリーミングなしのリクエストでは、生成された補完とメタデータを含むJSON応答が返されます。ストリーミングを有効にすると、APIはサーバー送信イベント（SSE）の連続データを送信し、アプリケーションは到着した順に処理します。

5. 出力を表示または処理する： アプリケーションは生成されたメッセージを抽出し、ユーザーに表示するか、別のアプリケーションコンポーネントに渡します。

このワークフローは、OpenAI Chat Completions APIのリクエストと応答のモデルに基づいています。

Chat Completions APIを効果的に使用するには、主要なリクエストパラメータと、それらがモデルの動作に与える影響を理解する必要があります。

modelパラメータは、どの言語モデルがリクエストを処理するかを指定します。モデルごとに、機能、応答速度、推論性能、料金が異なる場合があります。

開発者は、タスクの複雑さ、期待する応答品質、レイテンシの要件、予算に応じてモデルを選択する必要があります。

messagesパラメータには、会話メッセージの配列を指定します。通常、各メッセージにはroleフィールドとcontentフィールドが含まれます。

一般的な役割は次のとおりです。

モデルがサポートする指示用の役割を選択してください。同じ指示に対してsystemメッセージとdeveloperメッセージの両方を送信する必要はありません。会話のターンをまたいでコンテキストを維持するには、各リクエストに関連する会話履歴を含めます。互換プロバイダーではサポートする役割が異なる場合があるため、連携を調整する際は各プロバイダーのモデルドキュメントに従ってください。

対応するモデルと構成では、temperatureでサンプリングのランダム性を制御します。APIリファレンスでは、範囲は0から2、デフォルト値は1と定義されています。カスタム値を設定する前に、選択したモデルがこのパラメータをサポートしているか確認してください。

• 低いtemperature：より焦点が絞られ、予測しやすい応答を生成するため、分類、情報抽出、構造化されたタスクに適しています。

• 高いtemperature：生成テキストのばらつきが大きくなり、ブレインストーミングや創作に役立つ場合があります。

一部の推論構成では、temperatureまたはtop_pのカスタム値を受け付けません。そのような構成では、これらのサンプリングパラメータを省略し、代わりに推論の労力や出力上限など、サポートされている制御項目を使用してください。

対応している場合、top_pは核サンプリングによってtokenの選択を制御します。候補tokenを選ぶ際に使用する累積確率のしきい値を設定します。

たとえば、値が0.1の場合、モデルは累積確率の高い順に上位10%に含まれるtokenを考慮します。一般に、値を低くすると出力はより絞り込まれ、値を高くするとばらつきが大きくなります。

OpenAIは、temperatureとtop_pを同時に変更するのではなく、どちらか一方を調整することを推奨しています。

max_completion_tokensパラメータは、該当する場合は推論tokenを含め、モデルが1回の応答で生成できるtokenの最大数を設定します。

適切な上限を設定すると、開発者は出力の長さを制御し、token消費量を管理できます。モデルが応答を完了する前にこの上限に達した場合、補完はlengthの終了理由で終わることがあります。

streamパラメータは、APIが生成された応答を一度に返すか、生成に合わせて段階的に返すかを決定します。

• false：生成が完了した後に、完全な応答を返します。

• true：サーバー送信イベント（SSE）を通じて、応答データをアプリケーションにストリーミングします。

ストリーミングは、出力全体を待つよりも、応答が徐々に表示されるほうが便利なチャットインターフェースやアプリケーションで役立ちます。

response_formatパラメータは、対応モデルでの出力形式を選択します。デフォルトはテキストです。typeをjson_objectに設定するとJSONモードが有効になり、有効なJSONが生成されますが、特定のスキーマは強制されません。メッセージにはJSONを返すよう指示を含めてください。

フィールドとデータ型を予測可能にするには、対応モデルでtype: "json_schema"とstrict: trueを指定した、JSON Schemaベースの構造化出力を使用します。strictモードで使用できるのは、JSON Schemaでサポートされているサブセットのみです。結果を処理する前に、拒否応答や途中で切れた応答がないか確認してください。設定の詳細は構造化出力ガイドを参照してください。

tool_choiceパラメータは、モデルがChat Completionsを通じたツール呼び出しに対応している場合に、ツールの選択を制御します。対応状況はモデルと推論設定の両方に依存します。一部の新しいモデルでは、ツールを使用するためにResponses APIが必要です。リクエストにツールを追加する前に、これらの要件を確認してください。

一般的な設定は次のとおりです。

• none：モデルがツールを呼び出せないようにします。

• auto：利用可能なツールを呼び出すかどうかをモデルが判断できるようにします。

• required：モデルに1つ以上のツールの呼び出しを必須にします。

この機能は関数呼び出しに対応しており、アプリケーションでモデルが生成した判断を外部関数、データベース、サービスに接続できます。リクエストされた関数を実行し、その結果をモデルに返す責任はアプリケーション側にあります。

パラメータの定義とモデル互換性の要件については、Chat Completions APIリファレンスを参照してください。以下のPythonの例では、ツールを使わない基本的なテキストリクエストを使用します。

開発者はHTTPリクエストまたは公式SDKを通じてChat Completions APIにアクセスできます。以下の例では、Pythonを使用して会話形式のリクエストを送信し、生成された応答を取得します。

ステップ1：APIキーを取得する

OpenAI APIプラットフォームでAPIキーを作成し、アカウントが選択したモデルにアクセスでき、十分なAPIクレジットまたは請求枠があることを確認してください。キーはアプリケーションのソースコードではなく、環境変数に保存します。macOSまたはLinuxでは、次を実行します。

YOUR_API_KEYを自身のキーに置き換えてください。Windowsでは、同じOPENAI_API_KEY変数をシェルまたはシステム環境変数に設定します。

ステップ2：OpenAI Python SDKをインストールする

pipを使用して公式Pythonライブラリをインストールします。

ステップ3：APIクライアントを初期化する

SDKをインポートし、クライアントを初期化します。OpenAI()は、ステップ1で設定したOPENAI_API_KEY環境変数を自動的に読み取ります。

ステップ4：チャット補完リクエストを送信する

モデルとメッセージのリストを指定してclient.chat.completions.create()を呼び出します。この例では、gpt-6-astraを低い推論労力で使用し、生成上限を合計4,096トークンに設定しています。このモデルをアカウントで利用できない場合は、Chat Completionsに対応したモデルを選び、そのドキュメントに合わせてパラメータを調整してください。

この例では、

• modelは、応答の生成に使用する言語モデルを指定します。

• messagesは、指示とユーザー入力を提供します。

• reasoning_effortは、このパラメータに対応するモデルの推論労力を設定します。

• max_completion_tokensは、推論トークンを含む生成トークン数の上限を設定します。表示されるテキスト量が特定の量になることを保証するものではありません。

• response.choices[0].message.contentは、アシスタントの応答を取得します。

APIレスポンスを処理する

この非ストリーミングリクエストでは、APIは補完結果とリクエストのメタデータを含むJSONを返します。Python SDKはこれをChatCompletionオブジェクトとして解析するため、例ではresponse.choices[0].message.contentのように属性を通じてフィールドにアクセスしています。

主なレスポンスフィールドは次のとおりです。

finish_reasonフィールドは、生成がどのように終了したかを開発者が把握するのに役立ちます。一般的な値にはstop、length、tool_callsがあります。

開発者はusageフィールドを確認して、入力および出力のtoken消費量を監視することもできます。これはAPIコストの見積もりや、アプリケーションでの利用を最適化する際に役立ちます。

この例では、基本的なテキストレスポンスを示しています。ストリーミング、構造化出力、ツールを追加する場合は、選択したモデルとエンドポイントに合わせてリクエストとレスポンス処理のロジックを更新してください。

OpenAI Chat Completions APIの代替を検討している開発者向けに、Kimi APIはOpenAI互換のAPI形式を通じてMoonshot AIの大規模言語モデルを利用できるようにしています。

KimiはChat Completions、Responses、Messagesの各インターフェースを提供しています。以下の例では、上で紹介したSDKのワークフローを再利用できるよう、OpenAI互換のChat Completionsエンドポイントを使用します。Kimi APIキーを設定し、KimiのベースURLを指定して、対応モデルを選択してください。モデルパラメータ、メッセージロール、ツールのサポートについては、Kimiの公式ドキュメントに従ってください。

ステップ1：Kimi APIキーを取得する

Kimi API platformに登録し、開発者コンソールでAPIキーを作成します。初めてリクエストを送信する前に、残高、モデルへのアクセス権、アカウントのレート制限を確認してください。

Kimiのキーは別の環境変数に保存します。macOSまたはLinuxでは、次を実行します。

YOUR_KIMI_API_KEYを自身のKimiキーに置き換えてください。Windowsでは、同じKIMI_API_KEY変数を環境変数に設定します。

ステップ2：OpenAI Python SDKをインストールする

SDKがまだインストールされていない場合は、次を実行します。

ステップ3：Kimi APIクライアントを設定する

KimiのベースURLとステップ1で設定したKIMI_API_KEY変数を使用して、別のkimi_clientを作成します。os.environでキーを読み取ることで、環境変数が存在しない場合はすぐにエラーとして確認できます。

ステップ4：Chat Completionsリクエストを送信する

Kimiクライアントで同じSDKメソッドを使用します。このリクエストではkimi-k3を選択し、指示にはKimiでサポートされているsystemロールを使用して、非ストリーミングのテキストレスポンスを返します。

• 用途に応じたモデルの選択肢： Kimi K3.1 Proは、複雑な推論、長期的なコーディング、ナレッジワークをサポートします。Highspeedバリアントは、同じモデル機能のまま、より高速に出力します。上の例ではKimi K3を使用しています。利用可能なモデルと移行に関するガイダンスは、最新のモデル一覧で確認してください。

• OpenAI APIとの互換性： OpenAI Chat Completions形式に慣れた開発者は、Kimiモデルの統合時に、同様のリクエスト構造と対応SDKのワークフローを再利用できます。

• 複数ターンの会話： 開発者はメッセージ履歴を渡すことで、コンテキストを踏まえた会話、バーチャルアシスタント、インタラクティブなアプリケーションを実現できます。

• ストリーミングと関数呼び出し： APIはストリーミングレスポンスとツール呼び出しワークフローをサポートしており、よりインタラクティブなアプリケーションを構築し、モデルを外部関数と連携させることができます。

• マルチモーダル入力： 対応するKimiモデルは、モデルの機能に応じて、テキスト、画像、動画などの異なる入力形式を処理できます。

Chat Completions APIを使用する際、開発者は認証、API設定、モデルの可用性、リクエスト制限に関するエラーに遭遇することがあります。こうしたよくある問題を理解することで、原因を特定し、統合をスムーズに動作させやすくなります。

• APIキーが無効または未設定： APIキーが正しくない、期限切れ、失効している、または適切に設定されていない場合、HTTP 401などの認証エラーが発生することがあります。キーが有効であること、環境変数が正しく読み込まれていること、リクエストに適切な認証情報が含まれていることを確認してください。

• APIのベースURLが誤っている： 誤ったエンドポイントに送信したリクエストでは、404などのエラーや接続失敗が返されることがあります。ベースURLがAPIプロバイダーのドキュメントと一致していること、リクエストで正しいエンドポイントパスを使用していることを確認してください。OpenAIと互換プロバイダーを切り替える場合は、ベースURLも忘れずに更新してください。

• モデルIDが無効または利用不可： 指定したモデル名が正しくない、アカウントで利用できない、または選択したエンドポイントでサポートされていない場合、リクエストは失敗することがあります。プロバイダーのモデルドキュメントを確認し、モデルIDがAPIアカウントで利用可能なものと一致していることを確認してください。

• コンテキスト長の超過：入力メッセージと生成出力の合計がモデルのコンテキストウィンドウを超えると、APIがリクエストを拒否する場合があります。入力を短くするか、不要な会話履歴を削除するか、以前のメッセージを要約してから再度リクエストを送信してください。

• 出力の切り詰め：レスポンスがmax_completion_tokensの上限に達すると、要求した内容が完了する前に生成が停止することがあります。対応している場合はtoken上限を増やすか、長文生成タスクをより小さなリクエストに分割してください。また、choices[].finish_reasonを確認すると、length制限によってレスポンスが終了したかどうかを確認できます。

• レート制限または割り当て超過：OpenAIでは、HTTP 429はリクエスト数またはtoken数のレート制限、支出上限、その他の利用制限を示す場合があります。再試行する前に、エラーの種類とコードを確認してください。一時的なレート制限の場合は、リクエスト頻度を下げ、Retry-Afterが指定されている場合はそれに従うか、指数バックオフを使用してください。

エラーがクレジットの枯渇、請求上限、または支出上限を示している場合は、アカウントの残高と請求設定を確認してください。繰り返し再試行してもアクセスは復旧しません。Kimiまたは別の互換プロバイダーを使用している場合は、ステータスコードや割り当てのルールが異なる可能性があるため、そのプロバイダーのエラーコードに関するドキュメントを参照してください。

より効率的にデバッグするには、リクエストパラメータを変更する前に、APIから返されたHTTPステータスコードとエラーメッセージを確認してください。これらの情報は、認証の問題、設定エラー、利用制限を見分けるのに役立ちます。

Chat Completions APIは、幅広いアプリケーションシナリオに対応できます。構造化されたメッセージ形式とカスタマイズ可能な生成パラメータにより、シンプルなテキストベースの機能から、より複雑なAIワークフローまで利用できます。

• AIチャットボットとバーチャルアシスタント：開発者はAPIを使って、Webサイト、モバイルアプリケーション、カスタマーサービスプラットフォーム向けの会話型アシスタントを構築できます。以前のメッセージを後続のリクエストに渡すことで、アプリケーションは会話の文脈を維持し、より適切な応答を提供できます。

• コンテンツ作成と文章編集：APIは、ユーザーの指示に基づいてテキストを生成・変換できます。アプリケーションでは、ブログ記事の下書き、マーケティングコピーの作成、長文コンテンツの要約、段落の書き換え、対象読者や目的に応じた文体の調整に利用できます。

• テキスト分類と情報抽出：企業は、大量のテキストを処理するワークフローにAPIを組み込めます。たとえば、顧客フィードバックの分類、感情の特定、メッセージからの重要情報の抽出、非構造化コンテンツの事前定義済みカテゴリへの整理が可能です。

• コーディングアシスタント：APIは、コードの生成、プログラミング概念の説明、解決策の提案、エラーの特定支援を通じて、ソフトウェア開発ツールを支援できます。アプリケーションでは、function callingを通じてモデルを外部の開発ツールに接続することもできます。

• AIを活用した業務ワークフロー：開発者はAPIを業務アプリケーションに組み込み、言語に関する反復作業を自動化できます。たとえば、顧客からの問い合わせ処理、レポート生成、文書からの情報抽出、事前定義された指示に基づく回答の作成などがあります。

OpenAI Chat Completions APIを利用すると、開発者は会話型AIをアプリケーションに実用的な形で導入し、より便利なユーザー体験を提供できます。適切なモデルを選び、そのパラメータを理解し、APIレスポンスを慎重に処理することで、アプリケーションの性能は大きく変わります。ただし、AIを活用したソリューションを構築する際、開発者が単一のプロバイダーに頼る必要はありません。別の選択肢を検討したい場合は、Kimi APIを試して、OpenAI互換の構成が開発ニーズに適しているか確認してください。