Qwen-Deep-Research API reference-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Request and response parameters for calling the Qwen-Deep-Research model through the DashScope API.

Related documentation: Deep research (Qwen-Deep-Research)

Important

Qwen-Deep-Research is available only in the China (Beijing) region. You must use an API key from the China (Beijing) region.

Note

The model currently supports only the Python DashScope SDK. The Java SDK and the OpenAI-compatible interface are not supported.

DashScope

Before you begin, get an API key and set it as an environment variable. To use the DashScope SDK, you must also install the SDK.

Request body	Python import os import dashscope # Step 1: Get the clarifying question from the model. messages = [{'role': 'user', 'content': 'Research the applications of artificial intelligence in education'}] responses = dashscope.Generation.call( api_key=os.getenv('DASHSCOPE_API_KEY'), model="qwen-deep-research", messages=messages, stream=True ) # Collect the model's clarifying question. step1_content = "" for response in responses: if hasattr(response, 'output') and response.output: message = response.output.get('message', {}) content = message.get('content', '') if content: step1_content += content print(content, end='', flush=True) # Step 2: Start the deep research. messages = [ {'role': 'user', 'content': 'Research the applications of artificial intelligence in education'}, {'role': 'assistant', 'content': step1_content}, {'role': 'user', 'content': 'I want to focus on personalized learning and intelligent assessment.'} ] responses = dashscope.Generation.call( api_key=os.getenv('DASHSCOPE_API_KEY'), model="qwen-deep-research", messages=messages ) # Stream the research results. for response in responses: if hasattr(response, 'output') and response.output: message = response.output.get('message', {}) content = message.get('content', '') if content: print(content, end='', flush=True) Curl echo "Step 1: Get the clarifying question" curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation' \ --header 'X-DashScope-SSE: enable' \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "input": { "messages": [ { "content": "Research the applications of artificial intelligence in education", "role": "user" } ] }, "model": "qwen-deep-research" }' echo -e "\n\n" echo "Step 2: Start the deep research" curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation' \ --header 'X-DashScope-SSE: enable' \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "input": { "messages": [ { "content": "Research the applications of artificial intelligence in education", "role": "user" }, { "content": "What specific application scenarios of artificial intelligence in education would you like me to focus on?", "role": "assistant" }, { "content": "I want to focus on personalized learning.", "role": "user" } ] }, "model": "qwen-deep-research" }'
model `string` (Required) Supported value: `qwen-deep-research`.
messages `array` (Required) Conversation history, in chronological order. Message types User message `object` (Required) A user message sends questions, instructions, or context to the model. In the two-step call flow of Qwen-Deep-Research, user messages serve different purposes: Step 1 (Clarifying question): The user message initiates the research request with a broad topic. Step 2 (Deep research): The user message answers the model's clarifying question to narrow the model's research scope for a more targeted analysis. Fields content `string` (Required) The message content. role `string` (Required) Must be `user`. Assistant message `object` (Optional) The model's reply to a user message. For Step 2 (Deep research), pass the model's clarifying question from Step 1 to produce a more targeted analysis. content `string` (Optional) The message content. role `string` (Required) Must be `assistant`.
output_format `string` (Optional) Format and detail level of the research report. Valid values: `model_detailed_report` (Default) Complete report (~6,000 tokens) for in-depth analysis. `model_summary_report` Concise summary (~1,500–2,000 tokens) with key findings.

