Skip to main content

Invoke a workflow application

This guide explains how to quickly and efficiently integrate an Alibaba Cloud Model Studio Workflow Application into your business system using the DashScope SDK or an HTTP API.

To call the Responses API, see Responses API.
This topic is applicable only to the China (Beijing) region.

Prerequisites

Before you begin, ensure you have completed the following:
  1. You have obtained an API key and set it as an environment variable.
  2. You have created a workflow application and obtained the APP_ID from the application card on the application management page.
  3. If you use the DashScope SDK, you must have the DashScope SDK installed.

Quick start

  • Python
  • Java
  • HTTP
Sample request
import os
from http import HTTPStatus
from dashscope import Application
response = Application.call(
    # If environment variables are not configured, you can replace the following line with api_key="sk-xxx". However, it is not recommended to hard code the API Key directly into the code in a production environment to reduce the risk of API Key leakage.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='YOUR_APP_ID',# Replace with the actual application ID
    prompt='Who are you?')

if response.status_code != HTTPStatus.OK:
    print(f'request_id={response.request_id}')
    print(f'code={response.status_code}')
    print(f'message={response.message}')
    print(f'Refer to: https://help.aliyun.com/en/model-studio/developer-reference/error-code')
else:
    print(response.output.text)
Sample response
I am a large language model developed by Alibaba Cloud, named Qwen. I am designed to help users generate various types of text, such as articles, stories, poems, stories, etc., and can be adjusted and optimized according to different scenarios and needs. In addition, I can also answer various questions, provide information and explanations, and assist in learning and research. If you have any needs, please feel free to ask me questions at any time!

Multi-turn conversation

Unlike single-turn dialogue, multi-turn dialogue allows a large model to refer to the conversation history, resulting in more realistic conversations.
Usesession_idThe system automatically loads the conversation history from the cloud and combines it with the prompt to generate the context. This approach is simple and maintenance-free.
A session_id is valid for 1 hour and supports a maximum of 50 dialog turns.
Managemessages(Recommended)Maintain the messages array yourself. In each dialog turn, manually record and pass the conversation history and any new instructions. The prompt parameter is not required. This approach gives you greater flexibility and full control over the context.
Note: If a request includes both session_id and messages, messages takes precedence.
In the LLM Node, configure the prompt variable historyList and Publish the application, and then make an API call.
  • Cloud storage
  • Self-managed
  • Python
  • Java
  • HTTP
Request example
import os
from http import HTTPStatus
from dashscope import Application
def call_with_session():
    response = Application.call(
        # If the environment variable is not configured, you can use your Model Studio API key by replacing the following line with: api_key="sk-xxx".
        # To prevent API key exposure, avoid hardcoding the key in a production environment.
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='APP_ID',  # Replace with your actual application ID.
        prompt='Who are you?')

    if response.status_code != HTTPStatus.OK:
        print(f'request_id={response.request_id}')
        print(f'code={response.status_code}')
        print(f'message={response.message}')
        print(f'See the documentation: https://help.aliyun.com/en/model-studio/developer-reference/error-code')
        return response

    responseNext = Application.call(
                # If the environment variable is not configured, you can use your Model Studio API key by replacing the following line with: api_key="sk-xxx".
                # To prevent API key exposure, avoid hardcoding the key in a production environment.
                api_key=os.getenv("DASHSCOPE_API_KEY"),
                app_id='APP_ID',  # Replace with your actual application ID.
                prompt='What can you do?',
                session_id=response.output.session_id)  # The session_id from the previous response.

    if responseNext.status_code != HTTPStatus.OK:
        print(f'request_id={responseNext.request_id}')
        print(f'code={responseNext.status_code}')
        print(f'message={responseNext.message}')
        print(f'See the documentation: https://help.aliyun.com/en/model-studio/developer-reference/error-code')
    else:
        print('%s\n session_id=%s\n' % (responseNext.output.text, responseNext.output.session_id))
        # print('%s\n' % (response.usage))

