全部產品
Search
文件中心

Alibaba Cloud Model Studio:DashScope API 參考

更新時間:Dec 26, 2025

本文介紹 DashScope API 呼叫阿里雲百鍊應用(智能體工作流程)的輸入與輸出參數,並提供典型情境下的調用樣本。

重要

本文檔僅適用於國際版(新加坡地區)。

相關指南

請參閱應用調用

調用方式

  • HTTP 介面調用

    請求地址:POST https://dashscope-intl.aliyuncs.com/api/v1/apps/APP_ID/completion

    其中 APP_ID 需替換為您的實際應用 ID。
  • SDK 調用

    Python/Java SDK:本文已預設配置正確的 endpoint

    自訂 endpoint:可通過 base_url 參數配置

前置準備

開始前,請確保您已完成以下操作:

  1. 建立應用:前往應用管理建立阿里雲百鍊應用並擷取應用 ID;

  2. 擷取 API Key:通過密鑰管理擷取,並配置API Key到環境變數

  3. 安裝SDK(可選):若使用 SDK 調用,請安裝相應語言的DashScope SDK

DashScope API 線上調試

請求體
POST https://dashscope-intl.aliyuncs.com/api/v1/apps/APP_ID/completion
擷取 App ID
擷取 API Key
響應結果

請求體

單輪對話

Python

請求樣本

import os
from http import HTTPStatus
from dashscope import Application
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
response = Application.call(
    # 若沒有配置環境變數,可用百鍊API Key將下行替換為:api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',# 替換為實際的應用 ID
    prompt='你是誰?')

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'請參考文檔:https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
else:
    print(response.output.text)

Java

請求樣本

// 建議dashscope SDK的版本 >= 2.12.0
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
    static {
      Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void appCall()
            throws ApiException, NoApiKeyException, InputRequiredException {
        ApplicationParam param = ApplicationParam.builder()
                // 若沒有配置環境變數,可用百鍊API Key將下行替換為:.apiKey("sk-xxx")。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .appId("APP_ID")
                .prompt("你是誰?")
                .build();

        Application application = new Application();
        ApplicationResult result = application.call(param);

        System.out.printf("text: %s\n",
                result.getOutput().getText());
    }

    public static void main(String[] args) {
        try {
            appCall();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.err.println("message:"+e.getMessage());
            System.out.println("請參考文檔:https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code");
        }
        System.exit(0);
    }
}

HTTP

curl

請求樣本

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/apps/APP_ID/completion \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "prompt": "你是誰?"
    },
    "parameters":  {},
    "debug": {}
}' 
APP_ID替換為實際的應用 ID。

PHP

請求樣本

<?php

# 若沒有配置環境變數,可用百鍊API Key將下行替換為:$api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
$api_key = getenv("DASHSCOPE_API_KEY");
$application_id = 'APP_ID'; // 替換為實際的應用 ID

$url = "https://dashscope-intl.aliyuncs.com/api/v1/apps/$application_id/completion";

// 構造請求資料
$data = [
    "input" => [
        'prompt' => '你是誰?'
    ]
];

// 將資料編碼為 JSON
$dataString = json_encode($data);

// 檢查 json_encode 是否成功
if (json_last_error() !== JSON_ERROR_NONE) {
    die("JSON encoding failed with error: " . json_last_error_msg());
}

// 初始化 cURL 對話
$ch = curl_init($url);

// 設定 cURL 選項
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $dataString);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $api_key
]);

// 執行請求
$response = curl_exec($ch);

// 檢查 cURL 執行是否成功
if ($response === false) {
    die("cURL Error: " . curl_error($ch));
}

// 擷取 HTTP 狀態代碼
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// 關閉 cURL 對話
curl_close($ch);
// 解碼響應資料
$response_data = json_decode($response, true);
// 處理響應
if ($status_code == 200) {
    if (isset($response_data['output']['text'])) {
        echo "{$response_data['output']['text']}\n";
    } else {
        echo "No text in response.\n";
    }}
else {
    if (isset($response_data['request_id'])) {
        echo "request_id={$response_data['request_id']}\n";}
    echo "code={$status_code}\n";
    if (isset($response_data['message'])) {
        echo "message={$response_data['message']}\n";} 
    else {
        echo "message=Unknown error\n";}
}
?>

Node.js

需安裝相關依賴:

npm install axios

請求樣本

const axios = require('axios');

async function callDashScope() {
    // 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey='sk-xxx'。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
    const apiKey = process.env.DASHSCOPE_API_KEY;
    const appId = 'APP_ID';// 替換為實際的應用 ID

    const url = `https://dashscope-intl.aliyuncs.com/api/v1/apps/${appId}/completion`;

    const data = {
        input: {
            prompt: "你是誰?"
        },
        parameters: {},
        debug: {}
    };

    try {
        const response = await axios.post(url, data, {
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Content-Type': 'application/json'
            }
        });

        if (response.status === 200) {
            console.log(`${response.data.output.text}`);
        } else {
            console.log(`request_id=${response.headers['request_id']}`);
            console.log(`code=${response.status}`);
            console.log(`message=${response.data.message}`);
        }
    } catch (error) {
        console.error(`Error calling DashScope: ${error.message}`);
        if (error.response) {
            console.error(`Response status: ${error.response.status}`);
            console.error(`Response data: ${JSON.stringify(error.response.data, null, 2)}`);
        }
    }
}

callDashScope();

C#

請求樣本

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        //若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。 
        string apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY") ?? throw new InvalidOperationException("DASHSCOPE_API_KEY environment variable is not set.");
        string appId = "APP_ID"; // 替換為實際的應用ID

        string url = $"https://dashscope-intl.aliyuncs.com/api/v1/apps/{appId}/completion";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");

            string jsonContent = @"{
                ""input"": {
                    ""prompt"": ""你是誰?""
                },
                ""parameters"": {},
                ""debug"": {}
            }";

            HttpContent content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

            try
            {
                HttpResponseMessage response = await client.PostAsync(url, content);

                if (response.IsSuccessStatusCode)
                {
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Request successful:");
                    Console.WriteLine(responseBody);
                }
                else
                {
                    Console.WriteLine($"Request failed with status code: {response.StatusCode}");
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine(responseBody);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error calling DashScope: {ex.Message}");
            }
        }
    }
}

Go

請求樣本

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	// 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey := "sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
	apiKey := os.Getenv("DASHSCOPE_API_KEY")
	appId := "APP_ID" // 替換為實際的應用 ID

	if apiKey == "" {
		fmt.Println("請確保設定了DASHSCOPE_API_KEY。")
		return
	}

	url := fmt.Sprintf("https://dashscope-intl.aliyuncs.com/api/v1/apps/%s/completion", appId)

	// 建立請求體
	requestBody := map[string]interface{}{
		"input": map[string]string{
			"prompt": "你是誰?",
		},
		"parameters": map[string]interface{}{},
		"debug":      map[string]interface{}{},
	}

	jsonData, err := json.Marshal(requestBody)
	if err != nil {
		fmt.Printf("Failed to marshal JSON: %v\n", err)
		return
	}

	// 建立 HTTP POST 請求
	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	if err != nil {
		fmt.Printf("Failed to create request: %v\n", err)
		return
	}

	// 佈建要求頭
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	// 發送請求
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Printf("Failed to send request: %v\n", err)
		return
	}
	defer resp.Body.Close()

	// 讀取響應
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Printf("Failed to read response: %v\n", err)
		return
	}

	// 處理響應
	if resp.StatusCode == http.StatusOK {
		fmt.Println("Request successful:")
		fmt.Println(string(body))
	} else {
		fmt.Printf("Request failed with status code: %d\n", resp.StatusCode)
		fmt.Println(string(body))
	}
}

多輪對話

通過session_idmessages啟用多輪對話。

Python

請求樣本

import os
from http import HTTPStatus
from dashscope import Application
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

def call_with_session():
    response = Application.call(
        # 若沒有配置環境變數,可用百鍊API Key將下行替換為:api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='APP_ID',  # 替換為實際的應用 ID
        prompt='你是誰?')

    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'請參考文檔:https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
        return response

    responseNext = Application.call(
                # 若沒有配置環境變數,可用百鍊API Key將下行替換為:api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
                api_key=os.getenv("DASHSCOPE_API_KEY"),
                app_id='APP_ID',  # 替換為實際的應用 ID
                prompt='你有什麼技能?',
                session_id=response.output.session_id)  # 上一輪response的session_id

    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'請參考文檔:https://www.alibabacloud.com/help/zh/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()

