Skip to main content
OpenAI相容-Responses

建立響應

通過相容 OpenAI 格式的 Responses API 呼叫千問模型,查看輸入輸出參數說明及調用樣本。

相較於OpenAI Chat Completions API 的優勢:
  • 內建工具:內建連網搜尋、網頁抓取、代碼解譯器、文搜圖、圖搜圖、知識庫搜尋等工具,可在處理複雜任務時獲得更優效果,詳情參考工具調用
  • 更靈活的輸入:支援直接傳入字串作為模型輸入,也相容 Chat 格式的訊息數組。
  • 簡化上下文管理:通過傳遞上一輪響應的 previous_response_id,無需手動構建完整的訊息歷史數組。
  • 便捷的上下文緩衝:只需在要求標頭中添加 x-dashscope-session-cache: enable(預設值為 disable),服務端即可自動緩衝對話上下文,無需改動業務代碼即可降低多輪對話的推理延遲與成本,詳情參考Session 緩衝

相容性說明與限制

本 API 在介面設計上相容 OpenAI,以降低開發人員遷移成本,但在參數、功能和具體行為上存在差異。 核心原則:請求將僅處理本文檔明確列出的參數,任何未提及的 OpenAI 參數都會被忽略。 以下是幾個關鍵的差異點,以協助您快速適配:
  • 部分參數不支援:不支援部分 OpenAI Responses API 參數,例如非同步執行參數background(當前僅支援同步調用)等。
  • 思考強度控制:通過 reasoning.effort 參數控制模型的思考強度,具體用法請參考相應參數的說明。
  • 新加坡
  • 华北2(北京)
  • 美國(維吉尼亞)
  • 德國(法蘭克福)
  • 中國香港
  • 日本(東京)
SDK 調用配置的base_urlhttps://{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
阿里雲百鍊為華北2(北京)、新加坡、中國香港地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:
  • 華北2(北京)地區:從 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} 為您的業務空間 ID,可在阿里雲百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。
OpenAI相容-Responses API 的舊版URL路徑 /api/v2/apps/protocols/compatible-mode/v1/responses 即將停止維護,請儘快遷移至新版路徑 /compatible-mode/v1/responses

請求體

model string (必選)模型名稱。
qwen3.8-maxqwen3.8-flashqwen3.7-maxqwen3.7-max-2026-05-20qwen3.7-max-2026-06-08qwen3.7-max-2026-05-17qwen3.7-max-previewqwen3-maxqwen3-max-2026-01-23qwen3.7-plusqwen3.7-plus-2026-05-26qwen3.6-plusqwen3.6-plus-2026-04-02qwen3.5-plusqwen3.5-plus-2026-04-20qwen3.5-plus-2026-02-15qwen3.7-flashqwen3.7-flash-2026-07-15qwen3.6-flashqwen3.6-flash-2026-04-16qwen3.5-flashqwen3.5-flash-2026-02-23qwen3.8-2.4t-a95bqwen3.8-27bqwen3.6-35b-a3bqwen3.5-397b-a17bqwen3.5-122b-a10bqwen3.5-27bqwen3.5-35b-a3bdeepseek-v4-prodeepseek-v4-pro-0813deepseek-v4-flashdeepseek-v4-flash-0731glm-5.2kimi-k3
非列表中阿里雲百鍊直供文本生成模型僅支援基礎相容能力,Agent 能力(内建工具等)受限。
input string 或 array (必選)模型輸入,支援以下格式:
  • string:純文字,如 "你好"
  • array:訊息數組,按對話順序排列。