if __name__ == '__main__':
    call_with_session()
Response example
I have a wide range of skills to assist you with various tasks. Here are some of my main capabilities:

1. Information retrieval: Providing information on weather, news, historical facts, scientific knowledge, and more.
2. Language processing: Translating text, correcting grammar, and generating articles and stories.
3. Technical Q&A: Answering questions about programming, software usage, and technical troubleshooting.
4. Learning support: Assisting with questions in subjects like math, physics, and chemistry.
5. Lifestyle advice: Offering suggestions on health, diet, travel, and shopping.
6. Entertainment and interaction: Telling jokes, playing word games, and engaging in simple chats.
7. Schedule management: Setting reminders for important dates and helping to arrange schedules.
8. Data analysis: Explaining data charts and offering suggestions for analysis.
9. Emotional support: Listening to your feelings and providing comfort and encouragement.

If you have a specific request or question, just ask, and I'll do my best to help!
 session_id=98ceb3ca0c4e4b05a20a00f913050b42

Streaming output

When a large model receives input, it generates and returns intermediate results in real time. This process, called streaming output, lets you view content as the model generates it, reducing your wait time. To enable streaming output, set the appropriate parameter for your method:
  • Python SDK: Set the stream parameter to True.
  • Java SDK: Use the streamCall method.
  • HTTP: In the header, set X-DashScope-SSE to enable.
By default, streaming output is non-incremental, meaning each response includes all previously generated content. To enable incremental output, set the corresponding parameter:
  • Python SDK: Set the incremental_output parameter to True.
  • Java SDK: Call the incrementalOutput method with true.
  • HTTP: In the parameters object, set the incremental_output parameter to true.

Streaming mode

The flow_stream_mode parameter controls the streaming output mode for a workflow application. The parameter values are as follows:
message_format_plus(Recommended)Message enhancement mode streams the execution process and results for all nodes in the workflow_message field. Returns the same data structure as message_format.
Requires Python SDK version 1.24.0 or later, or Java SDK version 2.22.18 or later.
message_format(Recommended)In message mode, the execution result of the specified node is returned in a streaming manner and structured in the message field. Prerequisite: The Stream switch for the target node must be enabled in the console.
full_thoughts (Default, not recommended)Full thoughts mode streams execution details for all nodes in the thoughts field and is suitable for debugging.This requires setting the has_thoughts parameter to true.Not recommended for new applications. Use message_format or message_format_plus instead.
  • message_format_plus mode
  • Message format mode
  • full_thoughts mode
This enhanced message mode streams execution status and results for all node types through the workflow_message field. This mode uses the same data structure as the message_format mode but extends streaming support to all node types.
Client-side handling rules:
  • The message.content for all nodes is incremental; you must append each new delta to build the complete message. Some nodes, such as the Start node or nodes that perform variable substitution, only send a single data packet.
  • When the node_is_completed field is true, the node has finished executing.
  • HTTP
  • Python
  • Java
Request example
curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/YOUR_APP_ID/completion' \
--header 'X-DashScope-SSE: enable' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_DASHSCOPE_API_KEY' \
--data '{
    "input": {
        "prompt": "Hello"
    },
    "parameters": {
        "flow_stream_mode": "message_format_plus"
    }
}'
Response exampleThe following response example shows the complete streaming of a workflow through a series of Server-Sent Events (SSE):
id:1
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"3d46d9a4ae...","workflow_message":{"node_status":"success","node_type":"Start","node_msg_seq_id":1,"node_name":"Start","message":{"content":"{\"user\":{}}","role":"assistant"},"node_is_completed":true,"node_id":"Start_iEca"},"finish_reason":"null"},"usage":{},"request_id":"0e241c2b-..."}

id:2
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"3d46d9a4ae...","workflow_message":{"node_status":"executing","node_type":"LLM","node_msg_seq_id":1,"node_name":"LLM 1","message":{"content":"{\"result\":\"Hello! \",\"reasoningContent\":\"\"}","role":"assistant"},"node_is_completed":false,"node_id":"LLM_NPem"},"finish_reason":"null"},"usage":{},"request_id":"0e241c2b-..."}