Java

請求樣本

import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import java.util.Arrays;
import java.util.List;
import com.alibaba.dashscope.utils.Constants;
public class Main {
    static {
      Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void callWithSession()
            throws ApiException, NoApiKeyException, InputRequiredException {
        ApplicationParam param = ApplicationParam.builder()
                // 若沒有配置環境變數,可用百鍊API Key將下行替換為:.apiKey("sk-xxx")。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 替換為實際的應用 ID
                .appId("APP_ID")
                .prompt("你是誰?")
                .build();

        Application application = new Application();
        ApplicationResult result = application.call(param);

        param.setSessionId(result.getOutput().getSessionId());
        param.setPrompt("你有什麼技能?");
        result = application.call(param);

        System.out.printf("%s\n session_id: %s\n",
                result.getOutput().getText(), result.getOutput().getSessionId());
    }

    public static void main(String[] args) {
        try {
            callWithSession();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.printf("Exception: %s", e.getMessage());
            System.out.println("請參考文檔:https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code");
        }
        System.exit(0);
    }
}

HTTP

curl

請求樣本(上一輪對話)

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/apps/APP_ID/completion \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "prompt": "你是誰?"
    },
    "parameters":  {},
    "debug": {}
}' 

請求樣本(下一輪對話)

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/apps/APP_ID/completion \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "prompt": "你有什麼技能?",
        "session_id":"4f8ef7233dc641aba496cb201fa59f8c"
    },
    "parameters":  {},
    "debug": {}
}' 

PHP

請求樣本(上一輪對話)

<?php
# 若沒有配置環境變數,可用百鍊API Key將下行替換為:$api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
$api_key = getenv("DASHSCOPE_API_KEY");
$application_id = 'APP_ID'; // 替換為實際的應用 ID

$url = "https://dashscope-intl.aliyuncs.com/api/v1/apps/$application_id/completion";

// 構造請求資料
$data = [
    "input" => [
        'prompt' => '你是誰?'
    ]
];

// 將資料編碼為 JSON
$dataString = json_encode($data);

// 檢查 json_encode 是否成功
if (json_last_error() !== JSON_ERROR_NONE) {
    die("JSON encoding failed with error: " . json_last_error_msg());
}

// 初始化 cURL 對話
$ch = curl_init($url);

// 設定 cURL 選項
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $dataString);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $api_key
]);

// 執行請求
$response = curl_exec($ch);

// 檢查 cURL 執行是否成功
if ($response === false) {
    die("cURL Error: " . curl_error($ch));
}

// 擷取 HTTP 狀態代碼
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// 關閉 cURL 對話
curl_close($ch);
// 解碼響應資料
$response_data = json_decode($response, true);
// 處理響應
if ($status_code == 200) {
    if (isset($response_data['output']['text'])) {
        echo "{$response_data['output']['text']}\n";
    } else {
        echo "No text in response.\n";
    };
    if (isset($response_data['output']['session_id'])) {
        echo "session_id={$response_data['output']['session_id']}\n";
    }
}else {
    if (isset($response_data['request_id'])) {
        echo "request_id={$response_data['request_id']}\n";}
    echo "code={$status_code}\n";
    if (isset($response_data['message'])) {
        echo "message={$response_data['message']}\n";} 
    else {
        echo "message=Unknown error\n";}
}
?>

請求樣本(下一輪對話)

<?php
# 若沒有配置環境變數,可用百鍊API Key將下行替換為:$api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
$api_key = getenv("DASHSCOPE_API_KEY");
$application_id = 'APP_ID'; // 替換為實際的應用 ID

$url = "https://dashscope-intl.aliyuncs.com/api/v1/apps/$application_id/completion";

// 構造請求資料
$data = [
    "input" => [
        'prompt' => '你有什麼技能?',
        // 替換為實際上一輪對話返回的session_id
        'session_id' => '2e658bcb514f4d30ab7500b4766a8d43'
    ]
];

// 將資料編碼為 JSON
$dataString = json_encode($data);

// 檢查 json_encode 是否成功
if (json_last_error() !== JSON_ERROR_NONE) {
    die("JSON encoding failed with error: " . json_last_error_msg());
}

// 初始化 cURL 對話
$ch = curl_init($url);

// 設定 cURL 選項
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $dataString);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $api_key
]);

// 執行請求
$response = curl_exec($ch);

// 檢查 cURL 執行是否成功
if ($response === false) {
    die("cURL Error: " . curl_error($ch));
}

// 擷取 HTTP 狀態代碼
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// 關閉 cURL 對話
curl_close($ch);
// 解碼響應資料
$response_data = json_decode($response, true);
// 處理響應
if ($status_code == 200) {
    if (isset($response_data['output']['text'])) {
        echo "{$response_data['output']['text']}\n";
    } else {
        echo "No text in response.\n";
    };
    if (isset($response_data['output']['session_id'])) {
        echo "session_id={$response_data['output']['session_id']}\n";
    }
}else {
    if (isset($response_data['request_id'])) {
        echo "request_id={$response_data['request_id']}\n";}
    echo "code={$status_code}\n";
    if (isset($response_data['message'])) {
        echo "message={$response_data['message']}\n";} 
    else {
        echo "message=Unknown error\n";}
}
?>

Node.js

需安裝相關依賴:

npm install axios

請求樣本(上一輪對話)

const axios = require('axios');

async function callDashScope() {
    // 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey='sk-xxx'。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
    const apiKey = process.env.DASHSCOPE_API_KEY;
    const appId = 'APP_ID';// 替換為實際的應用 ID

    const url = `https://dashscope-intl.aliyuncs.com/api/v1/apps/${appId}/completion`;

    const data = {
        input: {
            prompt: "你是誰?"
        },
        parameters: {},
        debug: {}
    };

    try {
        const response = await axios.post(url, data, {
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Content-Type': 'application/json'
            }
        });

        if (response.status === 200) {
            console.log(`${response.data.output.text}`);
            console.log(`session_id=${response.data.output.session_id}`);
        } else {
            console.log(`request_id=${response.headers['request_id']}`);
            console.log(`code=${response.status}`);
            console.log(`message=${response.data.message}`);
        }
    } catch (error) {
        console.error(`Error calling DashScope: ${error.message}`);
        if (error.response) {
            console.error(`Response status: ${error.response.status}`);
            console.error(`Response data: ${JSON.stringify(error.response.data, null, 2)}`);
        }
    }
}
callDashScope();

請求樣本(下一輪對話)

const axios = require('axios');

async function callDashScope() {
    // 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey='sk-xxx'。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
    const apiKey = process.env.DASHSCOPE_API_KEY;
    const appId = 'APP_ID';// 替換為實際的應用 ID

    const url = `https://dashscope-intl.aliyuncs.com/api/v1/apps/${appId}/completion`;
    // session_id替換為實際上一輪對話的session_id
    const data = {
        input: {
            prompt: "你有什麼技能?",
            session_id: 'fe4ce8b093bf46159ea9927a7b22f0d3',
        },
        parameters: {},
        debug: {}
    };

    try {
        const response = await axios.post(url, data, {
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Content-Type': 'application/json'
            }
        });

        if (response.status === 200) {
            console.log(`${response.data.output.text}`);
            console.log(`session_id=${response.data.output.session_id}`);
        } else {
            console.log(`request_id=${response.headers['request_id']}`);
            console.log(`code=${response.status}`);
            console.log(`message=${response.data.message}`);
        }
    } catch (error) {
        console.error(`Error calling DashScope: ${error.message}`);
        if (error.response) {
            console.error(`Response status: ${error.response.status}`);
            console.error(`Response data: ${JSON.stringify(error.response.data, null, 2)}`);
        }
    }
}
callDashScope();

C#