EasyInputMessage object通過 role 區分訊息類型,通過content傳遞訊息內容。
role string (必選)訊息角色,可選值:userassistantsystemdevelopercontent string 或 array (必選)訊息內容。若輸入為純文字,則為 string 類型;若輸入為結構化內容數組,則為 array 類型。role 為 system/developer 時,array 元素類型為 input_text;role 為 user 時,array 元素類型為 input_textinput_imageinput_file;role 為 assistant 時,array 元素類型為 output_text
當前 Responses API 暫不支援傳入的視訊或語音,您可以通過Chat Completions APIDashScope API傳入。
type string (必選)可選值:input_text(文本輸入)、input_image(圖片輸入,僅 user 角色)、input_file(檔案輸入,僅 user 角色,支援 PDF 和圖片)、output_text(助手回複,僅 assistant 角色)。text string常值內容。當 type 為 input_textoutput_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 支援此類型。
type string (可選)固定為 message
ResponseOutputMessage object (可選)模型的輸出訊息對象。可直接將上一輪響應的 output 中的 message 項傳回 input,用於多輪對話情境。與 EasyInputMessage 的區別在於它攜帶了完整的輸出結構(含 id、status 和結構化 content)。
type string (必選)固定為 messageid string (必選)輸出訊息的唯一標識,來自上一輪響應。role string (必選)固定為 assistantstatus string (必選)訊息狀態,可選值:in_progresscompletedincompletecontent array (必選)內容數組,元素為 output_text 類型對象。
type string (必選)固定為 output_texttext string (必選)回複文本。annotations array (可選)標註資訊。
Function Call object (可選)模型決定調用外部工具時產生的結構化指令。
type string (必選)固定為 function_callid string (可選)Function Call 的唯一標識,來自上一輪響應。name string (必選)工具函數名稱。arguments string (必選)工具調用參數,JSON 字串格式。call_id string (必選)工具調用的標識符,需與模型返回的 call_id 一致。status string (可選)狀態,可選值:in_progresscompletedincomplete
Function Call Output object (可選)工具調用的輸出結果。在訊息列表中必須緊跟對應的 function_call 訊息,否則會報錯。
type string (必選)固定為 function_call_outputid string (可選)Function Call Output 的唯一標識。call_id string (必選)工具調用的標識符,需與模型返回的 call_id 一致。output string (必選)工具函數的執行結果。status string (可選)狀態,可選值:in_progresscompletedincomplete
Reasoning object (可選)模型的思考內容。可直接將上一輪響應的 output 中的 reasoning 項傳回 input,用於在多輪對話中傳遞思考內容。
type string (必選)固定為 reasoningid string (必選)思考內容的唯一標識,來自上一輪響應。summary array (必選)思考摘要內容。
type string (必選)固定為 summary_texttext string (必選)摘要文本。
status string (可選)狀態,可選值:in_progresscompletedincomplete
Web Search Call object (可選)搜尋調用對象。可直接將上一輪響應的 output 中的 web_search_call 項傳回 input,用於在多輪對話中傳遞搜尋結果上下文。
type string (必選)固定為 web_search_callid string (必選)搜尋調用的唯一標識,來自上一輪響應。status string (必選)搜尋狀態,可選值:in_progresssearchingcompletedfailedaction object (必選)搜尋資訊。僅支援 search 類型。
type string (必選)搜尋類型,固定為 searchqueries array (可選)搜尋查詢詞列表,元素類型為 string。sources array (可選)搜尋結果來源列表。
type string (必選)來源類型,固定為 urlurl string (必選)來源 URL。
instructionsstring (可選)作為系統指令插入到內容相關的起始位置。使用 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是否儲存本次會話產生的模型響應。
  • false:不儲存,對話內容不能被 previous_response_id 和後續 API 使用。
  • true:儲存,當前模型響應可被 previous_response_id 和後續 API 使用。