Response object	Research planning phase `{ "status_code": 200, "request_id": "2a6187f0-7e7b-40bb-a87e-xxx", "code": "", "message": "", "output": { "text": null, "finish_reason": null, "choices": null, "message": { "phase": "ResearchPlanning", "role": "assistant", "content": "", "extra": { "deep_research": {} }, "status": "typing" }, "fininshed": false, "fininshed_reason": "null" }, "usage": { "input_tokens": 694, "output_tokens": 0 }, "request_id": "2a6187f0-7e7b-40bb-xxx" }` Web research phase `{ "status_code": 200, "request_id": "2a6187f0-7e7b-40bb-a87e-xxx", "code": "", "message": "", "output": { "message": { "phase": "WebResearch", "role": "assistant", "content": "", "extra": { "deep_research": { "query": { "researchGoal": "By searching", "query": "", "id": 1 } } }, "status": "streamingQueries" }, "fininshed": false, "fininshed_reason": "null" }, "usage": { "input_tokens": 694, "output_tokens": 0 } }` Keep alive phase `{ "status_code": 200, "request_id": "2a6187f0-7e7b-40bb-a87e-xxx", "code": "", "message": "", "output": { "message": { "phase": "KeepAlive", "role": "assistant", "content": "", "extra": { "deep_research": {} }, "status": "typing" }, "fininshed": false, "fininshed_reason": "null" }, "usage": { "input_tokens": 694, "output_tokens": 0 } }` Answer phase { "status_code": 200, "request_id": "2a6187f0-7e7b-40bb-a87e-xxx", "code": "", "message": "", "output": { "message": { "phase": "answer", "role": "assistant", "content": ", these promises are mutual", "extra": { "deep_research": { "references": [ { "icon": "", "index_number": 1, "description": "The two xxx envisioned in the plan were never in ", "title": "History and Background \| United Nations - the United Nations", "url": "https://www.un.org/xxx" } ] } }, "status": "typing" }, "fininshed": false, "fininshed_reason": "null" }, "usage": { "input_tokens": 694, "output_tokens": 0 } }
status_code `string` The HTTP status code for the request. `200` indicates success; other values indicate an error. On failure, the thrown exception contains status_code and message.
request_id `string` The unique identifier for the request.
code `string` The error code. This field is empty on success. This parameter is returned only by the Python SDK.
message `string` The error message. This field is empty on success.
output `object` The result of the call. Fields text `string` This parameter is always `null`. finish_reason `string` The reason the model stopped generating content. Possible values: `null`: Generation is in progress. `stop`: Generation ended naturally. `length`: The maximum content length was reached. choices `array` A list of output choices from the model. Fields finish_reason `string` Possible values: `null`: Generation is in progress. `stop`: Generation ended naturally. `length`: The maximum content length was reached. message `object` The message object from the model. Fields Properties phase `string` Current phase. Possible values: `answer` `ResearchPlanning` `WebResearch` `KeepAlive` role `string` Must be `assistant`. content `string` The output content from the model. extra `array` Web search results and references gathered by the model. deep_research `object` Retrieved web search and reference information is included only in the `answer` and `WebResearch` stages, and is `null` in all other stages. research `object` Details of the research process. Fields researchGoal `string` The research goal. query `string` Search query used during research. id `integer` The search round number, in the range of [1, 15]. learningMap `object` Content summarized from tool calls, associated with the tool usage. references `object` Citations for the generated answer. This field appears only in the Answer phase. Fields icon `string` The favicon URL for the referenced content. index_number `integer` The index of the referenced content. description `string` A short description of the referenced content. title `string` The title of the referenced web page. url `string` The URL of the referenced content. webSites `object` Content referenced during research. Included only in the Web Research phase. Fields icon `string` The favicon URL for the referenced content. index_number `integer` The index of the referenced content. description `string` A short description of the referenced content. title `string` The web page title of the referenced content. url `string` The URL of the referenced content. status `string` The status of a specific phase during streaming: `typing`: The model is generating content for the current phase. `finished`: The current phase is complete. `streamingQueries`: The model is generating research goals and search queries. `streamingWebResult`: Web search, page reading, and code execution are in progress. `WebResultFinished`: The web search phase is complete. fininshed `boolean` Whether the stream is complete. Possible values: `false`: Streaming in progress. `true`: Final message. fininshed_reason `string` The reason the streaming output ended. Possible values: `null`: Generation is in progress. `stop`: The stream completed normally.
usage `object` The number of tokens used in this request. Fields input_tokens `integer` The number of input tokens. output_tokens `integer` The number of output tokens.

DashScope

Request body

Python

Curl

Response object

Research planning phase

Web research phase

Keep alive phase

Answer phase