請求樣本(上一輪對話)

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        //若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。 
        string apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY") ?? throw new InvalidOperationException("DASHSCOPE_API_KEY environment variable is not set.");
        string appId = "APP_ID"; // 替換為實際的應用ID

        string url = $"https://dashscope-intl.aliyuncs.com/api/v1/apps/{appId}/completion";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");

            string jsonContent = @"{
                ""input"": {
                    ""prompt"": ""你是誰?""
                },
                ""parameters"": {},
                ""debug"": {}
            }";

            HttpContent content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

            try
            {
                HttpResponseMessage response = await client.PostAsync(url, content);

                if (response.IsSuccessStatusCode)
                {
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Request successful:");
                    Console.WriteLine(responseBody);
                }
                else
                {
                    Console.WriteLine($"Request failed with status code: {response.StatusCode}");
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine(responseBody);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error calling DashScope: {ex.Message}");
            }
        }
    }
}

請求樣本(下一輪對話)

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        //若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。 
        string apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY") ?? throw new InvalidOperationException("DASHSCOPE_API_KEY environment variable is not set.");
        string appId = "APP_ID"; // 替換為實際的應用ID

        string url = $"https://dashscope-intl.aliyuncs.com/api/v1/apps/{appId}/completion";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");

            string jsonContent = @"{
                ""input"": {
                    ""prompt"": ""你有什麼技能?"",
                    ""session_id"": ""7b830e4cc8fe44faad0e648f9b71435f""
                },
                ""parameters"": {},
                ""debug"": {}
            }";

            HttpContent content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

            try
            {
                HttpResponseMessage response = await client.PostAsync(url, content);

                if (response.IsSuccessStatusCode)
                {
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Request successful:");
                    Console.WriteLine(responseBody);
                }
                else
                {
                    Console.WriteLine($"Request failed with status code: {response.StatusCode}");
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine(responseBody);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error calling DashScope: {ex.Message}");
            }
        }
    }
}

Go

請求樣本(上一輪對話)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	// 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey := "sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
	apiKey := os.Getenv("DASHSCOPE_API_KEY")
	appId := "APP_ID" // 替換為實際的應用 ID

	if apiKey == "" {
		fmt.Println("請確保設定了DASHSCOPE_API_KEY。")
		return
	}

	url := fmt.Sprintf("https://dashscope-intl.aliyuncs.com/api/v1/apps/%s/completion", appId)

	// 建立請求體
	requestBody := map[string]interface{}{
		"input": map[string]string{
			"prompt": "你是誰?",
		},
		"parameters": map[string]interface{}{},
		"debug":      map[string]interface{}{},
	}

	jsonData, err := json.Marshal(requestBody)
	if err != nil {
		fmt.Printf("Failed to marshal JSON: %v\n", err)
		return
	}

	// 建立 HTTP POST 請求
	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	if err != nil {
		fmt.Printf("Failed to create request: %v\n", err)
		return
	}

	// 佈建要求頭
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	// 發送請求
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Printf("Failed to send request: %v\n", err)
		return
	}
	defer resp.Body.Close()

	// 讀取響應
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Printf("Failed to read response: %v\n", err)
		return
	}

	// 處理響應
	if resp.StatusCode == http.StatusOK {
		fmt.Println("Request successful:")
		fmt.Println(string(body))
	} else {
		fmt.Printf("Request failed with status code: %d\n", resp.StatusCode)
		fmt.Println(string(body))
	}
}

請求樣本(下一輪對話)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	// 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey := "sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
	apiKey := os.Getenv("DASHSCOPE_API_KEY")
	appId := "APP_ID" // 替換為實際的應用 ID

	if apiKey == "" {
		fmt.Println("請確保設定了DASHSCOPE_API_KEY。")
		return
	}

	url := fmt.Sprintf("https://dashscope-intl.aliyuncs.com/api/v1/apps/%s/completion", appId)

	// 建立請求體
	requestBody := map[string]interface{}{
		"input": map[string]string{
			"prompt":     "你有什麼技能?",
			"session_id": "f7eea37f0c734c20998a021b688d6de2", // 替換為實際上一輪對話的session_id
		},
		"parameters": map[string]interface{}{},
		"debug":      map[string]interface{}{},
	}

	jsonData, err := json.Marshal(requestBody)
	if err != nil {
		fmt.Printf("Failed to marshal JSON: %v\n", err)
		return
	}

	// 建立 HTTP POST 請求
	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	if err != nil {
		fmt.Printf("Failed to create request: %v\n", err)
		return
	}

	// 佈建要求頭
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	// 發送請求
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Printf("Failed to send request: %v\n", err)
		return
	}
	defer resp.Body.Close()

	// 讀取響應
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Printf("Failed to read response: %v\n", err)
		return
	}

	// 處理響應
	if resp.StatusCode == http.StatusOK {
		fmt.Println("Request successful:")
		fmt.Println(string(body))
	} else {
		fmt.Printf("Request failed with status code: %d\n", resp.StatusCode)
		fmt.Println(string(body))
	}
}
APP_ID替換為實際的應用 ID。下一輪對話的輸入參數session_id欄位值替換為實際上一輪對話返回的session_id值。

傳遞參數

通過biz_params傳遞自訂參數。

Python

請求樣本

import os
from http import HTTPStatus
# 建議dashscope SDK 的版本 >= 1.14.0
from dashscope import Application
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
biz_params = {
    # 智能體應用的自訂外掛程式輸入參數傳遞,自訂的外掛程式ID替換<TOOL_ID>
    "user_defined_params": {
        "<TOOL_ID>": {
            "article_index": 2}}}
response = Application.call(
        # 若沒有配置環境變數,可用百鍊API Key將下行替換為:api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='APP_ID',
        prompt='寢室公約內容',
        biz_params=biz_params)

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'請參考文檔:https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
else:
    print('%s\n' % (response.output.text))  # 處理只輸出文本text
    # print('%s\n' % (response.usage))

Java

請求樣本

import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;

import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void appCall() throws NoApiKeyException, InputRequiredException {
        String bizParams =
                // 智能體應用的自訂外掛程式輸入參數傳遞,自訂的外掛程式ID替換<TOOL_ID>
                "{\"user_defined_params\":{\"<TOOL_ID>\":{\"article_index\":2}}}";
        ApplicationParam param = ApplicationParam.builder()
                // 若沒有配置環境變數,可用百鍊API Key將下行替換為:.apiKey("sk-xxx")。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .appId("APP_ID")
                .prompt("寢室公約內容")
                .bizParams(JsonUtils.parse(bizParams))
                .build();

        Application application = new Application();
        ApplicationResult result = application.call(param);
        System.out.printf("%s\n",
                result.getOutput().getText());
    }

    public static void main(String[] args) {
        try {
            appCall();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.printf("Exception: %s", e.getMessage());
            System.out.println("請參考文檔:https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code");
        }
        System.exit(0);
    }
}      

HTTP

curl

請求樣本

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/apps/APP_ID/completion \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "prompt": "寢室公約內容",
        "biz_params": 
        {
            "user_defined_params":
            {
                "<TOOL_ID>":
                    {
                    "article_index": 2
                    }
            }
        } 
    },
    "parameters":  {},
    "debug":{}
}'
APP_ID替換為實際的應用 ID。<TOOL_ID>替換為外掛程式ID。

PHP

請求樣本

<?php

# 若沒有配置環境變數,可用百鍊API Key將下行替換為:$api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
$api_key = getenv("DASHSCOPE_API_KEY");
$application_id = 'APP_ID'; // 替換為實際的應用 ID
$url = "https://dashscope-intl.aliyuncs.com/api/v1/apps/$application_id/completion";
//<TOOL_ID>替換為實際的外掛程式ID
// 構造請求資料
$data = [
    "input" => [
        'prompt' => '寢室公約內容',
        'biz_params' => [
        'user_defined_params' => [
            '<TOOL_ID>' => [
                'article_index' => 2            
                ]
            ]
        ]
    ],
];
// 將資料編碼為 JSON
$dataString = json_encode($data);

// 檢查 json_encode 是否成功
if (json_last_error() !== JSON_ERROR_NONE) {
    die("JSON encoding failed with error: " . json_last_error_msg());
}

// 初始化 cURL 對話
$ch = curl_init($url);

// 設定 cURL 選項
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $dataString);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $api_key
]);

// 執行請求
$response = curl_exec($ch);

// 檢查 cURL 執行是否成功
if ($response === false) {
    die("cURL Error: " . curl_error($ch));
}