tools array (可選)模型在產生響應時可調用的工具數組。支援內建工具和自訂 function 工具,可混合使用。
為了獲得最佳回複效果,建議同時開啟 code_interpreterweb_searchweb_extractor 工具。
web_search連網搜尋工具,允許模型搜尋互連網上的最新資訊。相關文檔:連網搜尋
type string (必選)固定為web_search使用樣本:[{"type": "web_search"}]
web_extractor網頁抽取工具,允許模型訪問並提取網頁內容。當前必須配合web_search工具一起使用。qwen3-maxqwen3-max-2026-01-23需要同時開啟思考模式。相關文檔:網頁抓取
type string (必選)固定為web_extractor使用樣本:[{"type": "web_search"}, {"type": "web_extractor"}]
code_interpreter代碼解譯器工具,允許模型執行代碼並返回結果,支援資料分析。qwen3.8-maxqwen3.8-flashqwen3-maxqwen3-max-2026-01-23qwen3.7-maxqwen3.7-max-2026-05-20qwen3.7-max-2026-06-08需要同時開啟思考模式。相關文檔:代碼解譯器
type string (必選)固定為code_interpreter使用樣本:[{"type": "code_interpreter"}]
web_search_image根據文本描述搜尋圖片。相關文檔:文搜圖
type string (必選)固定為web_search_image使用樣本:[{"type": "web_search_image"}]
image_search根據圖片搜尋相似或相關圖片,輸入中需要包含圖片的URL。相關文檔:圖搜圖
type string (必選)固定為image_search使用樣本:[{"type": "image_search"}]
file_search在已上傳或關聯的知識庫中搜尋。相關文檔:知識檢索
type string (必選)固定為file_searchvector_store_ids array(必選)要檢索的知識庫 ID。當前僅支援傳入一個知識庫 ID使用樣本:[{"type": "file_search", "vector_store_ids": ["your_knowledge_base_id"]}]
MCP調用通過 MCP(Model Context Protocol)調用外部服務,相關文檔:MCP
type string (必選)固定為mcpserver_protocol string (必選)與 MCP 服務的通訊協定,如 "sse"server_label string (必選)服務標籤,用於標識該 MCP 服務。server_description string (可選)服務描述,協助模型理解其功能與適用情境。server_url string (必選)MCP 服務端點的 URL。headers object (可選)要求標頭,用於攜帶身分識別驗證等資訊,如 Authorization使用樣本:
mcp_tool = {
    "type": "mcp",
    "server_protocol": "sse",
    "server_label": "amap-maps",
    "server_description": "高德地圖MCP Server現已覆蓋15大核心介面,提供全情境覆蓋的地理資訊服務,包括產生專屬地圖、導航到目的地、打車、地理編碼、逆地理編碼、IP定位、天氣查詢、騎行路徑規劃、步行路徑規劃、駕車路徑規劃、公交路徑規劃、距離測量、關鍵詞搜尋、周邊搜尋、詳情搜尋等。",
    "server_url": "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/mcps/amap-maps/sse",
    "headers": {
        "Authorization": "Bearer <your-mcp-server-token>"
    }
}
自訂工具function自訂函數工具,允許模型調用您定義的函數。當模型判斷需要調用工具時,響應會返回 function_call 類型的輸出。相關文檔:Function Calling
type string (必選)必須設定為functionnamestring(必選)工具名稱。僅允許字母、數字、底線(_)和短劃線(-),最長 64 個 Token。descriptionstring(必選)工具描述資訊,協助模型判斷何時以及如何調用該工具。parameters object (可選)工具的參數描述,需要是一個合法的 JSON Schema。若parameters參數為空白,表示該工具沒有入參(如時間查詢工具)。
為提高工具調用的準確性,建議傳入 parameters
使用樣本:
[{
  "type": "function",
  "name": "get_weather",
  "description": "擷取指定城市的天氣資訊",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名稱"
      }
    },
    "required": ["city"]
  }
}]
tool_choice string or object (可選)預設值為 auto控制模型如何選擇和調用工具。此參數支援兩種賦值格式:字串模式對象模式字串模式
  • auto:模型自動決定是否調用工具。
  • none:禁止模型調用任何工具。
  • required:強制模型調用工具(僅當 tools 列表中只有一個工具時可用)。
對象模式為模型設定可用的工具範圍,僅限在預定義的工具列表中進行選擇和調用。
mode string (必選)
  • auto:模型自動決定是否調用工具。
  • required:強制模型調用工具(僅當 tools 列表中只有一個工具時可用)。
tools array(必選)一個包含工具定義的列表,模型將被允許調用這些工具。
[
  { "type": "function", "name": "get_weather" }
]
typestring (必選)允許的工具配置類型,固定為 allowed_tools
temperaturefloat(可選)採樣溫度,控制模型產生文本的多樣性。temperature越高,產生的文本更多樣,反之,產生的文本更確定。取值範圍: [0, 2)temperature與top_p均可以控制產生文本的多樣性,建議只設定其中一個值。更多說明,請參見概述top_pfloat(可選)核採樣的機率閾值,控制模型產生文本的多樣性。top_p越高,產生的文本更多樣。反之,產生的文本更確定。取值範圍:(0,1.0]temperature與top_p均可以控制產生文本的多樣性,建議只設定其中一個值。更多說明,請參見概述enable_thinking boolean (可選)是否開啟思考模式。開啟後,模型會在回複前進行思考,思考內容將通過 reasoning 類型的輸出項返回。開啟思考模式時,建議開啟內建工具,以在處理複雜任務時獲得最佳的模型效果。可選值:
  • true:開啟
  • false:不開啟
