通過相容 OpenAI 格式的 Responses API 呼叫千問模型,查看輸入輸出參數說明及調用樣本。
相較於OpenAI Chat Completions API 的優勢:
本 API 在介面設計上相容 OpenAI,以降低開發人員遷移成本,但在參數、功能和具體行為上存在差異。
核心原則:請求將僅處理本文檔明確列出的參數,任何未提及的 OpenAI 參數都會被忽略。
以下是幾個關鍵的差異點,以協助您快速適配:
調用時請將
Q:如何傳遞多輪對話的上下文?
A:在發起新一輪對話請求時,請將上一輪模型響應成功返回的
- 內建工具:內建連網搜尋、網頁抓取、代碼解譯器、文搜圖、圖搜圖、知識庫搜尋等工具,可在處理複雜任務時獲得更優效果,詳情參考工具調用。
- 更靈活的輸入:支援直接傳入字串作為模型輸入,也相容 Chat 格式的訊息數組。
- 簡化上下文管理:通過傳遞上一輪響應的
previous_response_id,無需手動構建完整的訊息歷史數組。 - 便捷的上下文緩衝:只需在要求標頭中添加
x-dashscope-session-cache: enable(預設值為 disable),服務端即可自動緩衝對話上下文,無需改動業務代碼即可降低多輪對話的推理延遲與成本,詳情參考Session 緩衝。
相容性說明與限制
本 API 在介面設計上相容 OpenAI,以降低開發人員遷移成本,但在參數、功能和具體行為上存在差異。
核心原則:請求將僅處理本文檔明確列出的參數,任何未提及的 OpenAI 參數都會被忽略。
以下是幾個關鍵的差異點,以協助您快速適配:
- 部分參數不支援:不支援部分 OpenAI Responses API 參數,例如非同步執行參數
background(當前僅支援同步調用)等。 - 思考強度控制:通過
reasoning.effort參數控制模型的思考強度,具體用法請參考相應參數的說明。
- 新加坡
- 华北2(北京)
- 美國(維吉尼亞)
- 德國(法蘭克福)
- 中國香港
- 日本(東京)
SDK 調用配置的
base_url:https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1HTTP 要求地址:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses{WorkspaceId}替換為真實的業務空間ID。
請求體modelstring (必選)模型名稱。
支援的模型 qwen3.8-max、qwen3.8-flash、qwen3.7-max、qwen3.7-max-2026-05-20、qwen3.7-max-2026-06-08、qwen3.7-max-2026-05-17、qwen3.7-max-preview、qwen3-max、qwen3-max-2026-01-23、qwen3.7-plus、qwen3.7-plus-2026-05-26、qwen3.6-plus、qwen3.6-plus-2026-04-02、qwen3.5-plus、qwen3.5-plus-2026-04-20、qwen3.5-plus-2026-02-15、qwen3.7-flash、qwen3.7-flash-2026-07-15、qwen3.6-flash、qwen3.6-flash-2026-04-16、qwen3.5-flash、qwen3.5-flash-2026-02-23、qwen3.8-2.4t-a95b、qwen3.8-27b、qwen3.6-35b-a3b、qwen3.5-397b-a17b、qwen3.5-122b-a10b、qwen3.5-27b、qwen3.5-35b-a3b、deepseek-v4-pro、deepseek-v4-pro-0813、deepseek-v4-flash、deepseek-v4-flash-0731、glm-5.2、kimi-k3string 或 array (必選)模型輸入,支援以下格式:
array 輸入項類型 EasyInputMessage object通過 role 區分訊息類型,通過content傳遞訊息內容。
屬性 role string (必選)訊息角色,可選值:user、assistant、system、developer。content string 或 array (必選)訊息內容。若輸入為純文字,則為 string 類型;若輸入為結構化內容數組,則為 array 類型。role 為 system/developer 時,array 元素類型為 input_text;role 為 user 時,array 元素類型為 input_text、input_image 或 input_file;role 為 assistant 時,array 元素類型為 output_text。當前 Responses API 暫不支援傳入的視訊或語音,您可以通過Chat Completions API或DashScope API傳入。
content 數組元素 type string (必選)可選值:input_text(文本輸入)、input_image(圖片輸入,僅 user 角色)、input_file(檔案輸入,僅 user 角色,支援 PDF 和圖片)、output_text(助手回複,僅 assistant 角色)。text string常值內容。當 type 為 input_text 或 output_text 時必填。image_url string支援 URL 或者 Base 64 編碼,當 type 為 input_image 時必填。Base64 請傳入完整的 Data URI,例如:data:image/png;base64,iVBORw0K...。file_url string檔案的公網 URL。當 type 為 input_file 時必填。支援 PDF 檔案(最大 10 頁、100 MB)和圖片檔案(最大 20 MB)。目前僅 qwen3.5-ocr 支援此類型。string (可選)固定為 message。object (可選)模型的輸出訊息對象。可直接將上一輪響應的 output 中的 message 項傳回 input,用於多輪對話情境。與 EasyInputMessage 的區別在於它攜帶了完整的輸出結構(含 id、status 和結構化 content)。
屬性 type string (必選)固定為 message。id string (必選)輸出訊息的唯一標識,來自上一輪響應。role string (必選)固定為 assistant。status string (必選)訊息狀態,可選值:in_progress、completed、incomplete。content array (必選)內容數組,元素為 output_text 類型對象。
屬性 type string (必選)固定為 output_text。text string (必選)回複文本。annotations array (可選)標註資訊。object (可選)模型決定調用外部工具時產生的結構化指令。
屬性 type string (必選)固定為 function_call。id string (可選)Function Call 的唯一標識,來自上一輪響應。name string (必選)工具函數名稱。arguments string (必選)工具調用參數,JSON 字串格式。call_id string (必選)工具調用的標識符,需與模型返回的 call_id 一致。status string (可選)狀態,可選值:in_progress、completed、incomplete。object (可選)工具調用的輸出結果。在訊息列表中必須緊跟對應的 function_call 訊息,否則會報錯。
屬性 type string (必選)固定為 function_call_output。id string (可選)Function Call Output 的唯一標識。call_id string (必選)工具調用的標識符,需與模型返回的 call_id 一致。output string (必選)工具函數的執行結果。status string (可選)狀態,可選值:in_progress、completed、incomplete。object (可選)模型的思考內容。可直接將上一輪響應的 output 中的 reasoning 項傳回 input,用於在多輪對話中傳遞思考內容。
屬性 type string (必選)固定為 reasoning。id string (必選)思考內容的唯一標識,來自上一輪響應。summary array (必選)思考摘要內容。
屬性 type string (必選)固定為 summary_text。text string (必選)摘要文本。string (可選)狀態,可選值:in_progress、completed、incomplete。object (可選)搜尋調用對象。可直接將上一輪響應的 output 中的 web_search_call 項傳回 input,用於在多輪對話中傳遞搜尋結果上下文。
屬性 type string (必選)固定為 web_search_call。id string (必選)搜尋調用的唯一標識,來自上一輪響應。status string (必選)搜尋狀態,可選值:in_progress、searching、completed、failed。action object (必選)搜尋資訊。僅支援 search 類型。
屬性 type string (必選)搜尋類型,固定為 search。queries array (可選)搜尋查詢詞列表,元素類型為 string。sources array (可選)搜尋結果來源列表。
屬性 type string (必選)來源類型,固定為 url。url string (必選)來源 URL。string (可選)作為系統指令插入到內容相關的起始位置。使用 previous_response_id 時,上一輪指定的 instructions 不會傳入本輪上下文。previous_response_id string (可選)上一個響應的唯一 ID,當前響應id有效期間為7天。使用此參數可建立多輪對話,服務端會自動檢索並組合該輪次的輸入與輸出作為上下文。當同時提供 input 訊息數組和 previous_response_id 時,input 中的新訊息會追加到歷史上下文之後。不能與 conversation 同時使用。conversation string (可選)當前響應所屬的會話(參考Conversations API)。會話中的歷史項會自動作為上下文傳入本次請求,本次請求的輸入和輸出也會在響應完成後自動添加到會話中。不能與 previous_response_id 同時使用。stream boolean (可選)預設值為 false是否開啟流式輸出。設定為 true 時,模型響應資料將即時資料流式返回給用戶端。store boolean (可選)預設值為 true是否儲存本次會話產生的模型響應。
array (可選)模型在產生響應時可調用的工具數組。支援內建工具和自訂 function 工具,可混合使用。為了獲得最佳回複效果,建議同時開啟
屬性 web_search連網搜尋工具,允許模型搜尋互連網上的最新資訊。相關文檔:連網搜尋
屬性 type string (必選)固定為web_search。使用樣本:[{"type": "web_search"}]web_search工具一起使用。qwen3-max、qwen3-max-2026-01-23需要同時開啟思考模式。相關文檔:網頁抓取
屬性 type string (必選)固定為web_extractor。使用樣本:[{"type": "web_search"}, {"type": "web_extractor"}]qwen3.8-max、qwen3.8-flash、qwen3-max、qwen3-max-2026-01-23、qwen3.7-max、qwen3.7-max-2026-05-20、qwen3.7-max-2026-06-08需要同時開啟思考模式。相關文檔:代碼解譯器
屬性 type string (必選)固定為code_interpreter。使用樣本:[{"type": "code_interpreter"}]
屬性 type string (必選)固定為web_search_image。使用樣本:[{"type": "web_search_image"}]
屬性 type string (必選)固定為image_search。使用樣本:[{"type": "image_search"}]
屬性 type string (必選)固定為file_search。vector_store_ids array(必選)要檢索的知識庫 ID。當前僅支援傳入一個知識庫 ID。使用樣本:[{"type": "file_search", "vector_store_ids": ["your_knowledge_base_id"]}]
屬性 type string (必選)固定為mcp。server_protocol string (必選)與 MCP 服務的通訊協定,如 "sse"server_label string (必選)服務標籤,用於標識該 MCP 服務。server_description string (可選)服務描述,協助模型理解其功能與適用情境。server_url string (必選)MCP 服務端點的 URL。headers object (可選)要求標頭,用於攜帶身分識別驗證等資訊,如 Authorization。使用樣本:function_call 類型的輸出。相關文檔:Function Calling
屬性 type string (必選)必須設定為function。namestring(必選)工具名稱。僅允許字母、數字、底線(_)和短劃線(-),最長 64 個 Token。descriptionstring(必選)工具描述資訊,協助模型判斷何時以及如何調用該工具。parameters object (可選)工具的參數描述,需要是一個合法的 JSON Schema。若parameters參數為空白,表示該工具沒有入參(如時間查詢工具)。
為提高工具調用的準確性,建議傳入 使用樣本:string or object (可選)預設值為 auto控制模型如何選擇和調用工具。此參數支援兩種賦值格式:字串模式和對象模式。字串模式
屬性 mode string (必選)
array(必選)一個包含工具定義的列表,模型將被允許調用這些工具。string (必選)允許的工具配置類型,固定為 allowed_tools。float(可選)採樣溫度,控制模型產生文本的多樣性。temperature越高,產生的文本更多樣,反之,產生的文本更確定。取值範圍: [0, 2)temperature與top_p均可以控制產生文本的多樣性,建議只設定其中一個值。更多說明,請參見概述。top_pfloat(可選)核採樣的機率閾值,控制模型產生文本的多樣性。top_p越高,產生的文本更多樣。反之,產生的文本更確定。取值範圍:(0,1.0]temperature與top_p均可以控制產生文本的多樣性,建議只設定其中一個值。更多說明,請參見概述。enable_thinking boolean (可選)是否開啟思考模式。開啟後,模型會在回複前進行思考,思考內容將通過 reasoning 類型的輸出項返回。開啟思考模式時,建議開啟內建工具,以在處理複雜任務時獲得最佳的模型效果。可選值:
該參數非OpenAI標準參數。Python SDK 通過reasoning object (可選)控制模型的思考強度。模型會在回複前進行思考,思考內容將通過 reasoning 類型的輸出項返回。
屬性 effort string (可選):思考強度檔位,預設值為 xhigh。支援 none、minimal、low、medium、high、xhigh、max 共 7 個遞增檔位。降低該值可加快響應速度並減少推理 Token 的消耗。僅华北2(北京)和新加坡支援 ocr_options object (可選)OCR 定製任務參數。僅適用於 qwen3.5-ocr 模型。通過此參數可調用內建的 OCR 任務(如資訊抽取、文字定位等),定製任務結果通過響應中的 ocr_result 欄位返回。該參數非 OpenAI 標準參數。Python SDK 通過max_output_tokens integer(可選)
incomplete。 |
Python |
Response 響應對象(非流式輸出)idstring本次響應的唯一識別碼,為 UUID 格式的字串,有效期間為7天。可用於 previous_response_id 參數以建立多輪對話。created_at integer本次請求的 Unix 時間戳記(秒)。object string物件類型,固定為 response。status string響應產生的狀態。枚舉值:
string用於產生響應的模型 ID。output array模型產生的輸出項數組。數組中的元素類型和順序取決於模型的響應。
數組元素屬性 type string輸出項類型。枚舉值:
string輸出項的唯一識別碼。所有類型的輸出項都包含此欄位。role string訊息角色,固定為 assistant。僅當 type 為 message 時存在。status string輸出項狀態。可選值:completed(完成)、in_progress(產生中)。當 type 不為reasoning時存在。name string工具或函數名稱。當 type 為 function_call、web_search_image_call、image_search_call、mcp_call 時存在。對於 web_search_image_call 和 image_search_call,值分別固定為 "web_search_image" 和 "image_search"。對於 mcp_call,值為 MCP 服務中被調用的具體函數名(如 amap-maps-maps_geo)。arguments string工具調用的參數,JSON 字串格式。當 type 為 function_call、web_search_image_call、image_search_call、mcp_call 時存在。使用前需要通過 JSON.parse() 解析。不同工具類型的 arguments 內容:
string函數調用的唯一識別碼。僅當 type 為 function_call 時存在。在返回函數調用結果時,需要通過此 ID 關聯請求與響應。content array訊息內容數組。僅當 type 為 message 時存在。
數組元素屬性 type string內容類型,固定為 output_text。text string模型產生的常值內容。annotations array文本注釋數組。通常為空白數組。array推理摘要數組。僅當 type 為 reasoning 時存在。每個元素包含 type(值為 summary_text)和 text(摘要文本)欄位。action object搜尋動作資訊。僅當 type 為 web_search_call 時存在。
屬性 query string搜尋查詢關鍵詞。type string搜尋類型,固定為 search。sources array搜尋來源列表。每個元素包含 type和 url欄位。string模型產生並執行的代碼。僅當 type 為 code_interpreter_call 時存在。outputs array代碼執行輸出數組。僅當 type 為 code_interpreter_call 時存在。每個元素包含 type(值為 logs)和 logs(代碼執行日誌)欄位。container_id string代碼解譯器容器標識符。僅當 type 為 code_interpreter_call 時存在。用於關聯同一會話中的多次代碼執行。goal string抽取目標描述,說明需要從網頁中提取哪些資訊。僅當 type 為 web_extractor_call 時存在。output string工具調用的輸出結果,字串格式。
array被抽取的網頁 URL 列表。僅當 type 為 web_extractor_call 時存在。server_label stringMCP 服務標籤。僅當 type 為 mcp_call 時存在。標識本次調用所使用的 MCP 服務。queries array知識庫檢索使用的查詢列表。僅當 type 為 file_search_call 時存在。數組元素為字串,表示模型產生的搜尋查詢詞。results array知識庫檢索結果數組。僅當 type 為 file_search_call 時存在。
數組元素屬性 file_id string匹配文檔的檔案 ID。filename string匹配文檔的檔案名稱。score float匹配相關度評分,取值範圍 0-1,值越大表示相關度越高。text string匹配到的文檔內容片段。object本次請求的 Token 消耗資訊。
屬性 input_tokens integer輸入的 Token 數。補充說明output_tokens integer模型輸出的 Token 數。total_tokens integer消耗的總 Token 數,為 input_tokens 與 output_tokens 的總和。input_tokens_details object輸入 Token 的細粒度分類。
屬性 cached_tokens integer命中緩衝的 Token 數。詳情請參見上下文緩衝。object輸出 Token 的細粒度分類。
屬性 reasoning_tokens integer思考過程 Token 數。array本次請求的計費明細數組。比頂級 usage 欄位提供更細粒度的多模態 Token 拆分。
屬性 input_tokens integer輸入的 Token 數。補充說明output_tokens integer模型輸出的 Token 數。total_tokens integer消耗的總 Token 數,為 input_tokens 與 output_tokens 的總和。x_billing_type string固定為response_api。image_tokens integer映像輸入的 Token 數。包含映像輸入時返回,等同於 input_tokens_details.image_tokens。input_tokens_details object輸入 Token 的細粒度分類。多模態輸入時返回,目前僅區分 text_tokens 與 image_tokens,不返回視頻/音頻 Token 拆分。
屬性 text_tokens integer文本輸入的 Token 數。image_tokens integer映像輸入的 Token 數。object輸出 Token 的細粒度分類。比頂級 output_tokens_details 多 text_tokens 欄位(多模態輸入時返回)。
屬性 reasoning_tokens integer思考過程 Token 數。text_tokens integer文本輸出的 Token 數。多模態輸入時返回。object內建工具調用統計。使用內建工具(如 web_search)時返回,與頂級 x_tools 欄位內容相同。
屬性 web_search object連網搜尋調用統計。
屬性 count integer本次響應中連網搜尋的調用次數。object輸入 Token 的緩衝詳情。啟用 Session 緩衝後返回;含映像輸入但未命中緩衝時可能返回Null 物件。
屬性 cached_tokens integer命中緩衝的 Token 數。cache_creation_input_tokens integer本次請求新建立緩衝的 Token 數。cache_creation object緩衝建立詳情。
屬性 ephemeral_5m_input_tokens integer5 分鐘臨時緩衝新建立的 Token 數。string緩衝類型,固定為ephemeral。object工具使用統計資訊。當使用內建工具時,包含各工具的調用次數。樣本:{"web_search": {"count": 1}}object當模型產生響應失敗時返回的錯誤對象。成功時為 null。tools array回應要求中 tools 參數的完整內容,結構與請求體中的 tools 參數相同。tool_choice string回應要求中 tool_choice 參數的值,枚舉值為 auto、none、required。 |
Response 響應 chunk 對象(流式輸出)流式輸出返回一系列 JSON 對象。每個對象包含type 欄位標識事件類型,sequence_number 欄位標識事件順序。response.completed 事件標誌著串流的結束。type string事件類型標識符。枚舉值:
integer事件序號,從 0 開始遞增。用於確保用戶端按正確順序處理事件。response object響應對象。出現在 response.created、response.in_progress 和 response.completed 事件中。在 response.completed 事件中包含完整的響應資料(包括 output 和 usage),其結構與非流式響應的 Response 對象一致。item object輸出項對象。出現在 response.output_item.added 和 response.output_item.done 事件中。在 added 事件中為初始骨架(content 為空白數組),在 done 事件中為完整對象。
屬性 id string輸出項的唯一識別碼(如 msg_xxx)。type string輸出項類型。枚舉值:message(訊息)、reasoning(推理)、web_search_call(搜尋)、web_search_image_call(文搜圖)、image_search_call(圖搜圖)、mcp_call(MCP 調用)、file_search_call(知識庫搜尋)。role string訊息角色,固定為 assistant。僅當 type 為 message 時存在。status string產生狀態。在 added 事件中為 in_progress,在 done 事件中為 completed。content array訊息內容數組。在 added 事件中為空白數組 [],在 done 事件中包含完整的內容塊對象(結構與 part 對象相同)。object內容塊對象。出現在 response.content_part.added 和 response.content_part.done 事件中。
屬性 type string內容塊類型,固定為 output_text。text string常值內容。在 added 事件中為空白字串,在 done 事件中為完整文本。annotations array文本注釋數組。通常為空白數組。logprobs object | nullToken 的對數機率資訊。當前固定返回 null。string增量常值內容。出現在 response.output_text.delta 事件中,包含本次新增的文本片段。用戶端應將所有 delta 拼接以獲得完整文本。text string完整常值內容。出現在 response.output_text.done 事件中,包含該內容塊的完整文本,可用於校正 delta 拼接結果。item_id string輸出項的唯一識別碼。用於關聯同一輸出項的相關事件。output_index integer輸出項在 output 數組中的索引位置。content_index integer內容塊在 content 數組中的索引位置。 |
常見問題
Q:如何傳遞多輪對話的上下文?
A:在發起新一輪對話請求時,請將上一輪模型響應成功返回的id作為 previous_response_id 參數傳入。
Q:為什麼響應樣本中的某些欄位未在本文說明?
A:如果使用OpenAI的官方SDK,它可能會根據其自身的模型結構輸出一些額外的欄位(通常為null)。這些欄位是OpenAI協議本身定義的,我們的服務當前不支援,所以它們為空白值。只需關注本文檔中描述的欄位即可。