// 擷取 HTTP 狀態代碼
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// 關閉 cURL 對話
curl_close($ch);
// 解碼響應資料
$response_data = json_decode($response, true);
// 處理響應
if ($status_code == 200) {
    if (isset($response_data['output']['text'])) {
        echo "{$response_data['output']['text']}\n";
    } else {
        echo "No text in response.\n";
    }
}else {
    if (isset($response_data['request_id'])) {
        echo "request_id={$response_data['request_id']}\n";}
    echo "code={$status_code}\n";
    if (isset($response_data['message'])) {
        echo "message={$response_data['message']}\n";} 
    else {
        echo "message=Unknown error\n";}
}
?>

Node.js

需安裝相關依賴:

npm install axios

請求樣本

const axios = require('axios');

async function callDashScope() {
    // 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey='sk-xxx'。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
    const apiKey = process.env.DASHSCOPE_API_KEY;
    const appId = 'APP_ID';// 替換為實際的應用 ID
    const pluginCode = 'TOOL_ID';// 替換為實際的外掛程式ID
    const url = `https://dashscope-intl.aliyuncs.com/api/v1/apps/${appId}/completion`;

    const data = {
        input: {
            prompt: "寢室公約內容",
            biz_params: {
                user_defined_params: {
                    [pluginCode]: {
                        // article_index為自訂外掛程式的變數,替換為實際的外掛程式變數
                        'article_index': 3
                    }
                }
            }
        },
        parameters: {},
        debug: {}
    };

    try {
        console.log("Sending request to DashScope API...");

        const response = await axios.post(url, data, {
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Content-Type': 'application/json'
            }
        });

        if (response.status === 200) {
            if (response.data.output && response.data.output.text) {
                console.log(`${response.data.output.text}`);
            }
        } else {
            console.log("Request failed:");
            if (response.data.request_id) {
                console.log(`request_id=${response.data.request_id}`);
            }
            console.log(`code=${response.status}`);
            if (response.data.message) {
                console.log(`message=${response.data.message}`);
            } else {
                console.log('message=Unknown error');
            }
        }
    } catch (error) {
        console.error(`Error calling DashScope: ${error.message}`);
        if (error.response) {
            console.error(`Response status: ${error.response.status}`);
            console.error(`Response data: ${JSON.stringify(error.response.data, null, 2)}`);
        }
    }
}
callDashScope();

C#

請求樣本

using System.Text;

class Program
{
    static async Task Main(string[] args)
    {
        // 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
        string apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY")?? throw new InvalidOperationException("DASHSCOPE_API_KEY environment variable is not set.");;
        string appId = "APP_ID";// 替換為實際的應用ID

        if (string.IsNullOrEmpty(apiKey))
        {
            Console.WriteLine("請確保設定了 DASHSCOPE_API_KEY。");
            return;
        }

        string url = $"https://dashscope-intl.aliyuncs.com/api/v1/apps/{appId}/completion";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
            string pluginCode = "TOOL_ID"; // TOOL_ID替換為實際的外掛程式 ID
            string jsonContent = $@"{{
                ""input"": {{
                    ""prompt"": ""寢室公約內容"",
                    ""biz_params"": {{
                        ""user_defined_params"": {{
                            ""{pluginCode}"": {{
                                ""article_index"": 2
                            }}
                        }}
                    }}
                }},
                ""parameters"": {{}},
                ""debug"": {{}}
            }}";

            HttpContent content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

            try
            {
                HttpResponseMessage response = await client.PostAsync(url, content);

                if (response.IsSuccessStatusCode)
                {
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Request successful:");
                    Console.WriteLine(responseBody);
                }
                else
                {
                    Console.WriteLine($"Request failed with status code: {response.StatusCode}");
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine(responseBody);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error calling DashScope: {ex.Message}");
            }
        }
    }
}

Go

請求樣本

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	// 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey := "sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
	apiKey := os.Getenv("DASHSCOPE_API_KEY")
	appId := "APP_ID"           // 替換為實際的應用 ID
	pluginCode := "TOOL_ID" // 替換為實際的外掛程式 ID

	if apiKey == "" {
		fmt.Println("請確保設定了DASHSCOPE_API_KEY。")
		return
	}

	url := fmt.Sprintf("https://dashscope-intl.aliyuncs.com/api/v1/apps/%s/completion", appId)

	// 建立請求體
	requestBody := map[string]interface{}{
		"input": map[string]interface{}{
			"prompt": "寢室公約內容",
			"biz_params": map[string]interface{}{
				"user_defined_params": map[string]interface{}{
					pluginCode: map[string]interface{}{
						"article_index": 2,
					},
				},
			},
		},
		"parameters": map[string]interface{}{},
		"debug":      map[string]interface{}{},
	}

	jsonData, err := json.Marshal(requestBody)
	if err != nil {
		fmt.Printf("Failed to marshal JSON: %v\n", err)
		return
	}

	// 建立 HTTP POST 請求
	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	if err != nil {
		fmt.Printf("Failed to create request: %v\n", err)
		return
	}

	// 佈建要求頭
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	// 發送請求
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Printf("Failed to send request: %v\n", err)
		return
	}
	defer resp.Body.Close()

	// 讀取響應
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Printf("Failed to read response: %v\n", err)
		return
	}

	// 處理響應
	if resp.StatusCode == http.StatusOK {
		fmt.Println("Request successful:")
		fmt.Println(string(body))
	} else {
		fmt.Printf("Request failed with status code: %d\n", resp.StatusCode)
		fmt.Println(string(body))
	}
}

流式輸出

通過stream實現流式輸出。

Python

請求樣本

import os
from http import HTTPStatus
from dashscope import Application
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
responses = Application.call(
            # 若沒有配置環境變數,可用百鍊API Key將下行替換為:api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
            api_key=os.getenv("DASHSCOPE_API_KEY"), 
            app_id='APP_ID',
            prompt='你是誰?',
            stream=True,  # 流式輸出
            incremental_output=True)  # 增量輸出

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'請參考文檔:https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
    else:
        print(f'{response.output.text}\n')  # 處理只輸出文本text

Java

請求樣本

// 建議dashscope SDK的版本 >= 2.15.0
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import io.reactivex.Flowable;// 流式輸出
// 智能體應用調用實現流式輸出結果

import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
      Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void streamCall() throws NoApiKeyException, InputRequiredException {
        ApplicationParam param = ApplicationParam.builder()
                // 若沒有配置環境變數,可用百鍊API Key將下行替換為:.apiKey("sk-xxx")。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 替換為實際的應用 ID
                .appId("APP_ID")
                .prompt("你是誰?")
                // 增量輸出
                .incrementalOutput(true)
                .build();
        Application application = new Application();
        // .streamCall():流式輸出內容
        Flowable<ApplicationResult> result = application.streamCall(param);
        result.blockingForEach(data -> {
            System.out.printf("%s\n",
                    data.getOutput().getText());
        });
    }
    public static void main(String[] args) {
        try {
            streamCall();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.printf("Exception: %s", e.getMessage());
            System.out.println("請參考文檔:https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code");
        }
        System.exit(0);
    }
}

HTTP

curl

請求樣本

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/apps/APP_ID/completion \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--header 'X-DashScope-SSE: enable' \
--data '{
    "input": {
        "prompt": "你是誰?"

    },
    "parameters":  {
        "incremental_output":true
    },
    "debug": {}
}'
APP_ID替換為實際的應用 ID。

PHP

請求樣本

<?php

// 若沒有配置環境變數,可用百鍊API Key將下行替換為:$api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
$api_key = getenv("DASHSCOPE_API_KEY");
$application_id = 'APP_ID'; // 替換為實際的應用 ID

$url = "https://dashscope-intl.aliyuncs.com/api/v1/apps/$application_id/completion";

// 構造請求資料
$data = [
    "input" => [
        'prompt' => '你是誰?'],
    "parameters" => [
        'incremental_output' => true]];// 增量輸出
// 將資料編碼為 JSON
$dataString = json_encode($data);

// 檢查 json_encode 是否成功
if (json_last_error() !== JSON_ERROR_NONE) {
    die("JSON encoding failed with error: " . json_last_error_msg());
}

// 初始化 cURL 對話
$ch = curl_init($url);

// 設定 cURL 選項
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $dataString);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, false); // 不返回傳輸的資料
curl_setopt($ch, CURLOPT_WRITEFUNCTION, function ($ch, $string) {
    echo $string; // 處理流式資料
    return strlen($string);
});
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $api_key,
    'X-DashScope-SSE: enable' // 流式輸出
]);

// 執行請求
$response = curl_exec($ch);