id:3
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"3d46d9a4ae...","workflow_message":{"node_status":"executing","node_type":"LLM","node_msg_seq_id":2,"node_name":"LLM 1","message":{"content":"{\"result\":\"How can I help you?\",\"reasoningContent\":\"\"}","role":"assistant"},"node_is_completed":false,"node_id":"LLM_NPem"},"finish_reason":"null"},"usage":{},"request_id":"0e241c2b-..."}

id:4
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"3d46d9a4ae...","workflow_message":{"node_status":"success","node_type":"LLM","node_msg_seq_id":10,"node_name":"LLM 1","message":{"content":"","role":"assistant"},"node_is_completed":true,"node_id":"LLM_NPem"},"finish_reason":"null"},"usage":{"models":[{"input_tokens":15,"output_tokens":50,"model_id":"qwen-plus-latest"}]},"request_id":"0e241c2b-..."}

id:5
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"3d46d9a4ae...","workflow_message":{"node_status":"success","node_type":"End","node_msg_seq_id":2,"node_name":"End","message":{"content":"","role":"assistant"},"node_is_completed":true,"node_id":"End_pmAh"},"finish_reason":"null"},"usage":{"models":[{"input_tokens":15,"output_tokens":50,"model_id":"qwen-plus-latest"}]},"request_id":"0e241c2b-..."}

id:6
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"3d46d9a4ae...","finish_reason":"stop","text":"Hello! How can I help you?"},"usage":{"models":[{"input_tokens":15,"output_tokens":50,"model_id":"qwen-plus-latest"}]},"request_id":"0e241c2b-..."}

Node Execution Status

The output.thoughts[] array in the response returns execution information for each node, in execution order. The response field of each element is a JSON string containing the following fields:
FieldTypeDescription
nodeIdstringNode ID.
nodeNamestringNode name.
nodeTypestringNode type, such as Start, LLM, or Script.
nodeStatusstringNode execution status. See the table below for valid values.
nodeResultstringNode output, as a JSON string. Not returned for nodes without output, such as the Start node.
nodeExecTimestringNode execution duration, such as 1167ms. Not returned while the node is still running.
Valid values for nodeStatus:
ValueDescription
successThe node ran successfully.
failThe node failed.
skipThe node was skipped and did not run.
executingThe node is running and nodeResult is empty. In streaming mode, a node first returns executing, then returns its final status once complete.

Analysis

When a workflow application uses a deep thinking model, the model reasons through one or more steps before generating a final response. This improves the model's accuracy on complex tasks such as logical reasoning, code generation, and mathematical calculations.
A workflow application can contain multiple large model nodes, and the thinking mode must be configured for each node individually. This mode cannot be controlled dynamically via the API's enable_thinking parameter.

Thinking process

  • In your API call, set has_thoughts to true.
  • Or, in the console, reference the reasoningContent variable from a specified large model node within a flow output node or an end node.
The model returns the following: reasoningContent: Returned in the reasoningContent field. Response content: In the result field. Since deep think increases response time, we recommend using streaming output for improved responsiveness. For example:
  • Python
  • Java
  • curl
Request example
import json
from http import HTTPStatus
import os
from dashscope import Application

try:
    response = Application.call(
        # If an environment variable is not set, you can pass your Model Studio API key directly.
        # However, we strongly advise against hard-coding the API key in a production environment to prevent leaks.
        api_key=os.getenv('DASHSCOPE_API_KEY'),
        app_id='APP_ID',# Replace with your actual application ID
        prompt='Who are you?',
        stream=True,  # Set to True for streaming output. Defaults to False.
        incremental_output=True,  # Set to True for incremental output. Defaults to False.
        has_thoughts=True,  # Set to True to return the thought process. Defaults to False.
    )