不同模型的預設值:支援的模型
該參數非OpenAI標準參數。Python SDK 通過 extra_body={"enable_thinking": True} 傳遞;Node.js SDK 和 curl 直接使用 enable_thinking: true 作為頂層參數。建議使用 reasoning.effort 替代,enable_thinking 後續將不再支援。
reasoning object (可選)控制模型的思考強度。模型會在回複前進行思考,思考內容將通過 reasoning 類型的輸出項返回。
effort string (可選):思考強度檔位,預設值為 xhigh支援 noneminimallowmediumhighxhighmax 共 7 個遞增檔位。降低該值可加快響應速度並減少推理 Token 的消耗。
华北2(北京)新加坡支援xhighmax檔位。
reasoning.effort 的優先順序高於 enable_thinking,建議優先使用 reasoning.effortenable_thinking 後續將不再支援。
ocr_options object (可選)OCR 定製任務參數。僅適用於 qwen3.5-ocr 模型。通過此參數可調用內建的 OCR 任務(如資訊抽取、文字定位等),定製任務結果通過響應中的 ocr_result 欄位返回。
該參數非 OpenAI 標準參數。Python SDK 通過 extra_body={"ocr_options": {...}} 傳遞;Node.js SDK 和 curl 直接使用 ocr_options 作為頂層參數。
max_output_tokens integer(可選)
  • Qwen3.8系列:模型回複內容和思維鏈內容之和的最大Token數。
  • 其餘模型:模型回複內容的最大Token數。
最小值為16,模型輸出超過此值時產生將提前停止,狀態為incomplete
  • 基礎調用
  • 流式輸出
  • 多輪對話
  • 調用內建工具
  • 自訂 Function Call
  • 文檔理解
  • Session 緩衝
Python
import os
from openai import OpenAI