// 檢查 cURL 執行是否成功
if ($response === false) {
    die("cURL Error: " . curl_error($ch));
}

// 擷取 HTTP 狀態代碼
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// 關閉 cURL 對話
curl_close($ch);

if ($status_code != 200) {
    echo "HTTP Status Code: $status_code\n";
    echo "Request Failed.\n";
}
?>

Node.js

需安裝相關依賴:

npm install axios

請求樣本

1.輸出完整響應

const axios = require('axios');

async function callDashScope() {
    //若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey='sk-xxx'。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
    const apiKey = process.env.DASHSCOPE_API_KEY;
    const appId = 'APP_ID';// 替換為實際的應用 ID

    const url = `https://dashscope-intl.aliyuncs.com/api/v1/apps/${appId}/completion`;

    const data = {
        input: {
            prompt: "你是誰?"
        },
        parameters: {
            'incremental_output' : 'true' // 增量輸出
        },
        debug: {}
    };

    try {
        console.log("Sending request to DashScope API...");

        const response = await axios.post(url, data, {
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Content-Type': 'application/json',
                'X-DashScope-SSE': 'enable' // 流式輸出
            },
            responseType: 'stream' // 用於處理流式響應
        });

        if (response.status === 200) {
            // 處理流式響應
            response.data.on('data', (chunk) => {
                console.log(`Received chunk: ${chunk.toString()}`);
            });
        } else {
            console.log("Request failed:");
            if (response.data.request_id) {
                console.log(`request_id=${response.data.request_id}`);
            }
            console.log(`code=${response.status}`);
            if (response.data.message) {
                console.log(`message=${response.data.message}`);
            } else {
                console.log('message=Unknown error');
            }
        }
    } catch (error) {
        console.error(`Error calling DashScope: ${error.message}`);
        if (error.response) {
            console.error(`Response status: ${error.response.status}`);
            console.error(`Response data: ${JSON.stringify(error.response.data, null, 2)}`);
        }
    }
}

callDashScope();

可展開摺疊面板查看具體內容:

2.只輸出text欄位內容

const axios = require('axios');
const { Transform } = require('stream');

async function callDashScope() {
    //若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey='sk-xxx'。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
    const apiKey = process.env.DASHSCOPE_API_KEY;
    const appId = 'APP_ID'; // 替換為實際的應用 ID

    const url = `https://dashscope.aliyuncs.com/api/v1/apps/${appId}/completion`;

    const data = {
        input: { prompt: "你是誰?" },
        parameters: { incremental_output: true }, // 增量輸出
        debug: {}
    };

    try {
        console.log("Sending request to DashScope API...");

        const response = await axios.post(url, data, {
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Content-Type': 'application/json',
                'X-DashScope-SSE': 'enable' // 流式輸出
            },
            responseType: 'stream' // 用於處理流式響應
        });

        if (response.status === 200) {
            // // 處理流式響應 SSE協議解析轉換流
            const sseTransformer = new Transform({
                transform(chunk, encoding, callback) {
                    this.buffer += chunk.toString();
                    
                    // 按SSE事件分割(兩個分行符號)
                    const events = this.buffer.split(/\n\n/);
                    this.buffer = events.pop() || ''; // 保留未完成部分
                    
                    events.forEach(eventData => {
                        const lines = eventData.split('\n');
                        let textContent = '';
                        
                        // 解析事件內容
                        lines.forEach(line => {
                            if (line.startsWith('data:')) {
                                try {
                                    const jsonData = JSON.parse(line.slice(5).trim());
                                    if (jsonData.output?.text) {
                                        textContent = jsonData.output.text;
                                    }
                                } catch(e) {
                                    console.error('JSON解析錯誤:', e.message);
                                }
                            }
                        });

                        if (textContent) {
                            // 添加分行符號並推送
                            this.push(textContent + '\n');
                        }
                    });
                    
                    callback();
                },
                flush(callback) {
                    if (this.buffer) {
                        this.push(this.buffer + '\n');
                    }
                    callback();
                }
            });
            sseTransformer.buffer = '';

            // 管道處理
            response.data
                .pipe(sseTransformer)
                .on('data', (textWithNewline) => {
                    process.stdout.write(textWithNewline); // 自動換行輸出
                })
                .on('end', () => console.log(""))
                .on('error', err => console.error("管道錯誤:", err));

        } else {
            console.log("請求失敗,狀態代碼:", response.status);
            response.data.on('data', chunk => console.log(chunk.toString()));
        }
    } catch (error) {
        console.error(`API調用失敗: ${error.message}`);
        if (error.response) {
            console.error(`狀態代碼: ${error.response.status}`);
            error.response.data.on('data', chunk => console.log(chunk.toString()));
        }
    }
}

callDashScope();

C#

請求樣本

using System.Net;
using System.Text;

class Program
{
    static async Task Main(string[] args)
    {
        //若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
        string apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY") ?? throw new InvalidOperationException("DASHSCOPE_API_KEY environment variable is not set.");
        string appId = "APP_ID"; // 替換為實際的應用ID
        string url = $"https://dashscope.aliyuncs.com/api/v1/apps/{appId}/completion";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
            client.DefaultRequestHeaders.Add("X-DashScope-SSE", "enable");

            string jsonContent = @"{
                ""input"": {
                    ""prompt"": ""你是誰""
                },
                ""parameters"": {""incremental_output"": true},
                ""debug"": {}
            }";

            HttpContent content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

            Console.WriteLine(DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss:fff"));
            try
            {
                var request = new HttpRequestMessage(HttpMethod.Post, url);
                request.Content = content;

                HttpResponseMessage response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
                

                if (response.IsSuccessStatusCode)
                {
                    Console.WriteLine("Request successful:");
                    Console.WriteLine(DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss:fff"));
                    using (var stream = await response.Content.ReadAsStreamAsync())
                    using (var reader = new StreamReader(stream))
                    {
                        string? line; // 聲明為可Null 字元串
                        while ((line = await reader.ReadLineAsync()) != null)
                        {
                            if (line.StartsWith("data:"))
                            {
                                string data = line.Substring(5).Trim();
                                Console.WriteLine(data);
                                Console.WriteLine(DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss:fff"));
                            }
                        }
                    }
                }
                else
                {
                    Console.WriteLine($"Request failed with status code: {response.StatusCode}");
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine(responseBody);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error calling DashScope: {ex.Message}");
            }
        }
    }
}

Go

請求樣本

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
	"time"
)

func main() {
	// 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey := "sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
	apiKey := os.Getenv("DASHSCOPE_API_KEY")
	appId := "APP_ID" // 替換為實際的應用 ID

	if apiKey == "" {
		fmt.Println("請確保設定了DASHSCOPE_API_KEY。")
		return
	}

	url := fmt.Sprintf("https://dashscope.aliyuncs.com/api/v1/apps/%s/completion", appId)

	// 建立請求體,其中incremental_output為是否開啟流式響應
	requestBody := map[string]interface{}{
		"input": map[string]string{
			"prompt": "你是誰?",
		},
		"parameters": map[string]interface{}{
			"incremental_output": true,
		},
		"debug": map[string]interface{}{},
	}

	jsonData, err := json.Marshal(requestBody)
	if err != nil {
		fmt.Printf("Failed to marshal JSON: %v\n", err)
		return
	}

	// 建立 HTTP POST 請求
	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	if err != nil {
		fmt.Printf("Failed to create request: %v\n", err)
		return
	}

	// 佈建要求頭,其中X-DashScope-SSE設定為enable,表示開啟流式響應
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-DashScope-SSE", "enable")

	// 發送請求
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Printf("Failed to send request: %v\n", err)
		return
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		fmt.Printf("Request failed with status code: %d\n", resp.StatusCode)
		body, _ := io.ReadAll(resp.Body)
		fmt.Println(string(body))
		return
	}

	// 處理流式響應
	reader := io.Reader(resp.Body)
	buf := make([]byte, 1024)
	for {
		n, err := reader.Read(buf)
		if n > 0 {
			data := string(buf[:n])
			lines := strings.Split(data, "\n")
			for _, line := range lines {
				line = strings.TrimSpace(line)
				if len(line) >= 5 && line[:5] == "data:" {
					timestamp := time.Now().Format("2006-01-02 15:04:05.000")
					fmt.Printf("%s: %s\n", timestamp, line[5:])
				} else if len(line) > 0 {
					fmt.Println(line)
				}
			}
		}
		if err != nil {
			if err == io.EOF {
				break
			}
			fmt.Printf("Error reading response: %v\n", err)
			break
		}
	}
}