except Exception as e:
    print(f"API request exception: {str(e)}")
    exit(1)

# Stores the complete thought process.
reasoning_content = []
# Stores the complete response.
answer_content = []
# Flag to track if the response phase has begun.
is_answering = False

def print_section(title):
    """Prints a section title with dividers."""
    print(f"\n{'=' * 20} {title} {'=' * 20}\n", flush=True)

print_section("Thought Process")

for chunk in response:
    if chunk.status_code != HTTPStatus.OK:
        print(f'request_id={chunk.request_id}')
        print(f'code={chunk.status_code}')
        print(f'message={chunk.message}')
        print(f'For more information, see the documentation: https://help.aliyun.com/en/model-studio/developer-reference/error-code')
        continue

    # Skip empty data chunks.
    if not chunk.output or not chunk.output.thoughts:
        continue

    # Parse the JSON data.
    for thought in chunk.output.thoughts:
        try:
            response_json = json.loads(thought.response)
            node_result = response_json.get('nodeResult', {})

            if isinstance(node_result, str):
                node_result = json.loads(node_result)

            extracted_reasoning_content = node_result.get('reasoningContent', '')
            extracted_result = node_result.get('result', '')
            node_name = response_json.get('nodeName', '')

            # Handle the thought process.
            if extracted_reasoning_content and not is_answering:
                reasoning_content.append(extracted_reasoning_content)
                print(extracted_reasoning_content, end="", flush=True)

            # Handle the response content.
            if extracted_result and node_name != "End":
                answer_content.append(extracted_result)
                if not is_answering:
                    print_section("Complete Response")
                    is_answering = True
                print(extracted_result, end="", flush=True)

        except json.JSONDecodeError as e:
            print(f"JSON parsing error: {str(e)}")

# Consolidate the final results.
final_reasoning = "".join(reasoning_content)
final_answer = "".join(answer_content)

# To print the complete thought process and the complete response, uncomment and run the following code.
# print_section("Complete Thought Process")
# print(final_reasoning)
# print_section("Complete Response")
# print(final_answer)

Parameter passing

To adapt a workflow for different business scenarios, you can pass custom parameters through the biz_params field in an API call. To do this, add a custom parameter (for example, the city name city) in the Start Node, reference the city and query variables in the Prompt, and then Publish the application.
  • Python
  • Java
  • HTTP
Request example
import os
from http import HTTPStatus
from dashscope import Application
# Pass custom parameters for workflow and agent orchestration applications.
biz_params = {"city": "Hangzhou"}
response = Application.call(
    # If the environment variable is not set, you can replace the following line with your Model Studio API key: api_key="sk-xxx".
    # For security, do not hardcode your API key in production code.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',  # Replace with your actual application ID.
    prompt='Query the administrative divisions of this city',
    biz_params=biz_params  # Pass business parameters.
)

if response.status_code != HTTPStatus.OK:
    print(f'request_id={response.request_id}')
    print(f'code={response.status_code}')
    print(f'message={response.message}')
    print(f'Refer to the documentation: https://help.aliyun.com/en/model-studio/developer-reference/error-code')
else:
    print(f'{response.output.text}')  # Process the output to show only the text.
Response example
As the capital of Zhejiang Province, Hangzhou is divided into 10 municipal districts: Shangcheng, Gongshu, Xihu, Binjiang, Xiaoshan, Yuhang, Linping, Qiantang, Fuyang, and Lin'an. Each district has its own unique characteristics and development focus.

