Qwen-Deep-Research API reference

Request and response parameters for calling the Qwen-Deep-Research model through the DashScope API. Related documentation: Deep research (Qwen-Deep-Research) Important

This document applies only to the China (Beijing) region. You must use an API key from this 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


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 <b>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.

<b>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. FieldsProperties **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.