檢索知識庫

調用智能體應用時,通過rag_options實現知識庫檢索。

Python

請求樣本

import os
from http import HTTPStatus
# 建議dashscope SDK 的版本 >= 1.20.11
from dashscope import Application
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

response = Application.call(
    # 若沒有配置環境變數,可用百鍊API Key將下行替換為:api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
    api_key=os.getenv("DASHSCOPE_API_KEY"), 
    app_id='APP_ID',  # 應用ID替換APP_ID
    prompt='請幫我推薦一款3000元以下的手機',
    rag_options={
        "pipeline_ids": ["PIPELINE_ID1,PIPELINE_ID2"],  # 替換為實際的知識庫ID,逗號隔開多個
    }
)

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'請參考文檔:https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code')
else:
    print('%s\n' % (response.output.text))  # 處理只輸出文本text
    # print('%s\n' % (response.usage))

Java

請求樣本

// 建議dashscope SDK 的版本 >= 2.16.8;
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import java.util.Arrays;

import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void streamCall() throws NoApiKeyException, InputRequiredException {
        ApplicationParam param = ApplicationParam.builder()
                // 若沒有配置環境變數,可用百鍊API Key將下行替換為:.apiKey("sk-xxx")。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .appId("APP_ID") // 替換為實際的應用ID
                .prompt("請幫我推薦一款3000元左右的手機")
                .ragOptions(RagOptions.builder()
                        // 替換為實際指定的知識庫ID,逗號隔開多個
                        .pipelineIds(Arrays.asList("PIPELINES_ID1", "PIPELINES_ID2"))
                        .build())
                .build();

        Application application = new Application();
        ApplicationResult result = application.call(param);
        System.out.printf("%s\n",
                result.getOutput().getText());// 處理只輸出文本text
    }

    public static void main(String[] args) {
        try {
            streamCall();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.printf("Exception: %s", e.getMessage());
            System.out.println("請參考文檔:https://www.alibabacloud.com/help/zh/model-studio/developer-reference/error-code");
        }
        System.exit(0);
    }
}

HTTP

curl

請求樣本

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/apps/{APP_ID}/completion \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "prompt": "請幫我推薦一款3000元以下的手機"
    },
    "parameters":  {
                    "rag_options" : {
                    "pipeline_ids":["PIPELINE_ID1"]}
    },
    "debug": {}
}'
APP_ID替換為實際的應用 ID,PIPELINE_ID1替換為指定的知識庫ID。

PHP

請求樣本

<?php
# 若沒有配置環境變數,可用百鍊API Key將下行替換為:$api_key="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
$api_key = getenv("DASHSCOPE_API_KEY");
$application_id = 'APP_ID'; // 替換為實際的應用 ID

$url = "https://dashscope-intl.aliyuncs.com/api/v1/apps/$application_id/completion";

// 構造請求資料
$data = [
    "input" => [
        'prompt' => '請幫我推薦一款3000元以下的手機'
    ],
    "parameters" => [
        'rag_options' => [
            'pipeline_ids' => ['PIPELINE_ID1','PIPELINE_ID2']//替換為指定的知識庫ID,逗號隔開多個
        ]
    ]
];
// 將資料編碼為 JSON
$dataString = json_encode($data);

// 檢查 json_encode 是否成功
if (json_last_error() !== JSON_ERROR_NONE) {
    die("JSON encoding failed with error: " . json_last_error_msg());
}

// 初始化 cURL 對話
$ch = curl_init($url);

// 設定 cURL 選項
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $dataString);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $api_key
]);

// 執行請求
$response = curl_exec($ch);

// 檢查 cURL 執行是否成功
if ($response === false) {
    die("cURL Error: " . curl_error($ch));
}

// 擷取 HTTP 狀態代碼
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// 關閉 cURL 對話
curl_close($ch);
// 解碼響應資料
$response_data = json_decode($response, true);
// 處理響應
if ($status_code == 200) {
    if (isset($response_data['output']['text'])) {
        echo "{$response_data['output']['text']}\n";
    } else {
        echo "No text in response.\n";
    }
}else {
    if (isset($response_data['request_id'])) {
        echo "request_id={$response_data['request_id']}\n";}
    echo "code={$status_code}\n";
    if (isset($response_data['message'])) {
        echo "message={$response_data['message']}\n";} 
    else {
        echo "message=Unknown error\n";}
}
?>

Node.js

需安裝相關依賴:

npm install axios

請求樣本

const axios = require('axios');
async function callDashScope() {
    // 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey='sk-xxx'。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
    const apiKey = process.env.DASHSCOPE_API_KEY;
    const appId = 'APP_ID';//替換為實際的應用 ID

    const url = `https://dashscope-intl.aliyuncs.com/api/v1/apps/${appId}/completion`;

    const data = {
        input: {
            prompt: "請幫我推薦一款3000元以下的手機"
        },
        parameters: {
            rag_options:{
                pipeline_ids:['PIPELINE_ID1','PIPELINE_ID2']  // 替換為指定的知識庫ID,多個請用逗號隔開
            }
        },
        debug: {}
    };

    try {
        const response = await axios.post(url, data, {
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Content-Type': 'application/json'
            }
        });

        if (response.status === 200) {
            console.log(`${response.data.output.text}`);
        } else {
            console.log(`request_id=${response.headers['request_id']}`);
            console.log(`code=${response.status}`);
            console.log(`message=${response.data.message}`);
        }
    } catch (error) {
        console.error(`Error calling DashScope: ${error.message}`);
        if (error.response) {
            console.error(`Response status: ${error.response.status}`);
            console.error(`Response data: ${JSON.stringify(error.response.data, null, 2)}`);
        }
    }
}

callDashScope();

C#

請求樣本

using System.Text;

class Program
{
    static async Task Main(string[] args)
    {
        // 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey="sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
        string apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY")?? throw new InvalidOperationException("DASHSCOPE_API_KEY environment variable is not set.");;
        string appId = "APP_ID";// 替換為實際的應用ID
        // PIPELINE_ID1替換為指定的知識庫ID
        if (string.IsNullOrEmpty(apiKey))
        {
            Console.WriteLine("請確保設定了 DASHSCOPE_API_KEY。");
            return;
        }

        string url = $"https://dashscope-intl.aliyuncs.com/api/v1/apps/{appId}/completion";
        
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
            string jsonContent = $@"{{
                ""input"": {{
                    ""prompt"": ""請幫我推薦一款3000元以下的手機""
                }},
                ""parameters"": {{
                    ""rag_options"" : {{
                        ""pipeline_ids"":[""PIPELINE_ID1""]
                    }}
                }},
                ""debug"": {{}}
            }}";

            HttpContent content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

            try
            {
                HttpResponseMessage response = await client.PostAsync(url, content);

                if (response.IsSuccessStatusCode)
                {
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine(responseBody);
                }
                else
                {
                    Console.WriteLine($"Request failed with status code: {response.StatusCode}");
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine(responseBody);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error calling DashScope: {ex.Message}");
            }
        }
    }
}

Go

請求樣本

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	// 若沒有配置環境變數,可用百鍊API Key將下行替換為:apiKey := "sk-xxx"。但不建議在生產環境中直接將API Key寫入程式碼到代碼中,以減少API Key泄露風險。
	apiKey := os.Getenv("DASHSCOPE_API_KEY")
	appId := "APP_ID" // 替換為實際的應用 ID

	if apiKey == "" {
		fmt.Println("請確保設定了DASHSCOPE_API_KEY。")
		return
	}

	url := fmt.Sprintf("https://dashscope-intl.aliyuncs.com/api/v1/apps/%s/completion", appId)

	// 建立請求體
	requestBody := map[string]interface{}{
		"input": map[string]string{
			"prompt": "請幫我推薦一款3000元以下的手機",
		},
		"parameters": map[string]interface{}{
			"rag_options": map[string]interface{}{
				"pipeline_ids": []string{"PIPELINE_ID1"}, // 替換為指定的知識庫ID
			},
		},
		"debug": map[string]interface{}{},
	}

	jsonData, err := json.Marshal(requestBody)
	if err != nil {
		fmt.Printf("Failed to marshal JSON: %v\n", err)
		return
	}

	// 建立 HTTP POST 請求
	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	if err != nil {
		fmt.Printf("Failed to create request: %v\n", err)
		return
	}

	// 佈建要求頭
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	// 發送請求
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Printf("Failed to send request: %v\n", err)
		return
	}
	defer resp.Body.Close()

	// 讀取響應
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Printf("Failed to read response: %v\n", err)
		return
	}

	// 處理響應
	if resp.StatusCode == http.StatusOK {
		fmt.Println("Request successful:")
		fmt.Println(string(body))
	} else {
		fmt.Printf("Request failed with status code: %d\n", resp.StatusCode)
		fmt.Println(string(body))
	}
}