- Shangcheng District: Located in the heart of Hangzhou, it is one of the city's political, economic, and cultural centers.
- Gongshu District: Characterized by its canal culture, it is home to numerous historical and cultural heritage sites.
- Xihu District: The famous West Lake scenic area is located here, making it a major tourist destination.
- Binjiang District: A hub for high-tech industries, where well-known companies like Alibaba are located.
- Xiaoshan District: An administrative district in the southeast with rapid economic development, especially in manufacturing.
- Yuhang District: Has seen rapid development in recent years, particularly in the internet economy, and is home to Alibaba's global headquarters.
- Linping District: A newly established administrative district aimed at promoting comprehensive economic and social development in the area.
- Qiantang District: Also a result of recent administrative adjustments, it emphasizes a combination of innovative development and ecological protection.
- Fuyang District: Located to the southwest of Hangzhou, it is known for its rich natural landscapes and long history.
- Lin'an District: Situated in the western part of Hangzhou, it is famous for its beautiful ecology and deep cultural heritage.

Note that administrative divisions can change. Refer to official sources for the latest information.

File Q&A

You can upload files to your application and use a large model for file Q&A. You can also configure a file parsing node to enable your workflow to receive and parse various file types, such as documents, images, videos, and audio. You can then use the extracted content for analysis, summarization, or Q&A.
  1. Build a workflow that supports file Q&A
    1. Configure the Start node: In the Start node, add a custom parameter to receive the file URL. For example, name it file_url and set the type to File. For multiple files, select Array[File].
      image
    2. (Optional) Add a parsing node: Add a file parsing node and use file_url as the input variable for this node.
      image
    3. Configure the large model node
      • Reference parsing output variables: If you configured a parsing node, add its text output variables, such as markdownContent or ASRInfo, to a downstream node, such as the LLM Node, to process the file content.
      • Reference the custom variable: In the Prompt of the LLM Node, reference the custom variable from the Start Node.
    4. Publish the application: Check the node configuration. After your tests pass, Publish the workflow application.
    Note: The file URL you pass must be publicly accessible.
    Related documentation: Workflow application node descriptions.
  2. Call the application You can provide a file to the application in two ways:
    1. Test in the console On the application details page, go to the test pane. Under the file_url input parameter, upload a local file or paste a file URL to run a quick test.
      image
    2. Call via API In the API request, pass the file URL in the biz_params field. The key name in biz_params must exactly match the parameter name you set in the Start node (in this example, file_url).
      • Python
      • Java
      • HTTP
      Request example
      """
      Example of calling the Alibaba Cloud Model Studio Application SDK (streaming output)
      """
      import os
      from http import HTTPStatus
      from dashscope import Application
      
      # If you have not set an environment variable, you can replace the following with: api_key="sk-xxx"
      # However, for security reasons, we do not recommend hardcoding your API key in production code.
      responses = Application.call(
          api_key=os.getenv("DASHSCOPE_API_KEY"),
          app_id='APP_ID',  # Replace with your actual application ID
          prompt='Summarize the file content in one sentence',
          stream=True,           # Streaming output
          incremental_output=True,  # Incremental output
          biz_params={
              # Single-file format (console parameter type: File)
              # The parameter name must match the one defined in the console.
              'file_url': {
                  "url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3",  # Required
                  # "name": "welcome.mp3",  # Required if referenced in the console
                  # "type": "audio",        # Required if referenced in the console. Values: image/document/audio/video/custom
                  # "source": "localFile",  # Required if referenced in the console
                  # "mimeType": "audio"     # Required if referenced in the console. Values: image/png, etc.
              }
              # Multi-file format (console parameter type: Array[File])
              # 'file_url': [
              #     {"url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf", "name": "file1.pdf"},
              #     {"url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf", "name": "file2.pdf"}
              # ]
          }
      )
      
      # Handle the streaming response
      for response in responses:
          if response.status_code != HTTPStatus.OK:
              print(f'request_id={response.request_id}')
              print(f'code={response.status_code}')
              print(f'message={response.message}')
              print(f'For more information, see https://help.aliyun.com/en/model-studio/developer-reference/error-code')
          else:
              if response.output.text:
                  print(response.output.text, end='')
      
      print()  # New line
      
      Response example
      The file contains only a welcome message: "Welcome to Alibaba Cloud."
      

Private network calls

