Alibaba Cloud Model Studio：OpenAI Responses API 參考

model string （必選）

模型名稱。

input string 或 array （必選）

模型輸入，支援以下格式：

• string：純文字輸入，如 "你好"。

• array：訊息數組，按對話順序排列。

instructions string （可選）

作為系統指令插入到內容相關的起始位置。使用 previous_response_id 時，上一輪指定的 instructions 不會傳入本輪上下文。

previous_response_id string （可選）

上一個響應的唯一 ID，當前響應id有效期間為7天。使用此參數可建立多輪對話，服務端會自動檢索並組合該輪次的輸入與輸出作為上下文。當同時提供 input 訊息數組和 previous_response_id 時，input 中的新訊息會追加到歷史上下文之後。不能與 conversation 同時使用。

conversation string （可選）

當前響應所屬的會話。會話中的歷史項會自動作為上下文傳入本次請求，本次請求的輸入和輸出也會在響應完成後自動添加到會話中。不能與 previous_response_id 同時使用。

stream boolean （可選）預設值為 false

是否開啟流式輸出。設定為 true 時，模型響應資料將即時資料流式返回給用戶端。

tools array （可選）

模型在產生響應時可調用的工具數組。支援內建工具和自訂 function 工具，可混合使用。

為了獲得最佳回複效果，建議同時開啟 code_interpreter、web_search 和 web_extractor 工具。

mcp_tool = {
    "type": "mcp",
    "server_protocol": "sse",
    "server_label": "amap-maps",
    "server_description": "高德地圖MCP Server現已覆蓋15大核心介面，提供全情境覆蓋的地理資訊服務，包括產生專屬地圖、導航到目的地、打車、地理編碼、逆地理編碼、IP定位、天氣查詢、騎行路徑規劃、步行路徑規劃、駕車路徑規劃、公交路徑規劃、距離測量、關鍵詞搜尋、周邊搜尋、詳情搜尋等。",
    "server_url": "https://dashscope.aliyuncs.com/api/v1/mcps/amap-maps/sse",
    "headers": {
        "Authorization": "Bearer <your-mcp-server-token>"
    }
}

[{
  "type": "function",
  "name": "get_weather",
  "description": "擷取指定城市的天氣資訊",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名稱"
      }
    },
    "required": ["city"]
  }
}]

tool_choice string or object （可選）預設值為 auto

控制模型如何選擇和調用工具。此參數支援兩種賦值格式：字串模式和對象模式。

[
  { "type": "function", "name": "get_weather" }
]

temperature float （可選）

採樣溫度，控制模型產生文本的多樣性。

temperature越高，產生的文本更多樣，反之，產生的文本更確定。

取值範圍： [0, 2)

temperature與top_p均可以控制產生文本的多樣性，建議只設定其中一個值。更多說明，請參見文本產生模型概述。

top_p float （可選）

核採樣的機率閾值，控制模型產生文本的多樣性。

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 作為頂層參數。

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

模型產生的輸出項數組。數組中的元素類型和順序取決於模型的響應。

usage object

本次請求的 Token 消耗資訊。

error object

當模型產生響應失敗時返回的錯誤對象。成功時為 null。

tools array

回應要求中 tools 參數的完整內容，結構與請求體中的 tools 參數相同。

tool_choice string

回應要求中 tool_choice 參數的值，枚舉值為 auto、none、required。

流式輸出返回一系列 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_summary_text.delta：（開啟思考模式時）推理摘要增量文本，delta 欄位包含新增摘要片段。

• response.reasoning_summary_text.done：（開啟思考模式時）推理摘要完成，text 欄位包含完整摘要。

• 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.mcp_call_arguments.delta / response.mcp_call_arguments.done：（使用 mcp 工具時）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 事件中為完整對象。

part object

內容塊對象。出現在 response.content_part.added 和 response.content_part.done 事件中。

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 數組中的索引位置。

summary_index integer

摘要數組索引。出現在 response.reasoning_summary_text.delta 和 response.reasoning_summary_text.done 事件中。