Skip to main content

建立響應

通過相容 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_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。
阿里雲百鍊為華北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-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.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.1-flash-1017、deepseek-v4-pro、deepseek-v4-pro-0813、deepseek-v4-flash-0731、glm-5.2、kimi-k3
非列表中阿里雲百鍊直供文本生成模型僅支援基礎相容能力,Agent 能力(内建工具等)受限。
input string 或 array (必選)模型輸入,支援以下格式:
  • string:純文字,如 "你好"。
  • 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傳入。
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 檔案(最大 100 MB)和圖片檔案(最大 20 MB)。目前僅 qwen3.5-ocr 支援此類型。PDF 的頁數上限取決於 ocr_options 中的 task:設定為 document_parsing 時最大 50 頁;未設定 task 或設定為其他任務時,最大 10 頁。
type string (可選)固定為 message。
ResponseOutputMessage 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 (可選)標註資訊。
Function Call 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。
Function Call Output 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。
Reasoning object (可選)模型的思考內容。可直接將上一輪響應的 output 中的 reasoning 項傳回 input,用於在多輪對話中傳遞思考內容。
type string (必選)固定為 reasoning。id string (必選)思考內容的唯一標識,來自上一輪響應。summary array (必選)思考摘要內容。
type string (必選)固定為 summary_text。text string (必選)摘要文本。
status string (可選)狀態,可選值:in_progress、completed、incomplete。
Web Search Call 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。
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 工具,可混合使用。deepseek-v4.1-flash-1017 支援 web_search、web_extractor 和 code_interpreter 三項內建工具。
為了獲得最佳回複效果,建議同時開啟 code_interpreter、web_search 和 web_extractor 工具。
web_search連網搜尋工具,允許模型搜尋互連網上的最新資訊。相關文檔:連網搜尋
type string (必選)固定為web_search。使用樣本:[{"type": "web_search"}]
web_extractor網頁抽取工具,允許模型訪問並提取網頁內容。當前必須配合web_search工具一起使用。相關文檔:網頁抓取
type string (必選)固定為web_extractor。使用樣本:[{"type": "web_search"}, {"type": "web_extractor"}]
code_interpreter代碼解譯器工具,允許模型執行代碼並返回結果,支援資料分析。qwen3.8-max、qwen3.8-flash、qwen3.7-max、qwen3.7-max-2026-05-20、qwen3.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_search。vector_store_ids array(必選)要檢索的知識庫 ID。當前僅支援傳入一個知識庫 ID。使用樣本:[{"type": "file_search", "vector_store_ids": ["your_knowledge_base_id"]}]
MCP調用通過 MCP(Model Context Protocol)調用外部服務,相關文檔:MCP
type string (必選)固定為mcp。server_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 (必選)必須設定為function。namestring(必選)工具名稱。僅允許字母、數字、底線(_)和短劃線(-),最長 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。支援 none、minimal、low、medium、high、xhigh、max 共 7 個遞增檔位。降低該值可加快響應速度並減少推理 Token 的消耗。
僅华北2(北京)和新加坡支援xhigh、max檔位。
reasoning.effort 的優先順序高於 enable_thinking,建議優先使用 reasoning.effort,enable_thinking 後續將不再支援。
ocr_options object (可選)OCR 定製任務參數。僅適用於 qwen3.5-ocr 模型。通過此參數可調用內建的 OCR 任務(如資訊抽取、文字定位等),定製任務結果通過響應中的 ocr_result 欄位返回。解析 PDF 檔案時,task 的取值決定支援的頁數:設定為 document_parsing 時最大 50 頁;未設定 task 或設定為其他任務時,最大 10 頁。
該參數非 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物件類型,固定為 response。status 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。僅當 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 內容:
  • 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函數調用的唯一識別碼。僅當 type 為 function_call 時存在。在返回函數調用結果時,需要通過此 ID 關聯請求與響應。content array訊息內容數組。僅當 type 為 message 時存在。
type string內容類型,固定為 output_text。text string模型產生的常值內容。annotations array文本注釋數組。通常為空白數組。
summary array推理摘要數組。僅當 type 為 reasoning 時存在。每個元素包含 type(值為 summary_text)和 text(摘要文本)欄位。action object搜尋動作資訊。僅當 type 為 web_search_call 時存在。
query string搜尋查詢關鍵詞。type string搜尋類型,固定為 search。sources array搜尋來源列表。每個元素包含 type和 url欄位。
code 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工具調用的輸出結果,字串格式。
  • 當 type 為 web_extractor_call 時為網頁抽取的內容摘要
  • 當 type 為 web_search_image_call 或 image_search_call 時為 JSON 字串,包含圖片搜尋結果數組,每個元素包含 title(圖片標題)、url(圖片 URL)和 index(序號)欄位
  • 當 type 為 mcp_call 時為 MCP 服務返回的 JSON 字串結果。
urls 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匹配到的文檔內容片段。
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_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 數。
output_tokens_details object輸出 Token 的細粒度分類。比頂級 output_tokens_details 多 text_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當模型產生響應失敗時返回的錯誤對象。成功時為 null。tools array回應要求中 tools 參數的完整內容,結構與請求體中的 tools 參數相同。tool_choice string回應要求中 tool_choice 參數的值,枚舉值為 auto、none、required。
{
    "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.type 為 web_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.type 為 web_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.added 和 response.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_image 和 image_search 工具時,沒有專門的中間狀態事件。工具調用通過 response.output_item.added(調用開始)和 response.output_item.done(調用完成)事件傳遞。
  • response.completed:響應產生完成時觸發,response 對象包含完整響應(含 usage)。此事件標誌串流結束。
sequence_number 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 對象相同)。
part object內容塊對象。出現在 response.content_part.added 和 response.content_part.done 事件中。
type string內容塊類型,固定為 output_text。text 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協議本身定義的,我們的服務當前不支援,所以它們為空白值。只需關注本文檔中描述的欄位即可。
建立響應 - Alibaba Cloud Model Studio