查看檢索過程資訊:調用時在代碼中添加has_thoughts並設定為True,則檢索的過程資訊會在outputthoughts欄位中返回。

app_id string (必選)

應用標識。

可在應用管理頁面的應用卡片上擷取應用 ID。

Java SDK中為 appId。通過 HTTP 調用時,請將實際的應用 ID 放入 URL 中,替換APP_ID

prompt string (必選)

使用者的輸入指令,用於指導應用產生回複。

通過 HTTP 調用時,請將 prompt 放入 input 對象中。

session_id string (可選)

歷史對話標識。

傳入session_id時,請求將自動攜帶雲端儲存的對話歷史。此時必須傳遞prompt

該 ID 在連續 1 小時內無任何請求後將自動失效。

Java SDK 中為 setSessionId。通過 HTTP 調用時,請將 session_id 放入 input 對象中。

messages array (可選)

傳遞給大模型的上下文,按對話順序排列。

當使用messages參數實現多輪對話時,無需傳遞promptsession_id

若同時傳入session_idmessages,則大模型優先使用messages中的內容,忽略session_idprompt

通過HTTP調用時,請將 messages 放入 input 對象中。
使用該參數,Python Dashscope SDK的版本至少應為1.20.14,Java Dashscope SDK的版本至少應為2.17.0。

訊息類型

System Message object(可選)

系統訊息,用於設定大模型的角色、語氣、任務目標或約束條件等。一般放在messages數組的第一位。

屬性

content string (必選)

系統指令,用於明確模型的角色、行為規範、回答風格和任務約束等。

role string (必選)

系統訊息的角色,固定為system

User Message object(必選)

使用者訊息,用於向模型傳遞問題、指令或上下文等。

屬性

content string (必選)

訊息內容。

屬性

text string (必選)

輸入的文本。

role string (必選)

使用者訊息的角色,固定為user

Assistant Message object(可選)

模型的回複。通常用於在多輪對話中作為上下文回傳給模型。

屬性

content string (必選)

模型回複的常值內容。

role string (必選)

助手訊息的角色,固定為assistant

workspace string (可選)

業務空間標識。相關文檔:擷取Workspace ID

僅調用子業務空間的應用時需傳遞workspace ID

通過 HTTP 調用時,請指定Header中的 X-DashScope-WorkSpace

stream boolean(可選) 預設值為 false

是否以流式輸出方式回複。

推薦設定為true,可提升閱讀體驗並降低逾時風險。

參數值:

  • false(預設):模型產生全部內容後一次性返回;

  • true(推薦):邊產生邊輸出,每產生一部分內容即返回一個資料區塊(chunk)。需即時逐個讀取這些塊以拼接完整回複。

通過Java SDK實現流式輸出請通過streamCall介面調用;通過HTTP實現流式輸出請在Header中指定X-DashScope-SSEenable

incremental_output boolean(可選)預設值為 false

在流式輸出模式下是否開啟增量輸出。

推薦設定為true,可提升閱讀體驗。

參數值:

  • false(預設):每次輸出當前已經產生的整個序列,最後一次輸出為產生的完整結果。

    I
    I like
    I like apple
    I like apple.
  • true(推薦):增量輸出,即後續輸出內容不包含已輸出的內容。需要即時地逐個讀取這些片段以獲得完整的結果。

    I
    like
    apple
    .
Java SDK中為incrementalOutput通過HTTP調用時,請將incremental_output放入parameters對象中。

flow_stream_mode string(可選)預設值為full_thoughts

工作流程應用的流式輸出模式。

參數值:

  • message_format(推薦):

    message欄位輸出指定節點(流程輸出節點或結束節點)的結果。

    重要

    在控制台應用中開啟目標節點的流式輸出開關,即可流式返回結果;未開啟時,一次性返回該節點的最終結果。

    Java SDK 中為FlowStreamMode.MESSAGE_FORMAT
  • full_thoughts(預設):

    thoughts欄位輸出所有節點的結果。

    重要

    使用此模式時,必須同時將 has_thoughts 參數設定為 true

    Java SDK 中為FlowStreamMode.FULL_THOUGHTS
  • agent_format

    text 欄位輸出指定節點(大模型節點或結束節點)的結果。

    在控制台應用中開啟目標節點的結果返回開關,即可流式返回結果。

    重要

    請勿在並行節點上使用此模式,可能導致內容混雜。請確保開啟開關的節點有明確的執行順序。

    Java SDK 中為FlowStreamMode.AGENT_FORMAT
Python SDK 版本至少為1.24.0,Java SDK 版本至少為2.21.0。通過HTTP調用時,請將flow_stream_mode放入parameters對象中。

biz_params object (可選)

應用通過自訂變數、節點或外掛程式傳遞參數時,使用該欄位進行傳遞。

Java SDK 中為 bizParams。通過HTTP調用時,請將 biz_params 放入 input 對象中。

工作流程應用開始節點的自訂變數直接傳遞,樣本:

biz_params = {"city": "杭州"}

智能體應用通過以下欄位傳遞提示詞變數或外掛程式變數參數:

屬性

user_defined_params object (可選)

表示自訂外掛程式參數資訊。

一個應用內添加的外掛程式不可重複,且上限 10 個。

屬性

tool_id string (可選)

外掛程式 ID,可在外掛程式卡片上擷取。

${plugin_params} string(可選)

對象最內側包含的多個索引值對。每個索引值對錶示使用者自訂的待傳遞參數名及其指定值。如:

"article_index": 2

使用步驟:

  1. 在應用內關聯指定外掛程式,並發布應用。

  2. API調用通過此參數傳遞外掛程式資訊。

可提供多個索引值對,其中每個鍵為外掛程式的 TOOL_ID,值為該外掛程式所需的參數對象。樣本:

"user_defined_params": {
        "<TOOL_ID>": {
            "article_index": 2},
        "<TOOL_ID>": {
            "article_index": 8}
        }

user_defined_tokens object(可選)

表示自訂外掛程式的使用者級鑒權資訊。

一個應用內添加的外掛程式不可重複,且上限 10 個。

屬性

tool_id string (可選)

外掛程式 ID,可在外掛程式卡片中擷取。通過<TOOL_ID>欄位傳遞。

user_token string (可選)

傳遞該外掛程式需要的使用者鑒權資訊,如實際DASHSCOPE_API_KEY的值

使用步驟:

  1. 在應用內關聯指定外掛程式,並發布應用。

  2. API調用通過此參數傳遞外掛程式使用者級鑒權資訊。

可提供多個索引值對,其中每個鍵為外掛程式的 TOOL_ID,值為user_token 對象。

has_thoughts boolean (可選)預設值為 false

是否輸出外掛程式調用、知識檢索的過程,在thoughts欄位中查看。

參數值:

  • True:輸出。

  • False(預設):不輸出。

Java SDK 中為 hasThoughts。通過 HTTP 調用時,請將 has_thoughts 放入 parameters 對象中。

rag_options array (可選)

用於配置與檢索相關的參數。包括但不限於對指定的知識庫或文檔進行檢索。

說明

智能體應用支援此參數。

Java SDK 中為 ragOptions。通過HTTP調用時,請將 rag_options 放入 parameters 對象中。

屬性

pipeline_ids array 必選)

包含一個或多個知識庫 ID 的列表。上限5個。

檢索指定知識庫內的所有文檔。

擷取方式:

  • 知識庫頁面擷取知識庫 ID;

  • 或通過CreateIndex介面(僅支援非結構化知識庫)返回的Data.Id

Java SDK 中為pipelineIds

file_ids array (可選)