Call applications on Alibaba Cloud Model Studio over a private network to improve data transmission security and efficiency.
  1. Add a PrivateLink connection and associate your workspace: In the Model Studio console, add a PrivateLink connection for your VPC, and then associate the target workspace with the connection.
  2. Replace the domain name: Replace the public domain name in the API request URL, dashscope.aliyuncs.com, with the private domain name that is generated after the workspace is associated. For example: https://{WorkspaceId}-{VpcId}.cn-beijing.maas.aliyuncs.com/api/v1/
  3. Make the request.
    • Python
    • Java
    • HTTP
    import os
    from http import HTTPStatus
    from dashscope import Application
    # Configure the private domain name.
    os.environ['DASHSCOPE_HTTP_BASE_URL'] = 'https://{WorkspaceId}-{VpcId}.cn-beijing.maas.aliyuncs.com/api/v1/'
    response = Application.call(
        # If the environment variable is not set, use your API key directly (e.g., api_key="sk-xxx"). Avoid hard-coding the key in production to prevent leakage.
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='APP_ID',# Replace with your actual application ID.
        prompt='Who are you?')
    
    if response.status_code != HTTPStatus.OK:
        print(f'request_id={response.request_id}')
        print(f'code={response.status_code}')
        print(f'message={response.message}')
        print(f'For more information, see https://help.aliyun.com/en/model-studio/developer-reference/error-codes')
    else:
        print(response.output.text)
    

API reference

For a complete list of application invocation parameters, see the DashScope API reference for workflows and legacy agent applications.

Error code

If a call fails and returns an error message, see Error Messages.

Billing

Billing for a workflow application is based on the billable nodes it executes, such as large model and knowledge base nodes.
  • Billing unit: Each billable node has its own billing unit. For example, a large model node is billed based on the number of tokens.
  • Total cost: The total cost of a single workflow API call is the sum of costs for all billable nodes in its execution path.

Build and use applications

To learn about configuring workflow applications, including node descriptions and how to import and export workflows, see Workflow applications.

Use the prompt assistance tool

To use the in-application prompt assistance tool, see Prompt engineering.

Convert text to speech

To convert text responses from the model into speech, see Real-time speech synthesis - CosyVoice/Sambert.

Explore advanced usage

To call applications using the Responses API, see Responses API.

FAQ

1. Why does my workflow work correctly in the console but fail or produce unexpected results when I make an API call?

This issue typically stems from version or parameter mismatches. Check the following:
  • Ensure the application is published: An API call uses the last published version of your workflow. Changes saved in the console but not published do not affect API calls. Click "Publish" to apply your changes.
  • Validate custom parameters (biz_params): The key names and data types of the biz_params in an API request must exactly match the parameters defined in the workflow's start node. For example, if the start node defines a string parameter named city, the API call must pass {"city": "some_value"}.
  • Check the input content: Verify that the prompt or messages content in your API call matches the content and format you used when testing in the console, especially for prompts with specific formatting requirements.
  1. Verify that the class and package names in your import statements are correct.
  2. Add the dependency: If you use Maven or Gradle for project management, add the latest DashScope Java SDK dependency to your pom.xml or build.gradle file. You can find the latest version number on Maven.
<!-- https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>Enter the latest version number here, for example, 2.16.4</version>
</dependency>
// https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
implementation group: 'com.alibaba', name: 'dashscope-sdk-java', version: 'Enter the latest version number here, for example, 2.16.4'
  1. Upgrade the SDK: Older SDK versions may not include the features or classes you need. If you have already added the DashScope Java SDK dependency, confirm that you are using the latest version. If not, upgrade it by updating the version number in your pom.xml or build.gradle file.
<!-- https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>Update the version number here to the latest version</version>
</dependency>
// https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
implementation group: 'com.alibaba', name: 'dashscope-sdk-java', version: 'Update the version number here to the latest version'
  1. Reload your project to apply the changes.
  2. Rerun the code sample.
Agent Development
Agent Context
Agent Governance & Evolution
Store
Application Marketplace
Invoke a workflow application - 阿里云百炼