API reference for Qwen-Deep-Research - Alibaba Cloud Model Studio

This topic describes the input and output parameters of Qwen-Deep-Research DashScope API.

Reference: Deep research (Qwen-Deep-Research)

Important

This document applies only to the China (Beijing) region. To use the model, you must use an API key for the China (Beijing) region.

Note

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

DashScope

Before you begin, create an API key and export the API key as an environment variable. To call the model using the DashScope SDK, install the DashScope SDK.

Request body	Python import os import dashscope # Step 1: Model asks a follow-up question for confirmation messages = [{'role': 'user', 'content': 'Research the application of artificial intelligence in education'}] responses = dashscope.Generation.call( api_key=os.getenv('DASHSCOPE_API_KEY'), model="qwen-deep-research", messages=messages, stream=True ) # Get the content of the model's follow-up 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: Conduct deep research messages = [ {'role': 'user', 'content': 'Research the application 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 output of 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: Model asks a follow-up question for confirmation" 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 application of artificial intelligence in education", "role": "user" } ] }, "model": "qwen-deep-research" }' echo -e "\n\n" echo "Step 2: Conduct 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 application of artificial intelligence in education", "role": "user" }, { "content": "Which specific scenarios of AI in education do you want to focus on?", "role": "assistant" }, { "content": "I want to focus on personalized learning.", "role": "user" } ] }, "model": "qwen-deep-research" }'
model `string` (Required) The name of the model, qwen-deep-research.
messages `array` (Required) The context for the model, arranged in conversational order. Message types User Message `object` (Required) A user message provides questions, instructions, or context to the model. The purpose of the user message differs based on the step in the two-step call flow of Qwen-Deep-Research: Step 1 (Model follow-up question): The user message initiates the research request with a broad research topic. Step 2 (Deep research): The user message provides answers to the model's clarifying questions. This helps the model focus its research and perform a more targeted analysis. Properties content `string` (Required) The message content. role `string` (Required) The role of the message. Set the value to user. Assistant Message `object` (Optional) A response from the model to a user message. In an API call for Step 2 (Deep research), this parameter passes the clarifying question that was returned by the model in Step 1 (Model follow-up question). This information becomes part of the conversation history and guides the model to perform a more targeted analysis. content `string` (Optional) The message content. role `string` (Required) Set to `assistant`.
output_format `string` (Optional) Specifies the format and level of detail for the output research report. Valid values: `model_detailed_report` (Default): The model generates a complete and detailed deep research report of approximately 6,000 tokens. This format is suitable for scenarios that require a comprehensive, in-depth analysis. `model_summary_report`: The model generates a concise summary report of approximately 1,500 to 2,000 tokens that highlights key points. This format is suitable for scenarios in which you need to quickly understand key information and conclusions.

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 search 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 } }` Persistent connection 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 } }` Follow-up question and 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 status code of the request. A value of 200 indicates success. Other values indicate failure. If the call fails, an exception is thrown. The exception message contains the values of the status_code and message parameters.
request_id `string` The unique identifier for the call.
code `string` The error code. This parameter is empty if the call is successful. Only the Python SDK returns this parameter.
message `string` The error message. This parameter is empty if the call is successful.
output `object` The information about the result of the call. Properties text `string` This parameter is currently fixed to `null`. finish_reason `string` The reason the model stopped generating output. Valid values: `null`: Generation is in progress. `stop`: The model stopped generating the output naturally. `length`: The output was stopped because it reached the maximum length. choices `array` The output information from the model. Properties finish_reason `string` Consider the following scenarios: `null`: Generation is in progress. `stop`: The model stopped generating the output naturally. `length`: The output was stopped because it reached the maximum length. message `object` The message object output by the model. Properties Properties phase `string` The current phase of the process. The value can be one of the following: answer: The follow-up question and answer phase. ResearchPlanning: The research planning phase. WebResearch: The web search phase. KeepAlive: The persistent connection phase. role `string` The role of the output message. The value is fixed to `assistant`. content `string` The output content from the model. extra `array` The web search and reference information that is retrieved by the model. deep_research `object` Contains web search and reference information. This parameter is returned only in the `answer` and `WebResearch` phases. In other phases, the value of this parameter is null. research `object` Information about the model's research process and content. Properties researchGoal `string` The research goal. query `string` The search content used during the research process. id `integer` The search round. The value ranges from 1 to 15. learningMap `object` The content that is summarized from the tool call. This parameter is associated with the tool call. references `object` The content that is referenced by the model to generate the response. This parameter is returned only in the answer phase. Properties icon `string` The link to the favicon of the referenced URL. index_number `integer` The index of the reference. description `string` A brief description of the reference. title `string` The web page title of the reference. url `string` The URL of the reference web page. webSites `object` The content that is referenced by the model during the research process. This parameter is returned only in the web search phase. Properties icon `string` The link to the favicon of the referenced URL. index_number `integer` The index of the reference. description `string` A brief description of the reference. title `string` The web page title of the reference. url `string` The URL of the reference web page. status `string` The status of the different phases in the model's output process: typing: The content for this phase is being generated. finished: The phase is complete. streamingQueries: The research goals and search queries are being generated. streamingWebResult: Search, web page reading, and code execution are in progress. WebResultFinished: The web search phase is complete. finished `boolean` Indicates whether the streaming output of the model's content is complete. Valid values: `false`: The content is still being streamed. `true`: All content has been output. This is the final response. finished_reason `string` Indicates the reason why the streaming output of the model's content ended. Valid values: `null`: Generation is in progress. `stop`: The streaming output of the model's content stopped naturally.
usage `object` Information about the tokens used in this request. Properties 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 search phase

Persistent connection phase

Follow-up question and answer phase