包含一個或多個非結構化文檔 ID 的列表。上限5個。

檢索指定知識庫內的非結構化文檔。

傳入文檔 ID 時,必須同時在 pipeline_ids 欄位中傳入這些文檔所屬的知識庫 ID。

擷取方式:

Java SDK 中為 fileIds

metadata_filter object (可選)

非結構化文檔的中繼資料。

檢索指定知識庫內具備該中繼資料的非結構化文檔。

傳入中繼資料時,必須同時在 pipeline_ids 欄位中傳入這些中繼資料所屬的知識庫 ID。

查看方式:

  • 訪問知識庫頁面,單擊知識庫卡片的查看詳情 > Meta資訊查看。

  • 或通過ListChunks介面擷取。

Java SDK 中為 metadataFilter

tags array (可選)

包含一個或多個非結構化文檔標籤的列表。

檢索具備該標籤的非結構化文檔。

查看方式:

響應對象

單輪對話響應樣本

{
    "output": {
        "finish_reason": "stop",
        "session_id": "6105c965c31b40958a43dc93c28c7a59",
        "text": "我是通義千問,由阿里雲開發的AI助手。我被設計用來回答各種問題、提供資訊和與使用者進行對話。有什麼我可以協助你的嗎?"
    },
    "usage": {
        "models": [
            {
                "output_tokens": 36,
                "model_id": "qwen-plus",
                "input_tokens": 74
            }
        ]
    },
    "request_id": "f97ee37d-0f9c-9b93-b6bf-bd263a232bf9"
}

指定知識庫響應樣本

調用應用知識庫功能時,想要輸出召迴文檔中被模型引用的文檔資訊,可在百鍊控制台的智能體應用內,單擊檢索配置,開啟展示回答來源開關,發布應用。

{
    "text": "根據您的預算,我推薦您考慮百鍊 Zephyr Z9。這款手機輕巧便攜,擁有6.4英寸1080 x 2340像素的螢幕,搭配128GB儲存與6GB RAM,非常適合日常使用<ref>[1]</ref>。此外,它還配備了4000mAh電池以及30倍數字變焦鏡頭,能夠捕捉遠處細節,價格區間在2499-2799元之間,完全符合您的預算需求<ref>[1]</ref>。",
    "finish_reason": "stop",
    "session_id": "6c1d47fa5eca46b2ad0668c04ccfbf13",
    "thoughts": null,
    "doc_references": [
        {
            "index_id": "1",
            "title": "百鍊手機產品介紹",
            "doc_id": "file_7c0e9abee4f142f386e488c9baa9cf38_10317360",
            "doc_name": "百鍊系列手機產品介紹",
            "doc_url": null,
            "text": "【文檔名】:百鍊系列手機產品介紹\n【標題】:百鍊手機產品介紹\n【本文】:參考售價:5999- 6499。百鍊 Ace Ultra ——遊戲玩家之選:配備 6.67英寸 1080 x 2400像素螢幕,內建 10GB RAM與 256GB儲存,確保遊戲運行絲滑無阻。百鍊 Ace Ultra ——遊戲玩家之選:配備 6.67英寸 1080 x 2400像素螢幕,內建 10GB RAM與 256GB儲存,確保遊戲運行絲滑無阻。5500mAh電池搭配液冷散熱系統,長時間遊戲也能保持冷靜。高動態雙擴音器,沈浸式音效升級遊戲體驗。參考售價:3999- 4299。百鍊 Zephyr Z9 ——輕薄便攜的藝術:輕巧的 6.4英寸 1080 x 2340像素設計,搭配 128GB儲存與 6GB RAM,日常使用遊刃有餘。4000mAh電池確保一天無憂,30倍數字變焦鏡頭捕捉遠處細節,輕薄而不失強大。參考售價:2499- 2799。百鍊 Flex Fold+ ——摺疊屏新紀元:集創新與奢華於一身,主屏 7.6英寸 1800 x 2400像素與外屏 4.7英寸 1080 x 2400像素,多角度自由懸停設計,滿足不同情境需求。512GB儲存、12GB RAM,加之 4700mAh電池與 UTG超薄柔性玻璃,開啟摺疊屏時代新篇章。此外,這款手機還支援雙卡雙待、衛星通話,協助您在世界各地都能暢聯通話。參考零售價:9999- 10999。\n",
            "biz_id": null,
            "images": [

            ],
            "page_number": [
                0]
        }]
}

異常響應樣本

在訪問請求出錯的情況下,輸出的結果中會通過 code 和 message 指明錯誤原因。

此處展示未傳入正確API-KEY的異常響應樣本。

request_id=1d14958f-0498-91a3-9e15-be477971967b, 
code=401, 
message=Invalid API-key provided.

status_code string

返回的狀態代碼。

200表示請求成功,否則表示請求失敗。

請求失敗可通過code擷取錯誤碼、message擷取錯誤詳細資料。

Java SDK不會返回該參數。調用失敗會拋出異常,異常資訊為status_codemessage的內容。

request_id string

本次調用的唯一識別碼。

Java SDK返回參數為requestId

code string

表示錯誤碼,調用成功時為空白值。

只有Python SDK返回該參數。

message string

表示錯誤詳細資料,請求成功則忽略。

只有Python SDK返回該參數。

output object

調用結果資訊。

output屬性

text string

模型產生的回複內容。

finish_reason string

完成原因。

stop為自然結束(遇預設標記),null為強制中斷(如達到最大長度限制或手動停止)。

session_id string

目前的交談的唯一標識。

在後續請求中傳入,可攜帶歷史對話記錄。

thoughts array

調用時將has_thoughts參數設定為True,即可在thoughts中查看外掛程式調用、知識檢索的過程,或深度思考模型的思考過程。

thoughts屬性

thought string

模型的思考過程。

當在控制台智能體應用中選擇了深度思考模型,並成功發布應用後,若在 API 呼叫時將 has_thoughts 參數設為 True,則模型的思考過程將在此欄位中返回。

reasoningContent string

模型的思考過程。

當在控制台工作流程應用中選擇了深度思考模型,並成功發布應用後,若在 API 呼叫時將 has_thoughts 參數設為 True,則模型的思考過程將在此欄位中返回。

action_type string

大模型返回的執行步驟類型。如API表示執行API外掛程式、agentRag表示執行知識檢索、reasoning表示執行深度思考模型的思考過程。

action_name string

執行的action名稱,如知識檢索、API外掛程式、思考過程。

action string

執行的步驟。

action_input_stream string

入參的流式結果。

action_input string

外掛程式的輸入參數。

observation string

檢索或外掛程式的過程。

doc_references array

檢索的召迴文檔中被模型引用的文檔資訊。

在百鍊控制台的智能體應用內,開啟展示回答來源開關並發布應用,doc_references才可能包含有效資訊。

doc_references屬性

index_id string

模型引用的召迴文檔索引,如[1]。

title string

模型引用的文本切片標題。

doc_id string

模型引用的文檔ID。

doc_name string

模型引用的文檔名。

text string

模型引用的具體常值內容。

biz_id string

模型引用的業務關聯標識。

images array

模型引用的圖片URL列表。

page_number array

模型引用的文本切片的頁碼。

此參數僅支援在2024年10月25日後建立的知識庫。
如需使用該參數,Python Dashscope SDK的版本至少應為1.20.14;Java Dashscope SDK的版本至少應為2.16.10。

workflow_message object

包含工作流程節點狀態和訊息的對象。

workflow_message屬性

node_status string

當前節點的執行狀態,例如 executing(執行中)。

node_type string

當前節點的類型,例如End(結束節點)。

node_msg_seq_id integer

節點內訊息的序號。

node_name string

當前節點的名稱,例如結束。

message object

包含具體訊息內容的對象。

message屬性

content string

訊息的具體常值內容。

role string

訊息寄件者的角色,例如Assistant。

node_is_completed boolean

指示當前節點是否已完成執行。true表示完成,false 表示未完成。

node_id string

當前節點的唯一標識ID。

usage object

表示本次請求使用的資料資訊。

usage屬性

models array

本次調用的模型資訊。

models屬性

model_id string

本次應用調用到的模型 ID。

input_tokens integer

使用者輸入文本轉換成Token後的長度。

output_tokens integer

模型產生回複轉換為Token後的長度。

錯誤碼

如果調用失敗並返回報錯資訊,請參閱錯誤資訊進行解決。