client = OpenAI(
    # If environment variable is not set, replace with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 請將{WorkspaceId}替換為真實的業務空間ID,各地區URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

response = client.responses.create(
    model="qwen3.8-max",
    input="What can you do?"
)

# Get model response
print(response.output_text)

Response 響應對象(非流式輸出)

id string本次響應的唯一識別碼,為 UUID 格式的字串,有效期間為7天。可用於 previous_response_id 參數以建立多輪對話。created_at integer本次請求的 Unix 時間戳記(秒)。object string物件類型,固定為 responsestatus string響應產生的狀態。枚舉值:
  • completed:產生完成
  • failed:產生失敗
  • in_progress:產生中
  • cancelled:已取消
  • queued:請求排隊中
  • incomplete:產生不完整
model string用於產生響應的模型 ID。output array模型產生的輸出項數組。數組中的元素類型和順序取決於模型的響應。
type string輸出項類型。枚舉值:
  • message:訊息類型,包含模型最終產生的回複內容。
  • reasoning:推理類型,設定 reasoning.effort(非 none)或開啟思考模式時返回。推理 Token 會被計入 output_tokens_details.reasoning_tokens 中,按推理 Token 計費。
  • function_call:函數調用類型,使用自訂 function 工具時返回。需要處理函數調用並返回結果。
  • web_search_call:搜尋調用類型,使用 web_search 工具時返回。
  • code_interpreter_call:代碼執行類型,使用 code_interpreter 工具時返回。
  • web_extractor_call:網頁抽取類型,使用 web_extractor 工具時返回。需要配合 web_search 工具一起使用。
  • web_search_image_call:文搜圖調用類型,使用 web_search_image 工具時返回。包含搜尋到的圖片列表。
  • image_search_call:圖搜圖調用類型,使用 image_search 工具時返回。包含搜尋到的相似圖片列表。
  • mcp_call:MCP 調用類型,使用 mcp 工具時返回。包含 MCP 服務的調用結果。
  • file_search_call:知識庫搜尋調用類型,使用 file_search 工具時返回。包含知識庫的檢索查詢和結果。
id string輸出項的唯一識別碼。所有類型的輸出項都包含此欄位。role string訊息角色,固定為 assistant。僅當 typemessage 時存在。status string輸出項狀態。可選值:completed(完成)、in_progress(產生中)。當 type 不為reasoning時存在。name string工具或函數名稱。當 typefunction_callweb_search_image_callimage_search_callmcp_call 時存在。對於 web_search_image_callimage_search_call,值分別固定為 "web_search_image""image_search"對於 mcp_call,值為 MCP 服務中被調用的具體函數名(如 amap-maps-maps_geo)。arguments string工具調用的參數,JSON 字串格式。當 typefunction_callweb_search_image_callimage_search_callmcp_call 時存在。使用前需要通過 JSON.parse() 解析。不同工具類型的 arguments 內容:
  • web_search_image_call{"queries": ["搜尋關鍵詞1", "搜尋關鍵詞2"]},其中 queries 為模型根據使用者輸入自動產生的搜尋關鍵詞列表。
  • image_search_call{"img_idx": 0, "bbox": [0, 0, 1000, 1000]},其中 img_idx 為輸入圖片的索引(從 0 開始),bbox 為搜尋地區的邊界框座標 [x1, y1, x2, y2],座標範圍 0-1000。
  • function_call:按使用者定義的函數參數 schema 產生的參數對象。
  • mcp_call:MCP 服務中被調用函數的參數對象。
call_id string函數調用的唯一識別碼。僅當 typefunction_call 時存在。在返回函數調用結果時,需要通過此 ID 關聯請求與響應。content array訊息內容數組。僅當 typemessage 時存在。
type string內容類型,固定為 output_texttext string模型產生的常值內容。annotations array文本注釋數組。通常為空白數組。
summary array推理摘要數組。僅當 typereasoning 時存在。每個元素包含 type(值為 summary_text)和 text(摘要文本)欄位。action object搜尋動作資訊。僅當 typeweb_search_call 時存在。
query string搜尋查詢關鍵詞。type string搜尋類型,固定為 searchsources array搜尋來源列表。每個元素包含 typeurl欄位。
code string模型產生並執行的代碼。僅當 typecode_interpreter_call 時存在。outputs array代碼執行輸出數組。僅當 typecode_interpreter_call 時存在。每個元素包含 type(值為 logs)和 logs(代碼執行日誌)欄位。container_id string代碼解譯器容器標識符。僅當 typecode_interpreter_call 時存在。用於關聯同一會話中的多次代碼執行。goal string抽取目標描述,說明需要從網頁中提取哪些資訊。僅當 typeweb_extractor_call 時存在。output string工具調用的輸出結果,字串格式。
  • typeweb_extractor_call 時為網頁抽取的內容摘要
  • typeweb_search_image_callimage_search_call 時為 JSON 字串,包含圖片搜尋結果數組,每個元素包含 title(圖片標題)、url(圖片 URL)和 index(序號)欄位
  • typemcp_call 時為 MCP 服務返回的 JSON 字串結果。
urls array被抽取的網頁 URL 列表。僅當 typeweb_extractor_call 時存在。server_label stringMCP 服務標籤。僅當 typemcp_call 時存在。標識本次調用所使用的 MCP 服務。queries array知識庫檢索使用的查詢列表。僅當 typefile_search_call 時存在。數組元素為字串,表示模型產生的搜尋查詢詞。results array知識庫檢索結果數組。僅當 typefile_search_call 時存在。
file_id string匹配文檔的檔案 ID。filename string匹配文檔的檔案名稱。score float匹配相關度評分,取值範圍 0-1,值越大表示相關度越高。text string匹配到的文檔內容片段。
usage 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 數。詳情請參見上下文緩衝
output_tokens_details object輸出 Token 的細粒度分類。
reasoning_tokens integer思考過程 Token 數。
x_details array本次請求的計費明細數組。比頂級 usage 欄位提供更細粒度的多模態 Token 拆分。
input_tokens integer輸入的 Token 數。補充說明output_tokens integer模型輸出的 Token 數。total_tokens integer消耗的總 Token 數,為 input_tokens 與 output_tokens 的總和。x_billing_type string固定為response_apiimage_tokens integer映像輸入的 Token 數。包含映像輸入時返回,等同於 input_tokens_details.image_tokensinput_tokens_details object輸入 Token 的細粒度分類。多模態輸入時返回,目前僅區分 text_tokensimage_tokens,不返回視頻/音頻 Token 拆分。
text_tokens integer文本輸入的 Token 數。image_tokens integer映像輸入的 Token 數。
output_tokens_details object輸出 Token 的細粒度分類。比頂級 output_tokens_detailstext_tokens 欄位(多模態輸入時返回)。
reasoning_tokens integer思考過程 Token 數。text_tokens integer文本輸出的 Token 數。多模態輸入時返回。
plugins object內建工具調用統計。使用內建工具(如 web_search)時返回,與頂級 x_tools 欄位內容相同。
web_search object連網搜尋調用統計。
count integer本次響應中連網搜尋的調用次數。
input_tokens_details object輸入 Token 的緩衝詳情。啟用 Session 緩衝後返回;含映像輸入但未命中緩衝時可能返回Null 物件。
cached_tokens integer命中緩衝的 Token 數。cache_creation_input_tokens integer本次請求新建立緩衝的 Token 數。cache_creation object緩衝建立詳情。
ephemeral_5m_input_tokens integer5 分鐘臨時緩衝新建立的 Token 數。
cache_type string緩衝類型,固定為ephemeral
x_tools object工具使用統計資訊。當使用內建工具時,包含各工具的調用次數。樣本:{"web_search": {"count": 1}}
error object當模型產生響應失敗時返回的錯誤對象。成功時為 nulltools array回應要求中 tools 參數的完整內容,結構與請求體中的 tools 參數相同。tool_choice string回應要求中 tool_choice 參數的值,枚舉值為 autononerequired
{
    "created_at": 1771165900.0,
    "id": "f75c28fb-4064-48ed-90da-4d2cc4362xxx",
    "model": "qwen3.8-max",
    "object": "response",
    "output": [
        {
            "content": [
                {
                    "annotations": [],
                    "text": "Hello! I am Qwen3.5, a large language model developed by Alibaba Cloud with knowledge up to 2026, designed to assist you with complex reasoning, creative tasks, and multilingual conversations.",
                    "type": "output_text"
                }
            ],
            "id": "msg_89ad23e6-f128-4d4c-b7a1-a786e7880xxx",
            "role": "assistant",
            "status": "completed",
            "type": "message"
        }
    ],
    "parallel_tool_calls": false,
    "status": "completed",
    "tool_choice": "auto",
    "tools": [],
    "usage": {
        "input_tokens": 57,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 44,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 101,
        "x_details": [
            {
                "input_tokens": 57,
                "output_tokens": 44,
                "total_tokens": 101,
                "x_billing_type": "response_api"
            }
        ]
    }
}

Response 響應 chunk 對象(流式輸出)

流式輸出返回一系列 JSON 對象。每個對象包含 type 欄位標識事件類型,sequence_number 欄位標識事件順序。response.completed 事件標誌著串流的結束。type string事件類型標識符。枚舉值:
  • response.created:響應建立時觸發,狀態為 queued
  • response.in_progress:響應開始處理時觸發,狀態變為 in_progress
  • response.output_item.added:新的輸出項(如 message、web_extractor_call)被添加到 output 數組時觸發。當 item.typeweb_extractor_call 時,表示網頁抽取工具調用開始。
  • response.content_part.added:輸出項的 content 數組中新增內容塊時觸發。
  • response.output_text.delta:增量文本產生時觸發,多次觸發,delta 欄位包含新增文本片段。
  • response.output_text.done:文本產生完成時觸發,text 欄位包含完整文本。
  • response.content_part.done:內容塊完成時觸發,part 對象包含完整內容塊。
  • response.output_item.done:輸出項產生完成時觸發,item 對象包含完整輸出項。當 item.typeweb_extractor_call 時,表示網頁抽取工具調用完成。
  • response.reasoning_text.delta:(開啟思考模式時)推理摘要增量文本,delta 欄位包含新增摘要片段。
  • response.reasoning_text.done:(開啟思考模式時)推理摘要完成,text 欄位包含完整摘要。
  • response.custom_tool_call_input.delta:自訂工具增量文本
  • response.custom_tool_call_input.done:自訂工具完成
  • response.web_search_call.in_progress / searching / completed:(使用 web_search 工具時)搜尋狀態變化事件。
  • response.code_interpreter_call.in_progress / interpreting / completed:(使用 code_interpreter 工具時)代碼執行狀態變化事件。
  • 注意:使用 web_extractor 工具時,沒有專門的事件類型標識符。網頁抽取工具調用通過通用的 response.output_item.addedresponse.output_item.done 事件傳遞,通過 item.type 欄位(值為 web_extractor_call)來識別。
  • response.incomplete:響應因 max_output_tokens等限制而提前結束
  • response.mcp_call_arguments.delta / response.mcp_call_arguments.done:(使用 mcp 工具時)MCP 調用參數的增量和完成事件。
  • response.mcp_call.in_progress:MCP 服務調用中。
  • response.mcp_call.completed:(使用 mcp 工具時)MCP 服務調用完成。
  • response.file_search_call.in_progress / searching / completed:(使用 file_search 工具時)知識庫搜尋狀態變化事件。
  • 注意:使用 web_search_imageimage_search 工具時,沒有專門的中間狀態事件。工具調用通過 response.output_item.added(調用開始)和 response.output_item.done(調用完成)事件傳遞。
  • response.completed:響應產生完成時觸發,response 對象包含完整響應(含 usage)。此事件標誌串流結束。
sequence_number integer事件序號,從 0 開始遞增。用於確保用戶端按正確順序處理事件。response object響應對象。出現在 response.createdresponse.in_progressresponse.completed 事件中。在 response.completed 事件中包含完整的響應資料(包括 outputusage),其結構與非流式響應的 Response 對象一致。item object輸出項對象。出現在 response.output_item.addedresponse.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 事件中為 completedcontent array訊息內容數組。在 added 事件中為空白數組 [],在 done 事件中包含完整的內容塊對象(結構與 part 對象相同)。
part object內容塊對象。出現在 response.content_part.addedresponse.content_part.done 事件中。
type string內容塊類型,固定為 output_texttext string常值內容。在 added 事件中為空白字串,在 done 事件中為完整文本。annotations array文本注釋數組。通常為空白數組。logprobs object | nullToken 的對數機率資訊。當前固定返回 null
delta string增量常值內容。出現在 response.output_text.delta 事件中,包含本次新增的文本片段。用戶端應將所有 delta 拼接以獲得完整文本。text string完整常值內容。出現在 response.output_text.done 事件中,包含該內容塊的完整文本,可用於校正 delta 拼接結果。item_id string輸出項的唯一識別碼。用於關聯同一輸出項的相關事件。output_index integer輸出項在 output 數組中的索引位置。content_index integer內容塊在 content 數組中的索引位置。
// response.created - 響應建立
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","created_at":1769082930,"object":"response","status":"queued",...},"sequence_number":0,"type":"response.created"}

// response.in_progress - 響應進行中
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","status":"in_progress",...},"sequence_number":1,"type":"response.in_progress"}

// response.output_item.added - 新增輸出項
{"item":{"id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","content":[],"role":"assistant","status":"in_progress","type":"message"},"output_index":0,"sequence_number":2,"type":"response.output_item.added"}

// response.content_part.added - 新增內容塊
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","output_index":0,"part":{"annotations":[],"text":"","type":"output_text","logprobs":null},"sequence_number":3,"type":"response.content_part.added"}

// response.output_text.delta - 增量文本(多次觸發)
{"content_index":0,"delta":"人工智慧","item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":4,"type":"response.output_text.delta"}
{"content_index":0,"delta":"(Artificial Intelligence,","item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":6,"type":"response.output_text.delta"}

// response.output_text.done - 文本完成
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":53,"text":"人工智慧(Artificial Intelligence,簡稱 AI)是指由電腦系統類比人類智能行為的技術和科學...","type":"response.output_text.done"}

// response.content_part.done - 內容塊完成
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","output_index":0,"part":{"annotations":[],"text":"...完整文本...","type":"output_text","logprobs":null},"sequence_number":54,"type":"response.content_part.done"}

// response.output_item.done - 輸出項完成
{"item":{"id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","content":[{"annotations":[],"text":"...完整文本...","type":"output_text","logprobs":null}],"role":"assistant","status":"completed","type":"message"},"output_index":0,"sequence_number":55,"type":"response.output_item.done"}

// response.completed - 響應完成(包含完整響應和 usage)
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","created_at":1769082930,"model":"qwen3.7-max","object":"response","output":[...],"status":"completed","usage":{"input_tokens":37,"output_tokens":243,"total_tokens":280,...}},"sequence_number":56,"type":"response.completed"}

常見問題

Q:如何傳遞多輪對話的上下文? A:在發起新一輪對話請求時,請將上一輪模型響應成功返回的id作為 previous_response_id 參數傳入。 Q:為什麼響應樣本中的某些欄位未在本文說明? A:如果使用OpenAI的官方SDK,它可能會根據其自身的模型結構輸出一些額外的欄位(通常為null)。這些欄位是OpenAI協議本身定義的,我們的服務當前不支援,所以它們為空白值。只需關注本文檔中描述的欄位即可。