This topic covers the input and output parameters for using the DashScope API to call the new agent application in Alibaba Cloud Model Studio.
Related guide:Agent 2.0.
This topic is applicable only to the China (Beijing) region.
Prerequisites
Before you begin, ensure you complete the following:- Create an application: Go to application management, create a new agent application in Model Studio, and record the application ID.
- Get an API Key: Obtain an API Key from key management and configure the API Key as an environment variable.
- Install the SDK (optional): Install the DashScope SDK for your programming language.
Invocation method
-
HTTP API invocation
Request URL:
POST https://dashscope.aliyuncs.com/api/v1/apps/APP_ID/completionReplace
APP_IDwith your actual application ID. - SDK invocation The Python and Java SDKs use the correct endpoint by default. To set a custom endpoint, use the base_url parameter.
Request bodyapp_idstring(Required)The application ID.Obtain this from the application card in Application Management.
In the Java SDK, this parameter is appId. For HTTP calls, replace promptstring(Required)The user input that guides the application's response.For HTTP calls, place the prompt in the input object.session_id string (Optional)The identifier for the conversation history.When you pass session_id, the request automatically includes the conversation history stored in the cloud. In this case, you must pass prompt.This ID expires after 1 hour of inactivity.In the Java SDK, use setSessionId. For HTTP calls, place the session_id in the input object.workspace string (Optional)The workspace identifier. For more information, see Obtain Workspace ID.You need to pass the workspace ID only when you call an application in a sub-workspace.For HTTP calls, specify the X-DashScope-WorkSpace header.stream boolean (Optional, default: false)Specifies whether to stream the response.We recommend that you set this to true to improve the reading experience and reduce the risk of timeouts.Valid values:
To enable streaming output with the Java SDK, use theincremental_output boolean (Optional, default: false)Specifies whether to enable incremental output in streaming output mode.We recommend setting this to true to improve the reading experience.Valid values:
Copy
Copy In the Java SDK, this parameter is incrementalOutput. For HTTP calls, place incremental_output in the parameters object.enable_thinking boolean (Optional, default: false)This parameter toggles between thinking and non-thinking modes for deep-thinking models.Valid values:
To obtain the content of the thinking process, you must set has_thoughts to True:
Enabling In the Java SDK, this parameter is enableThinking. For HTTP calls, place enable_thinking in the parameters object. Requires Java Dashscope SDK version 2.20.0 or later.has_thoughts boolean (Optional, default: false)Specifies whether to output the thinking process of a model that has thinking mode enabled. The process is returned in the thoughts field.Valid values:
In the Java SDK, this parameter is hasThoughts. For HTTP calls, place has_thoughts in the parameters object.image_list array(Optional)A list of images. This parameter supports image URLs and Data URLs (Base64-encoded). The application must use an Image and Video Understanding model.The base64 encoding format can be constructed as a Data URL: data:[MIME_type];base64,{base64_image}. For a detailed description and code examples, see the Visual Understanding section.In the Java SDK, this parameter is images. For HTTP calls, place image_list in the input object.file_list array(Optional)A list of file URLs.In the Java SDK, this parameter is files. For HTTP calls, place file_list in the input object. Requires Python Dashscope SDK version 1.24.7 or later, or Java Dashscope SDK version 2.21.13 or later.model_id string(Optional)The model name.You can use this parameter to specify the model to be used for the current API call.Priority: If the model_id passed through the API is different from the one configured in the console, the API parameter value takes precedence.In the Java SDK, this parameter is modelId. For HTTP calls, place model_id in the parameters object. Requires Java Dashscope SDK version 2.19.3 or later. |
Request example Copy Request example Copy
Request example Copy Replace APP_ID with your application ID. Request example Copy Install the required dependency: Copy Copy Request example Copy Request example Copy For multi-turn conversations, use a session_id to maintain the conversation context:
Request example Copy Request example Copy
Request example (first turn) Copy Copy Request example (first turn) Copy Copy Install the required dependency: Copy Copy Copy Request example (first turn) Copy Copy Request example (first turn) Copy Copy Replace Use stream to enable streaming output.
Request example Copy Request example Copy
Request example Copy Replace APP_ID with your application ID. Request example Copy Install the required dependency: Copy
1. Output the full response Copy
2. Output only the content of the text field Copy Request example Copy Request example Copy Pass the URLs of your files, such as documents, images, and videos, in the file_list parameter to enable the file Q&A feature.Application configuration: Enable the Pre-parse Files switch in your application.
Request example Copy Copy Request example Copy Copy Request example Copy Copy Enable the visual understanding feature by passing an image URL or a Base64-encoded Data URL to the image_list parameter. The application must use the Image and Video Understanding model.To use a local image, encode it into a Base64 string and construct a Data URL in the data:[MIME_type];base64,{base64_image} format. The MIME_type must match the image format. For example, use image/png for PNG, image/jpeg for JPEG, and image/webp for WebP.
URL request example Copy Copy URL request example Copy Copy
URL request example Copy Copy URL request example Copy Copy Install the required dependency: Copy Copy Copy URL request example Copy Copy URL request example Copy Copy Pass custom parameters using biz_params. For more information, see Call an agent application - Pass custom parameters.
Request example Copy Request example Copy Request example Copy Replace APP_ID with your application ID. Replace <TOOL_ID> with your tool ID. |
Response objectstatus_codestringThe status code of the response.A value of 200 indicates that the request was successful. Other values indicate that the request failed.If the request fails, use code to get the error code and message to get the error message.The Java SDK does not return this parameter. If the call fails, the SDK throws an exception. The exception includes the status_code value.request_id stringA unique identifier for this call.
In the Java SDK, this parameter is returned as code stringThe error code. This field is empty if the call is successful.Only the Python SDK returns this parameter.message stringA detailed error message. This field is empty if the request is successful.Only the Python SDK returns this parameter.output objectThe result of the request.
output properties text stringThe content generated by the model.finish_reason stringThe reason the generation stopped.stop indicates a natural stop (a predefined stop sequence). null indicates a forced stop (for example, the maximum length limit is reached or the generation is manually stopped).session_idstringA unique identifier for the current conversation.Pass this ID in subsequent requests to include the conversation history.thoughtsarrayWhen you make a call, set the has_thoughts parameter to True to view the the thinking process of the Deep Thinking Model in thoughts.
thoughts properties thought stringThe thinking process of the model.Procedure
stringThe type of action performed by the model. For example, reasoning indicates the thinking process of the Deep Thinking Model.action_name stringThe name of the action being executed, such as the thinking process.action stringThe step being executed.action_input_stream stringThe streaming input for the action.action_input stringThe input for the action.objectUsage details for this request.
usage properties models arrayInformation about the model used in this call.
models properties model_id stringThe ID of the model used for the request.input_tokens integerThe length, in tokens, of the user input text.output_tokens integerThe length, in tokens, of the model output. | Example success response Copy code and message fields indicate the reason for the error.The following example shows an error response when an invalid API-KEY is provided.Copy |