OpenAI 互換の Responses API を使用して Qwen モデルを呼び出します。このトピックでは、入出力パラメーターについて説明し、呼び出し例を示します。
OpenAI Chat Completions API に対する利点:- 組み込みツール:Web 検索、Web スクレイピング、コードインタープリター、Text-to-Image、Image-to-Image、ナレッジベース検索などの組み込みツールを使用して、複雑なタスクでより良い結果を得ることができます。詳細については、「ツール呼び出し」をご参照ください。
- より柔軟な入力:直接的な文字列入力とチャット形式のメッセージ配列の両方をサポートします。
- 簡素化されたコンテキスト管理:最後のレスポンスから
previous_response_idを渡すことで、メッセージ履歴配列を手動で構築する必要がなくなります。 - 便利なコンテキストキャッシュ:リクエストヘッダーに
x-dashscope-session-cache: enable(デフォルト値:disable) を追加して、サーバー側での対話コンテキストの自動キャッシュを有効にします。これにより、コードの変更を必要とせずに、マルチターン対話の推論レイテンシとコストを削減できます。詳細については、「セッションキャッシュ」をご参照ください。
互換性と制限事項
この API は、開発者の移行コストを削減するために OpenAI と互換性がありますが、パラメーター、機能、および動作が異なります。
基本原則:このドキュメントに明示的に記載されているパラメーターのみが処理されます。記載されていない OpenAI パラメーターはすべて無視されます。
以下の主な違いは、迅速な適応に役立ちます:
- サポートされていないパラメーター:この API は、非同期実行パラメーター
backgroundなど、一部の OpenAI API パラメーターをサポートしていません。API は現在、同期呼び出しのみをサポートしています。 - 推論労力制御:
reasoning.effortパラメーターを使用して、モデルの推論労力を制御します。使用方法の詳細については、このパラメーターの説明をご参照ください。
シンガポール
SDK 呼び出し設定の base_url は https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1 です。
HTTP リクエストエンドポイント:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
China (Beijing)
SDK 呼び出し設定の base_url:https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
HTTP リクエストエンドポイント:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses
米国 (バージニア)
SDK 呼び出し設定 base_url:https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
HTTP リクエストエンドポイント:POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/responses
ドイツ (フランクフルト)
SDK 呼び出し設定 base_url:https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
HTTP リクエストエンドポイント:POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/responses
中国 (香港)
SDK 呼び出し設定 base_url:https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
HTTP リクエストエンドポイント:POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/responses
日本 (東京)
SDK 呼び出し設定 base_url:https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
HTTP リクエストエンドポイント:POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
{WorkspaceId} を実際の ワークスペース ID に置き換えてください。
重要Alibaba Cloud Model Studio は、中国 (北京)、シンガポール、および中国 (香港) リージョン向けにワークスペース固有のドメインをリリースしました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。新しいドメインへの移行を推奨します:
- 中国 (北京):
https://dashscope.aliyuncs.comからhttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.comへ - シンガポール:
https://dashscope-intl.aliyuncs.comからhttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.comへ - 中国 (香港):
https://cn-hongkong.dashscope.aliyuncs.comからhttps://{WorkspaceId}.cn-hongkong.maas.aliyuncs.comへ
{WorkspaceId} は、Alibaba Cloud Model Studio コンソールの [ワークスペース詳細] ページで確認できるワークスペース ID です。既存のドメインは引き続き完全に機能します。
重要OpenAI 互換の Responses API のレガシー URL パス /api/v2/apps/protocols/compatible-mode/v1/responses は間もなく非推奨になります。できるだけ早く新しいパス /compatible-mode/v1/responses に移行してください。
リクエストボディmodel 使用するモデルの ID。 サポートされているモデル
重要上記リスト外のAlibaba Cloud Model Studio直接提供テキスト生成モデルは基本的な互換機能のみをサポートします。Agent機能(組み込みツールなど)は制限されます。 input モデルへの入力。以下のフォーマットがサポートされています:
配列要素のタイプ EasyInputMessage メッセージの作成者の プロパティ role メッセージの作成者のロール。有効な値: content メッセージのコンテンツ。入力がプレーンテキストの場合は
コンテンツ配列の項目 type コンテンツタイプを指定します。有効な値は text テキストコンテンツ。 image_url URL または Base64 エンコードされたデータをサポートします。 file_url ファイルの公開 URL。 PDF のページ数の上限は type
ResponseOutputMessage モデルの出力メッセージ。対話を続けるには、以前のレスポンスの プロパティ type
id 以前のレスポンスからの出力メッセージの一意の識別子。 role
status メッセージステータス。有効な値: content コンテンツの配列。要素は プロパティ type
text レスポンステキスト。 annotations アノテーション情報。 関数呼び出し モデルが外部ツールを呼び出すことを決定したときに生成される構造化された命令。 プロパティ type
id 以前のレスポンスからの関数呼び出しの一意の識別子。 name ツール関数の名前。 arguments ツール呼び出しの引数 (JSON 文字列形式)。 call_id ツール呼び出しの識別子。これはモデルによって返される status ステータス。有効な値: 関数呼び出しの出力 ツール呼び出しの出力。メッセージリストでは、このオブジェクトはリクエストの失敗を防ぐために、対応する プロパティ type
id 関数呼び出しの出力の一意の識別子。 call_id ツール呼び出し識別子は、モデルによって返される output ツール関数の実行結果。 status ステータス。有効な値: Reasoning モデルの推論プロセス。以前のレスポンスの プロパティ type
id 以前のレスポンスからの推論コンテンツの一意の識別子。 summary 推論のまとめコンテンツ。 プロパティ type
text まとめテキスト。 status ステータス。有効な値: Web Search Call Web 検索呼び出しオブジェクト。以前のレスポンスの出力から web_search_call アイテムを入力に渡すことで、マルチターン対話で検索結果のコンテキストを提供できます。 プロパティ type 常に id 以前のレスポンスからの検索呼び出しの一意の識別子。 status 検索ステータス。有効な値: action 検索アクションの詳細。 プロパティ type 検索タイプ。常に queries 検索クエリのリスト。各要素は文字列です。 sources 検索結果ソースのリスト。 プロパティ type ソースタイプ。常に url ソース URL。 instructions コンテキストの冒頭にシステム命令として挿入されます。 previous_response_id 前のレスポンスの一意の ID。レスポンスの conversation 現在のレスポンスが属する対話 (「Conversations API」をご参照ください)。対話の履歴は自動的にコンテキストとして含まれます。このリクエストの入力と出力は、完了時に会話に追加されます。 stream ストリーミング出力を有効にします。 store このセッションで生成されたモデルのレスポンスを保存するかどうかを指定します。
tools モデルがレスポンスを生成する際に呼び出すことができるツールの配列。組み込みツールとカスタム
プロパティ Web 検索 最新の情報をインターネットで検索します。関連ドキュメント:Web 検索 プロパティ type
例: Web ページにアクセスし、コンテンツを抽出します。 プロパティ type
例: サンドボックス環境でコードを実行して、データ分析などのタスクを実行します。 プロパティ type
例: テキストの説明に基づいて画像を検索します。関連ドキュメント:テキストによる画像検索 プロパティ type
例: 入力画像に基づいて類似または関連する画像を検索します。入力には画像の URL を含める必要があります。関連ドキュメント:Image-to-Image 検索 プロパティ type
例: 指定されたナレッジベースを検索して知識を取得します。関連ドキュメント:ナレッジ取得 プロパティ type
vector_store_ids 検索するナレッジベースの ID。現在、提供できるナレッジベース ID は 1 つだけです。 例: Model Context Protocol (MCP) を介して外部サービスを呼び出します。関連ドキュメント:MCP プロパティ type
server_protocol MCP サービスとの通信プロトコル、例: server_label MCP サービスを識別するために使用されるラベル。 server_description サービスの説明。モデルがその機能を理解し、いつ使用するかを判断するのに役立ちます。 server_url MCP サービスエンドポイントの URL。 headers リクエストヘッダー。認証 (例: 例: モデルが開発者定義の関数を呼び出すことを許可します。モデルがツールを呼び出す必要があると判断した場合、レスポンスはタイプ プロパティ type
name ツールの名前。文字、数字、アンダースコア ( description ツールの説明。モデルがいつ、どのように呼び出すかを決定するのに役立ちます。 parameters ツールのパラメーター定義。有効な JSON Schema オブジェクトである必要があります。
例: tool_choice モデルがツールを選択して呼び出す方法を制御します。このパラメーターは、文字列モードとオブジェクトモードの 2 つのフォーマットをサポートします。 文字列モード
モデルが選択して呼び出すツールを特定のセットに制限します。 プロパティ mode
tools モデルが呼び出すことを許可されているツール定義のリスト。 type ツール設定のタイプ。 temperature サンプリング温度。生成されるテキストの多様性を制御します。 値が高いほど出力はよりランダムで多様になり、値が低いほどより集中的で決定論的になります。 値の範囲:[0, 2)
top_p Top-p サンプリングの確率のしきい値。生成されるテキストの多様性を制御します。 値が高いほど出力はよりランダムで多様になり、値が低いほどより集中的で決定論的になります。 値の範囲:(0, 1.0]
enable_thinking 推論モードを有効または無効にします。有効にすると、モデルは応答する前に推論ステップを実行します。推論プロセスは、タイプ 有効な値:
さまざまなモデルのデフォルト値については、「サポートされているモデル」をご参照ください。
reasoning モデルの推論労力を制御します。モデルは返信する前に推論ステップを実行し、推論プロセスはタイプ プロパティ effort 7 つの増分レベルをサポートします:
ocr_options OCR 組み込みタスクパラメーター。 PDF ファイルを解析する場合、サポートされるページ数は
max_output_tokens
最小値は 16 です。モデルの出力がこの値を超えると、生成は早期に停止し、ステータスは | 基本的な呼び出しストリーミング出力マルチターン対話組み込みツール関数呼び出しドキュメント理解セッションキャッシュキャッシュヒットメカニズム:セッションキャッシュはシステムプロンプトのプレフィックスでマッチングします。後続のリクエストのシステムプロンプトがキャッシュされたコンテンツと同一である場合、キャッシュにヒットします。ユーザープロンプトを変更してもキャッシュヒットには影響しません。キャッシュがヒットしたかどうかを確認するには、レスポンスの |
レスポンスオブジェクト (非ストリーミング出力)id このレスポンスの一意の識別子、UUID。この ID は 7 日間有効で、 created_at このリクエストの UNIX タイムスタンプ (秒単位)。 object オブジェクトタイプ。常に status レスポンス生成のステータス。有効な値:
model レスポンスの生成に使用されたモデルの ID。 output モデルによって生成された出力アイテムの配列。配列内の要素のタイプと順序は、モデルのレスポンスによって異なります。 配列要素のプロパティ type 出力アイテムのタイプ。有効な値:
id 出力アイテムの一意の識別子。すべてのタイプの出力アイテムにこのフィールドが含まれています。 role メッセージのロールは常に status 出力アイテムのステータス。有効な値: name ツールまたは関数の名前。このパラメーターは、
arguments ツール呼び出しのパラメーター (JSON 文字列形式)。このパラメーターは、
call_id 関数呼び出しの一意の ID。このパラメーターは、 content メッセージコンテンツの配列。このパラメーターは、 配列要素のプロパティ type コンテンツタイプ。値は text モデルによって生成されたテキストコンテンツ。 annotations テキストアノテーションの配列。通常は空の配列です。 summary 推論のまとめの配列。このフィールドは、 action 検索アクションに関する情報。このパラメーターは、 プロパティ query 検索クエリのキーワード。 type 検索タイプ。値は常に sources 検索ソースのリスト。各要素には code モデルによって生成および実行されたコード。これは、 outputs コード実行の出力配列。これは、 container_id コードインタープリターのコンテナ識別子。このパラメーターは、 goal Web ページから抽出する情報の説明。このパラメーターは、 output ツール呼び出しの出力。出力は文字列です。
urls 抽出された Web ページの URL のリスト。このパラメーターは、 server_label MCP サービスのラベル。これは、 queries ナレッジベース取得のためのクエリのリスト。このパラメーターは、 results ナレッジベースからの検索結果の配列。このパラメーターは、 配列要素のプロパティ file_id 一致したドキュメントのファイル ID。 filename 一致したドキュメントのファイル名。 score 一致の関連性スコア。値の範囲は 0 から 1 です。値が大きいほど関連性が高くなります。 text 一致したドキュメントからのコンテンツスニペット。 usage このリクエストのトークン消費量に関する情報。 プロパティ input_tokens 入力のトークン数。追加の注意事項 output_tokens モデルの出力のトークン数。 total_tokens 消費された合計トークン数は、 input_tokens_details 入力トークンの詳細な分類。 プロパティ cached_tokens キャッシュにヒットしたトークン数。詳細については、「コンテキストキャッシュ」をご参照ください。 output_tokens_details 出力トークンの詳細な内訳。 プロパティ reasoning_tokens 推論トークンの数。 x_details リクエストの請求明細の配列。これは、トップレベルの プロパティ input_tokens 入力のトークン数。追加の注意事項 output_tokens モデルの出力のトークン数。 total_tokens 消費された合計トークン数は、 x_billing_type 値は image_tokens 画像入力のトークン数。このフィールドは、入力に画像が含まれている場合に返され、 input_tokens_details 入力トークンの詳細な内訳。このフィールドはマルチモーダル入力に対して返されます。現在、 プロパティ text_tokens テキスト入力のトークン数。 image_tokens 画像入力のトークン数。 output_tokens_details 出力トークンの詳細な内訳。このフィールドには、トップレベルの プロパティ reasoning_tokens 推論プロセスのトークン数。 text_tokens テキスト出力のトークン数。このフィールドはマルチモーダル入力に対して返されます。 plugins 組み込みツール呼び出しの統計。このフィールドは、 プロパティ web_search Web 検索呼び出しの統計。 プロパティ count このレスポンスで Web 検索が呼び出された回数。 prompt_tokens_details 入力トークンのキャッシュ詳細。このフィールドは、セッションキャッシュが有効になっている場合に返されます。入力に画像が含まれているがキャッシュミスになった場合、空のオブジェクトを返すことがあります。 プロパティ cached_tokens キャッシュにヒットしたトークン数。 cache_creation_input_tokens このリクエストで新しいキャッシュを作成するために使用されたトークン数。 cache_creation キャッシュ作成に関する詳細。 プロパティ ephemeral_5m_input_tokens 新しい 5 分間のエフェメラルキャッシュを作成するために使用されたトークン数。 cache_type キャッシュタイプ。値は x_tools ツール使用状況に関する統計。これには、各組み込みツールが呼び出された回数が含まれます。 例: error モデルがレスポンスを生成できなかった場合にエラーオブジェクトが返されます。それ以外の場合、値は tools リクエストからの tool_choice リクエストの | |
レスポンスチャンクオブジェクト (ストリーミング出力)ストリーミング出力は一連の JSON オブジェクトを返します。各オブジェクトには、イベントタイプを指定する type イベントタイプ識別子。考えられる値は次のとおりです:
sequence_number イベントのシーケンス番号。0 から始まり、イベントごとにインクリメントされます。この番号を使用して、イベントを正しい順序で処理します。 response
item 出力アイテムオブジェクト。 プロパティ id 出力アイテムの一意の識別子 (例: type 出力アイテムのタイプ。考えられる値: role メッセージのロール。常に status 生成ステータス。 content メッセージコンテンツの配列。 part コンテンツパートオブジェクト。 プロパティ type コンテンツパートのタイプ。常に text テキストコンテンツ。これは annotations テキストアノテーションの配列。通常は空の配列です。 logprobs トークンのログ確率。このフィールドは現在、常に delta 増分テキストセグメント。このフィールドは text 完全なテキストコンテンツ。このフィールドは item_id 出力アイテムの一意の識別子。この ID を使用して、同じアイテムに属するイベントを関連付けます。 output_index
content_index
| |
よくある質問
Q:マルチターン対話のコンテキストを渡すにはどうすればよいですか?A:新しい対話リクエストを行う際に、モデルの前回の成功したレスポンスから得られる id を previous_response_id パラメーターとして渡します。
A:公式の OpenAI SDK は、OpenAI プロトコルで定義された追加のフィールドを出力することがあります。当社のサービスはこれらのフィールドをサポートしていないため、通常は null になります。このトピックで説明されているフィールドにのみ注目してください。