All Products
Search
Document Center

Alibaba Cloud Model Studio:Qwen API reference

Last Updated:Nov 27, 2024

This topic describes the input and output parameters of the Qwen API.

For more information about the models and how to select and use them, see Text generation.

You can call the Qwen API with the OpenAI SDK or the DashScope SDK.

OpenAI

Public cloud

base_url for SDK: https://dashscope-intl.aliyuncs.com/compatible-mode/v1

HTTP endpoint: POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions

You must first obtain an API Key and set the API Key as an environment variable. If using the OpenAI SDK, you must also install the OpenAI SDK.

The request body

Text input

Python

Sample request

import os
from openai import OpenAI

client = OpenAI(
    # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"), 
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-plus", # Model list: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
    messages=[
        {'role': 'system', 'content': 'You are a helpful assistant.'},
        {'role': 'user', 'content': 'Who are you?'}],
    )
    
print(completion.model_dump_json())

Sample response

{
  "id": "chatcmpl-0da38de9-5d2b-916d-9c6a-7af95993e275",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "I am Qwen, an AI assistant developed by Alibaba Cloud. I am designed to answer various questions, provide information, and engage in conversations with users. Is there anything I can help you with?",
        "role": "assistant",
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1721044114,
  "model": "qwen-plus",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 36,
    "prompt_tokens": 22,
    "total_tokens": 58
  }
}

Node.js

Sample request

import OpenAI from "openai";

const openai = new OpenAI(
    {
        // If the environment variable is not configured, replace the following line with: apiKey: "sk-xxx",
        apiKey: process.env.DASHSCOPE_API_KEY,
        baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
    }
);
const completion = await openai.chat.completions.create({
    model: "qwen-plus",  //Model list: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
    messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "Who are you?" }
    ],
});
console.log(JSON.stringify(completion))

Sample response

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "I am a large language model from Alibaba Cloud, and my name is Qwen."
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 22,
        "completion_tokens": 17,
        "total_tokens": 39
    },
    "created": 1728455191,
    "system_fingerprint": null,
    "model": "qwen-plus",
    "id": "chatcmpl-3a8c00cc-9c9f-9aba-b2d9-dc431e27d1b5"
}

HTTP

Sample request

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user", 
            "content": "Who are you?"
        }
    ]
}'
<?php
// Set the request URL
$url = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions';
// If the environment variable is not configured, replace the following line with: $apiKey = "sk-xxx";
$apiKey = getenv('DASHSCOPE_API_KEY');
// Set the request header
$headers = [
    'Authorization: Bearer '.$apiKey,
    'Content-Type: application/json'
];
// Set the request body
$data = [
    // Model list: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
    "model" => "qwen-plus",
    "messages" => [
        [
            "role" => "system",
            "content" => "You are a helpful assistant."
        ],
        [
            "role" => "user",
            "content" => "Who are you?"
        ]
    ]
];
// Initialize cURL session
$ch = curl_init();
// Set cURL options
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
// Execute cURL session
$response = curl_exec($ch);
// Check for errors
if (curl_errno($ch)) {
    echo 'Curl error: ' . curl_error($ch);
}
// Close cURL resource
curl_close($ch);
// Output the response
echo $response;
?>
using System.Net.Http.Headers;
using System.Text;

class Program
{
    private static readonly HttpClient httpClient = new HttpClient();

    static async Task Main(string[] args)
    {
        // If the environment variable is not configured, replace the following line with: string? apiKey = "sk-xxx";
        string? apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY");

        if (string.IsNullOrEmpty(apiKey))
        {
            Console.WriteLine("API Key is not set. Please ensure the environment variable 'DASHSCOPE_API_KEY' is set.");
            return;
        }

        // Set the request URL and content
        string url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions";
        // Model list: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
        string jsonContent = @"{
            ""model"": ""qwen-plus"",
            ""messages"": [
                {
                    ""role"": ""system"",
                    ""content"": ""You are a helpful assistant.""
                },
                {
                    ""role"": ""user"", 
                    ""content"": ""Who are you?""
                }
            ]
        }";

        // Send the request and get the response
        string result = await SendPostRequestAsync(url, jsonContent, apiKey);

        // Output the result
        Console.WriteLine(result);
    }

    private static async Task<string> SendPostRequestAsync(string url, string jsonContent, string apiKey)
    {
        using (var content = new StringContent(jsonContent, Encoding.UTF8, "application/json"))
        {
            // Set the request header
            httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
            httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

            // Send the request and get the response
            HttpResponseMessage response = await httpClient.PostAsync(url, content);

            // Handle the response
            if (response.IsSuccessStatusCode)
            {
                return await response.Content.ReadAsStringAsync();
            }
            else
            {
                return $"Request failed: {response.StatusCode}";
            }
        }
    }
}
package main

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

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}
type RequestBody struct {
	Model    string    `json:"model"`
	Messages []Message `json:"messages"`
}

func main() {
	// Create HTTP client
	client := &http.Client{}
	// Build request body
	requestBody := RequestBody{
		// Model list: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
		Model: "qwen-plus",
		Messages: []Message{
			{
				Role:    "system",
				Content: "You are a helpful assistant.",
			},
			{
				Role:    "user",
				Content: "Who are you?",
			},
		},
	}
	jsonData, err := json.Marshal(requestBody)
	if err != nil {
		log.Fatal(err)
	}
	// Create POST request
	req, err := http.NewRequest("POST", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions", bytes.NewBuffer(jsonData))
	if err != nil {
		log.Fatal(err)
	}
	// Set request header
	// If the environment variable is not configured, replace the following line with: apiKey := "sk-xxx"
	apiKey := os.Getenv("DASHSCOPE_API_KEY")
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	// Send request
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	// Read response body
	bodyText, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	// Print the content of the response
	fmt.Printf("%s\n", bodyText)
}

Sample response

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "I am Qwen, an AI assistant developed by Alibaba Cloud. I am designed to answer various questions, provide information, and engage in conversations with users. Is there anything I can help you with?"
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 22,
    "completion_tokens": 36,
    "total_tokens": 58
  },
  "created": 1721044596,
  "system_fingerprint": null,
  "model": "qwen-plus",
  "id": "chatcmpl-94149c5a-137f-9b87-b2c8-61235e85f540"
}

Streaming output

Python

Sample request

import os
from openai import OpenAI

client = OpenAI(
    # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[{'role': 'system', 'content': 'You are a helpful assistant.'},
                {'role': 'user', 'content': 'Who are you?'}],
    stream=True,
    stream_options={"include_usage": True}
    )
for chunk in completion:
    print(chunk.model_dump_json())

Sample response

{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"","function_call":null,"refusal":null,"role":"assistant","tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"I am","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":" a large-scale","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":" language model","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":" developed by Alibaba Cloud","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":".","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":"stop","index":0,"logprobs":null}],"created":1724916712,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[],"created":1724916712,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":{"completion_tokens":17,"prompt_tokens":22,"total_tokens":39}}

curl

Sample request

curl --location "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
    "model": "qwen-plus",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user", 
            "content": "Who are you?"
        }
    ],
    "stream":true
}'

Sample response

data: {"choices":[{"delta":{"content":"","role":"assistant"},"index":0,"logprobs":null,"finish_reason":null}],"object":"chat.completion.chunk","usage":null,"created":1724916884,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-e45656c0-efae-940b-a3b8-18c9e6528ecb"}

data: {"choices":[{"finish_reason":null,"delta":{"content":"I am"},"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1724916884,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-e45656c0-efae-940b-a3b8-18c9e6528ecb"}

data: {"choices":[{"delta":{"content":" a large-scale"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1724916884,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-e45656c0-efae-940b-a3b8-18c9e6528ecb"}

data: {"choices":[{"delta":{"content":" language model"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1724916884,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-e45656c0-efae-940b-a3b8-18c9e6528ecb"}

data: {"choices":[{"delta":{"content":" developed by Alibaba Cloud"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1724916884,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-e45656c0-efae-940b-a3b8-18c9e6528ecb"}

data: {"choices":[{"delta":{"content":"."},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1724916884,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-e45656c0-efae-940b-a3b8-18c9e6528ecb"}

data: {"choices":[{"delta":{"content":""},"finish_reason":"stop","index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1724916884,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-e45656c0-efae-940b-a3b8-18c9e6528ecb"}

data: [DONE]

Node.js

Sample request

import OpenAI from "openai";

const openai = new OpenAI(
    {
        // If the environment variable is not configured, replace the following line with: apiKey: "sk-xxx",
        apiKey: process.env.DASHSCOPE_API_KEY,
        baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
    }
);

const completion = await openai.chat.completions.create({
    model: "qwen-plus",
    messages: [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"}
    ],
    stream: true,
});

for await (const chunk of completion) {
    console.log(JSON.stringify(chunk));
}

Sample response

{"choices":[{"delta":{"content":"","role":"assistant"},"index":0,"logprobs":null,"finish_reason":null}],"object":"chat.completion.chunk","usage":null,"created":1728455257,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-bdcd77c7-6c52-9501-9ad0-fbda95386bbc"}
{"choices":[{"finish_reason":null,"delta":{"content":"I am from"},"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1728455257,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-bdcd77c7-6c52-9501-9ad0-fbda95386bbc"}
{"choices":[{"delta":{"content":" Alibaba"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1728455257,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-bdcd77c7-6c52-9501-9ad0-fbda95386bbc"}
{"choices":[{"delta":{"content":" Cloud"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1728455257,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-bdcd77c7-6c52-9501-9ad0-fbda95386bbc"}
{"choices":[{"delta":{"content":"'s large language model"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1728455257,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-bdcd77c7-6c52-9501-9ad0-fbda95386bbc"}
{"choices":[{"delta":{"content":", and my name is Qwen."},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1728455257,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-bdcd77c7-6c52-9501-9ad0-fbda95386bbc"}
{"choices":[{"delta":{"content":""},"finish_reason":"stop","index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1728455257,"system_fingerprint":null,"model":"qwen-plus","id":"chatcmpl-bdcd77c7-6c52-9501-9ad0-fbda95386bbc"}

Image input

For more information, see Vision understanding.

Python

Sample request

import os
from openai import OpenAI

client = OpenAI(
    # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-vl-plus",
    messages=[{"role": "user","content": [
            {"type": "text","text": "What is this"},
            {"type": "image_url",
             "image_url": {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}}
            ]}]
    )
print(completion.model_dump_json())

Sample response

{
  "id": "chatcmpl-9b2665ca-4d9c-9799-9675-e2947ccc2c3e",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "The image shows a woman interacting with her dog on the beach. The dog is sitting on the ground, reaching out its paw as if to shake hands or give a high-five. The woman is wearing a plaid shirt and seems to be having a close interaction with the dog, smiling. The background is the ocean and the sky at sunrise or sunset. This is a heartwarming photo that captures a moment of friendship between humans and pets.",
        "refusal": null,
        "role": "assistant",
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1724920555,
  "model": "qwen-vl-plus",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 79,
    "prompt_tokens": 1276,
    "total_tokens": 1355
  }
}

curl

Sample request

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "model": "qwen-vl-plus",
  "messages": [{
      "role": "user",
      "content": 
      [{"type": "text","text": "What is this"},
       {"type": "image_url","image_url": {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}}]
    }]
}'

Sample response

{
    "choices": [
        {
            "message": {
                "content": "This image shows a woman and a dog interacting on the beach. They seem to be enjoying each other's company, with the dog sitting on the sand and reaching out its paw to shake hands or play with the woman.\n\nIn the background, you can see the waves hitting the shoreline, and the sky is illuminated with soft light during sunset. This gives a sense of tranquility and warmth, possibly taken in the evening or early morning. This scene typically symbolizes friendship, love, and the deep emotional connection between humans and pets.",
                "role": "assistant"
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 1275,
        "completion_tokens": 92,
        "total_tokens": 1367
    },
    "created": 1728458088,
    "system_fingerprint": null,
    "model": "qwen-vl-plus",
    "id": "chatcmpl-5b471a38-02a4-92b0-a076-45378c986aea"
}

Node.js

Sample request

import OpenAI from "openai";

const openai = new OpenAI(
    {
        // If the environment variable is not configured, replace the following line with: apiKey: "sk-xxx",
        apiKey: process.env.DASHSCOPE_API_KEY,
        baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
    }
);

const response = await openai.chat.completions.create({
    model: "qwen-vl-max",
    messages: [{role: "user",content: [
        { type: "text", text: "What is this?" },
        { type: "image_url",image_url: {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}}
    ]}]
});
console.log(JSON.stringify(response));

Sample response

{
    "choices": [
        {
            "message": {
                "content": "This is a photo taken on the beach. In the photo, a woman wearing a plaid shirt is sitting on the sand, interacting with a yellow Labrador wearing a collar. The background is the sea and the sky, with sunlight shining on them, creating a warm atmosphere.",
                "role": "assistant"
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 1271,
        "completion_tokens": 55,
        "total_tokens": 1326
    },
    "created": 1728455324,
    "system_fingerprint": null,
    "model": "qwen-vl-max",
    "id": "chatcmpl-2c878e62-613c-9acd-a0e3-bb77cce98960"
}

Tool calling

For a complete tool calling sample, see Function calling.

Python

Sample request

import os
from openai import OpenAI

client = OpenAI(
    # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",  # Replace with the base_url of the DashScope SDK
)

tools = [
    # Tool 1: obtain the current time
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "This tool can help you query the current time.",
            "parameters": {}  # No request parameter is needed. The parameters parameter is left empty.
        }
    },  
    # Tool 2: obtain the weather of a specific city
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "This tool can help you query the weather of a city.",
            "parameters": {  
                "type": "object",
                "properties": {
                    # The location parameter is required when querying the weather
                    "location": {
                        "type": "string",
                        "description": "A city, county, or district, such as Beijing, Hangzhou, or Yuhang."
                    }
                },
                "required": ["location"]
            }
        }
    }
]
messages = [{"role": "user", "content": "How is the weather in Hangzhou"}]
completion = client.chat.completions.create(
    model="qwen-plus",
    messages=messages,
    tools=tools
)

print(completion.model_dump_json())

Sample response

{
  "id": "chatcmpl-9894dd96-4cd9-9d10-9ad1-cd7d8ce7a579",
  "choices": [
    {
      "finish_reason": "tool_calls",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "",
        "role": "assistant",
        "function_call": null,
        "tool_calls": [
          {
            "id": "call_105fec8d4a954d89b280fe",
            "function": {
              "arguments": "{\"location\": \"Hangzhou\"}",
              "name": "get_current_weather"
            },
            "type": "function",
            "index": 0
          }
        ]
      }
    }
  ],
  "created": 1726048255,
  "model": "qwen-plus",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 18,
    "prompt_tokens": 224,
    "total_tokens": 242
  }
}

curl

Sample request

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user", 
            "content": "How is the weather in Hangzhou"
        }
    ],
    "tools": [
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "This tool can help you query the current time.",
            "parameters": {}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "This tool can help you query the weather of a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location":{
                        "type": "string",
                        "description": "A city, county, or district, such as Beijing, Hangzhou, or Yuhang."
                    }
                },
                "required": ["location"]
            }
        }
    }
  ]
}'

Sample response

{
  "choices": [
    {
      "message": {
        "content": "",
        "role": "assistant",
        "tool_calls": [
          {
            "function": {
              "name": "get_current_weather",
              "arguments": "{\"location\": \"Hangzhou\"}"
            },
            "index": 0,
            "id": "call_b3b822e3aa6441369c42fc",
            "type": "function"
          }
        ]
      },
      "finish_reason": "tool_calls",
      "index": 0,
      "logprobs": null
    }
  ],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 224,
    "completion_tokens": 18,
    "total_tokens": 242
  },
  "created": 1726048351,
  "system_fingerprint": null,
  "model": "qwen-plus",
  "id": "chatcmpl-c1417bcf-10db-9fd3-8af0-8f99a15a833f"
}

Node.js

Sample request

import OpenAI from "openai";

const openai = new OpenAI(
    {
        // If the environment variable is not configured, replace the following line with: apiKey: "sk-xxx",
        apiKey: process.env.DASHSCOPE_API_KEY,
        baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
    }
);

const messages = [{"role": "user", "content": "How is the weather in Hangzhou"}];
const tools = [
// Tool 1: obtain the current time
{
    "type": "function",
    "function": {
        "name": "get_current_time",
        "description": "This tool can help you query the current time.",
        // No request parameter is needed. The parameters parameter is left empty.
        "parameters": {}  
    }
},  
// Tool 2: obtain the weather of a specific city
{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "This tool can help you query the weather of a city.",
        "parameters": {  
            "type": "object",
            "properties": {
                // The location parameter is required when querying the weather
                "location": {
                    "type": "string",
                    "description": "A city, county, or district, such as Beijing, Hangzhou, or Yuhang."
                }
            },
            "required": ["location"]
        }
    }
}
];

const response = await openai.chat.completions.create({
    model: "qwen-plus",
    messages: messages,
    tools: tools,
});

console.log(JSON.stringify(response));

Sample response

{
    "choices": [
        {
            "message": {
                "content": "",
                "role": "assistant",
                "tool_calls": [
                    {
                        "function": {
                            "name": "get_current_weather",
                            "arguments": "{\"location\": \"Hangzhou\"}"
                        },
                        "index": 0,
                        "id": "call_75cb935df86f48929cb606",
                        "type": "function"
                    }
                ]
            },
            "finish_reason": "tool_calls",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 224,
        "completion_tokens": 18,
        "total_tokens": 242
    },
    "created": 1728455556,
    "system_fingerprint": null,
    "model": "qwen-plus",
    "id": "chatcmpl-fee4749f-7c2a-9e16-a8cc-4111d89cf9f2"
}

Asynchronous calling

Sample request

import os
import asyncio
from openai import AsyncOpenAI
import platform

client = AsyncOpenAI(
    # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

async def main():
    response = await client.chat.completions.create(
        messages=[{"role": "user", "content": "Who are you"}],
        model="qwen-plus",
    )
    print(response.model_dump_json())

if platform.system() == "Windows":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
asyncio.run(main())

Sample response

{
    "id": "chatcmpl-e517181d-5b98-9c23-b57e-e6de5178bd4a",
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null,
            "message": {
                "content": "I am a large language model from Alibaba Cloud, and my name is Qwen.",
                "refusal": null,
                "role": "assistant",
                "function_call": null,
                "tool_calls": null
            }
        }
    ],
    "created": 1726124351,
    "model": "qwen-plus",
    "object": "chat.completion",
    "service_tier": null,
    "system_fingerprint": null,
    "usage": {
        "completion_tokens": 17,
        "prompt_tokens": 10,
        "total_tokens": 27
    }
}

model string (Required)

Specifies the model name.

Supported models: Qwen LLMs (commercial version and open-source version) and Qwen-VL

For specific model names and billing, see List of models.

messages array (Required)

A list of historical messages.

Message type

System Message object (Optional)

Specifies the purpose or role of the model. If this parameter is specified, the system message should be the first in the messages array.

Properties

content string (Required)

The content of the message.

role string (Required)

Set to system.

User Message object (Required)

The message that the user sends to the model.

Properties

content string or array (Required)

The content of the message. Use a string for text-only input and an array for multimodal inputs, such as images.

Properties

type string (Required)

Valid values: text and image_url.

text string (Required)

The text input by the user.

image_url string (Required)

The image input by the user, which can be a URL or local path. For more information, see Use local files.

role string (Required)

Set to user.

Assistant Message object (Optional)

The response from the model to the User Message.

Properties

content string (Optional)

The content of the message. This parameter is required unless the tool_calls parameter is specified in Assistant Message.

role string (Required)

Set to assistant.

tool_calls array (Optional)

Specifies the tools and their parameters returned by the model. It consists of one or more objects from the tool_calls field in the previous model response.

Properties

id string

The tool response ID.

type string

The type of the tool. Valid value: function.

function object

The function to call.

Properties

name string

The name of the function to call.

arguments string

The input parameters for the function, provided in JSON string format.

index integer

The index of the tool information within the tool_calls array.

Tool Message object (Optional)

The output information of the tool. For more information, see Function calling.

Properties

content string (Required)

The message content, typically the output from the tool function.

role string (Required)

Set to tool.

stream boolean (Optional)

Specifies whether to use the streaming output mode. Valid values:

  • false (default): The model delivers the complete response at a time.

  • true: The model returns output in chunks as content is generated, allowing for real-time retrieval of each part until the full response is obtained.

stream_options object (Optional)

If you set stream to true, set stream_options to {"include_usage": true} to display the token count in the final line of the response

If this parameter is set to false, the token count is not displayed.

stream_options is effective only when stream is set to true.

temperature float (Optional)

Controls the diversity of the generated text.

A higher temperature results in more diversified text, while a lower temperature results in more predictable text.

Valid values: [0,2).

Because both temperature and top_p controls text diversity, we recommend that you specify only one of them. For more information, see temperature and top_p.

top_p float (Optional)

The probability threshold for nucleus sampling, which controls the diversity of the generated text.

A higher top_p results in more diversified text, while a lower top_p results in more predictable text.

Valid values: (0,1.0].

Because both temperature and top_p controls text diversity, we recommend that you specify only one of them. For more information, see temperature and top_p.

presence_penalty float (Optional)

Controls the repetition of the generated text.

Valid values: [-2.0, 2.0]. A positive value decreases repetition, while a negative value decreases repetition.

Scenarios:

A higher presence_penalty is ideal for scenarios demanding diversity, enjoyment, or creativity, such as creative writing or brainstorming.

A lower presence_penalty is ideal for scenarios demanding consistency and technical terminology, such as technical documentation and formal writing.

How it works

When set to a positive value, the model imposes a penalty on tokens already present in the text (irrespective of their frequency), thus decreasing their recurrence and enhancing variety.

Example

In the following example, the LLM is asked to translate a piece of Chinese text into English. The Chinese text contains many repetitive words. In the example, when presence_penalty is 2.0, the LLM translate the repetitive Chinese into diversified English words. When presence_penalty is -2.0, the repetitions are retained.

Prompt: Translate this sentence into English “这部电影很好。情节很好,演技很好,音乐也很好,总的来说,整部电影都很好。实际上,它真的很棒。情节非常好,演技也非常好,音乐也非常好。

With a value of 2.0: This movie is great. The plot is excellent, the acting is superb, and the music is delightful. Overall, the entire film is outstanding. Indeed, it is truly exceptional. The plot is thrilling, the acting is top-notch, and the music is melodious.

With a value of 0.0: This movie is good. The plot is good, the acting is good, the music is good, and overall, the movie is good. Indeed, it is really great. The plot is very good, the acting is outstanding, and the music is excellent.

With a value of -2.0: This movie is good. The plot is good, the acting is good, the music is good, and overall, the movie is good. Indeed, it is really great. The plot is good, the acting is good, and the music is good.

max_tokens integer (Optional)

The maximum number of tokens that can be generated by the model.

The default and maximum values correspond to the maximum output length.

This parameter is useful in scenarios that require a limited word count, such as generating summaries or keywords, controlling costs, or improving response time.

seed integer (Optional)

Specifying this parameter makes the text generation process more predictable.

If you specify the same seed every time you call a model, while keeping other parameters unchanged, the model is likely to return the same response.

Valid values: An unsigned 64-bit integer, ranging from 0 to 264−1.

stop string or array (Optional)

If you specify this parameter, the model stops generating content when the specified string or token is about to be generated.

You can set stop to sensitive words to control model response.

When stop is an array, it cannot contain both token_id and string types at the same time. For instance, ["Hello",104307] is not valid.

tools array (Optional)

Specifies an array of tools that the model can call. tools can include one or more tool objects. The model selects one appropriate tool to use during each function calling process.

Qwen-VL does not support tools. We recommend that you use qwen-max or qwen-plus instead.

Properties

type string (Required)

The type of the tool. Valid value: function.

function object (Required)

Properties

name string (Required)

The name of the tool function, which can contain letters, digits, underscores (_), and hyphens (-). It can be up to 64 characters in length.

description string (Required)

The description of the function. It tells the model when and how to use the tool function.

parameters object (Required)

The request parameters of the tool function. The request parameters must be specified in a valid JSON schema, see Understanding JSON Schema. If the parameters parameter is left empty, the function does not need request parameters.

chat response object (Non-streaming output)

{
  "id": "chatcmpl-0da38de9-5d2b-916d-9c6a-7af95993e275",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "I am Qwen, an AI assistant developed by Alibaba Cloud. I am designed to answer various questions, provide information, and engage in conversations with users. Is there anything I can help you with?",
        "role": "assistant",
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1721044114,
  "model": "qwen-plus",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 36,
    "prompt_tokens": 22,
    "total_tokens": 58
  }
}

id string

The ID of this request.

choices array

An array of content generated by the model, potentially including multiple choices objects.

Properties

finish_reason string

The reason why the model stops. Valid values:

  • stop: The stop input parameter is met, or the output ends naturally.

  • length: The generation length exceeds the limit.

  • tool_calls: The model needs to call a tool.

index integer

The index number within the choices array.

message object

The message returned by the model.

Properties

content string

The text output produced by the model during this call.

role string

The role of the message. Always assistant.

tool_calls array

The tools and their parameters returned by the model. It can contain one or more objects.

Properties

id string

The tool response ID.

type string

The type of the tool. Valid value: function.

function object

The function to be called.

Properties

name string

The name of the function.

arguments string

The input parameters for the tool, a JSON string.

Given the randomness of LLM responses, the output JSON string may not always align with your function. We recommend that you validate parameter integrity before passing them to the function.

Index integer

The index of the tool information within thetool_callsarray.

function_call (to be deprecated) object method.

Default value: null. Refer to tool_calls.

created string

The timestamp when this request was created.

model string

The name of the model used for the request.

object string

Always chat.completion.

usage object

The token consumed by this request.

Properties

prompt_tokens integer

The number of tokens converted from the user input.

completion_tokens integer

The number of tokens converted from the model response.

total_tokens integer

The sum of prompt_tokens and completion_tokens.

chat response chunk object (Streaming output)

{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"","function_call":null,"refusal":null,"role":"assistant","tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"I am","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":" a large","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":" language model","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":" developed by Alibaba Cloud","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":".","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":"stop","index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[],"created":1724916712,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":{"completion_tokens":17,"prompt_tokens":22,"total_tokens":39}}

id string

The ID of this request. All chunk objects share the same ID.

choices array

An array of content generated by the model, potentially including multiple choices objects. If include_usage is set to true, the final chunk is empty.

Properties

delta object

The incremental object of the request.

Properties

content string

The content of the message chunk.

tools_calls array

Properties

index integer

The index of the tool information within thetool_callsarray.

id string

The tool response ID.

function object

The function to be called.

Properties

arguments string

The input parameters for the tool. The arguments properties of all chunks can concatenat to form a complete JSON string.

Given the randomness of LLM responses, the output JSON string may not always align with your function. We recommend that you validate parameter integrity before passing them to the function.

name string

The name of the function, assigned a value only in the first chunk.

type string

The type of the tool. Valid value:function.

function_call object

Default value:null. Refer totool_calls.

role string

The role of the incremental message object, assigned a value only in the first chunk.

finish_reason string

The reason why the model stops. Valid values:

  • stop: Thestopinput parameter is met, or the output ends naturally.

  • length: The generation length exceeds the limit.

  • tool_calls: The model needs to call a tool.

index integer

The index number within thechoicesarray.

created string

The timestamp when this request was created. All chunk objects share the same timestamp.

model string

The name of the model used for the request.

object string

Always chat.completion.chunk.

usage object

The token consumed by this request. It is displayed only in the last chunk when include_usage is true.

Properties

prompt_tokens integer

The number of tokens converted from the user input.

completion_tokens integer

The number of tokens converted from the model response.

total_tokens integer

The sum of prompt_tokens and completion_tokens.

DashScope

Public cloud

HTTP endpoint:

For Qwen models: POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text-generation/generation

For Qwen-VL models: POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

You must first obtain an API key and set the API key as an environment variable. If using the DashScope SDK, you must also install the DashScope SDK.

The request body

Text input

Python

Sample request

import os
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
messages = [
    {'role': 'system', 'content': 'You are a helpful assistant.'},
    {'role': 'user', 'content': 'Who are you?'}
    ]
response = dashscope.Generation.call(
    # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen-plus", # Model list: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
    messages=messages,
    result_format='message'
    )
print(response)

Sample response

{
  "status_code": 200,
  "request_id": "902fee3b-f7f0-9a8c-96a1-6b4ea25af114",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "I am a large language model developed by Alibaba Cloud, and my name is Qwen."
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 22,
    "output_tokens": 17,
    "total_tokens": 39
  }
}

Java

Sample request

// It is recommended that the version of the dashscope SDK is >= 2.12.0
import java.util.Arrays;
import java.lang.System;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
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.protocol.Protocol;

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://dashscope-intl.aliyuncs.com/api/v1");
        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .content("You are a helpful assistant.")
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content("Who are you?")
                .build();
        GenerationParam param = GenerationParam.builder()
                // If the environment variable is not configured, replace the following line with: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-plus")
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .build();
        return gen.call(param);
    }
    public static void main(String[] args) {
        try {
            GenerationResult result = callWithMessage();
            System.out.println(JsonUtils.toJson(result));
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // Use the logging framework to record exception information
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
        System.exit(0);
    }
}

Sample response

{
  "requestId": "86dd52a9-23ec-9804-8f82-85f4c7fd5114",
  "usage": {
    "input_tokens": 22,
    "output_tokens": 17,
    "total_tokens": 39
  },
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "I am a large language model developed by Alibaba Cloud, and my name is Qwen."
        }
      }
    ]
  }
}

curl

Sample request

curl --location "https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text-generation/generation" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
    "model": "qwen-plus",
    "input":{
        "messages":[      
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Who are you?"
            }
        ]
    },
    "parameters": {
        "result_format": "message"
    }
}'

Sample response

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "I am Qwen, an AI assistant developed by Alibaba Cloud. I am designed to answer various questions, provide information, and engage in conversations with users. Is there anything I can help you with?"
        }
      }
    ]
  },
  "usage": {
    "total_tokens": 58,
    "output_tokens": 36,
    "input_tokens": 22
  },
  "request_id": "39377fd7-26dd-99f5-b539-5fd004b6ecb5"
}

Streaming output

Python

Sample request

import os
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
messages = [
    {'role':'system','content':'you are a helpful assistant'},
    {'role': 'user','content': 'Who are you?'}
    ]
responses = dashscope.Generation.call(
    # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen-plus",
    messages=messages,
    result_format='message',
    stream=True,
    incremental_output=True
    )
for response in responses:
    print(response)
    

Sample response

{"status_code": 200, "request_id": "xxx", "code": "", "message": "", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": "I am"}}]}, "usage": {"input_tokens": 21, "output_tokens": 1, "total_tokens": 22}}
{"status_code": 200, "request_id": "xxx", "code": "", "message": "", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": "Qwen"}}]}, "usage": {"input_tokens": 21, "output_tokens": 2, "total_tokens": 23}}
{"status_code": 200, "request_id": "xxx", "code": "", "message": "", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": ", an AI"}}]}, "usage": {"input_tokens": 21, "output_tokens": 3, "total_tokens": 24}}
{"status_code": 200, "request_id": "xxx", "code": "", "message": "", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": "assistant developed by"}}]}, "usage": {"input_tokens": 21, "output_tokens": 8, "total_tokens": 29}}
{"status_code": 200, "request_id": "xxx", "code": "", "message": "", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": "Alibaba Cloud. I am"}}]}, "usage": {"input_tokens": 21, "output_tokens": 16, "total_tokens": 37}}
{"status_code": 200, "request_id": "xxx", "code": "", "message": "", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": "designed to answer various questions, provide information"}}]}, "usage": {"input_tokens": 21, "output_tokens": 24, "total_tokens": 45}}
{"status_code": 200, "request_id": "xxx", "code": "", "message": "", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": "and engage in conversations with users. Is there anything I can"}}]}, "usage": {"input_tokens": 21, "output_tokens": 32, "total_tokens": 53}}
{"status_code": 200, "request_id": "xxx", "code": "", "message": "", "output": {"text": null, "finish_reason": "stop", "choices": [{"finish_reason": "stop", "message": {"role": "assistant", "content": "help you with?"}}]}, "usage": {"input_tokens": 21, "output_tokens": 36, "total_tokens": 57}}

Java

Sample request

import java.util.Arrays;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
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 io.reactivex.Flowable;
import java.lang.System;
import com.alibaba.dashscope.protocol.Protocol;

public class Main {
    private static final Logger logger = LoggerFactory.getLogger(Main.class);
    private static void handleGenerationResult(GenerationResult message) {
        System.out.println(JsonUtils.toJson(message));
    }
    public static void streamCallWithMessage(Generation gen, Message userMsg)
            throws NoApiKeyException, ApiException, InputRequiredException {
        GenerationParam param = buildGenerationParam(userMsg);
        Flowable<GenerationResult> result = gen.streamCall(param);
        result.blockingForEach(message -> handleGenerationResult(message));
    }
    private static GenerationParam buildGenerationParam(Message userMsg) {
        return GenerationParam.builder()
                // If the environment variable is not configured, replace the following line with: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-plus")
                .messages(Arrays.asList(userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .incrementalOutput(true)
                .build();
    }
    public static void main(String[] args) {
        try {
            Generation gen = new Generation(Protocol.HTTP.getValue(), "https://dashscope-intl.aliyuncs.com/api/v1");
            Message userMsg = Message.builder().role(Role.USER.getValue()).content("Who are you?").build();
            streamCallWithMessage(gen, userMsg);
        } catch (ApiException | NoApiKeyException | InputRequiredException  e) {
            logger.error("An exception occurred: {}", e.getMessage());
        }
        System.exit(0);
    }
}

Sample response

{"requestId":"xxx","usage":{"input_tokens":11,"output_tokens":1,"total_tokens":12},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":"I am"}}]}}
{"requestId":"xxx","usage":{"input_tokens":11,"output_tokens":2,"total_tokens":13},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":"Qwen"}}]}}
{"requestId":"xxx","usage":{"input_tokens":11,"output_tokens":3,"total_tokens":14},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":", an AI"}}]}}
{"requestId":"xxx","usage":{"input_tokens":11,"output_tokens":8,"total_tokens":19},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":"assistant developed by"}}]}}
{"requestId":"xxx","usage":{"input_tokens":11,"output_tokens":16,"total_tokens":27},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":"Alibaba Cloud. I am"}}]}}
{"requestId":"xxx","usage":{"input_tokens":11,"output_tokens":24,"total_tokens":35},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":"designed to answer various questions, provide information"}}]}}
{"requestId":"xxx","usage":{"input_tokens":11,"output_tokens":32,"total_tokens":43},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":"and engage in conversations with users. Is there anything I can"}}]}}
{"requestId":"xxx","usage":{"input_tokens":11,"output_tokens":36,"total_tokens":47},"output":{"choices":[{"finish_reason":"stop","message":{"role":"assistant","content":"help you with?"}}]}}

curl

Sample request

curl --location "https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text-generation/generation" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--header "X-DashScope-SSE: enable" \
--data '{
    "model": "qwen-plus",
    "input":{
        "messages":[      
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Who are you?"
            }
        ]
    },
    "parameters": {
        "result_format": "message",
        "incremental_output":true
    }
}'

Sample response

id:1
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"message":{"content":"I am","role":"assistant"},"finish_reason":"null"}]},"usage":{"total_tokens":23,"input_tokens":22,"output_tokens":1},"request_id":"xxx"}

id:2
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"message":{"content":"Qwen","role":"assistant"},"finish_reason":"null"}]},"usage":{"total_tokens":24,"input_tokens":22,"output_tokens":2},"request_id":"xxx"}

id:3
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"message":{"content":", an AI","role":"assistant"},"finish_reason":"null"}]},"usage":{"total_tokens":25,"input_tokens":22,"output_tokens":3},"request_id":"xxx"}

id:4
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"message":{"content":"assistant developed by","role":"assistant"},"finish_reason":"null"}]},"usage":{"total_tokens":30,"input_tokens":22,"output_tokens":8},"request_id":"xxx"}

id:5
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"message":{"content":"Alibaba Cloud. I am","role":"assistant"},"finish_reason":"null"}]},"usage":{"total_tokens":38,"input_tokens":22,"output_tokens":16},"request_id":"xxx"}

id:6
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"message":{"content":"designed to answer various questions, provide information","role":"assistant"},"finish_reason":"null"}]},"usage":{"total_tokens":46,"input_tokens":22,"output_tokens":24},"request_id":"xxx"}

id:7
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"message":{"content":"and engage in conversations with users. Is there anything I can","role":"assistant"},"finish_reason":"null"}]},"usage":{"total_tokens":54,"input_tokens":22,"output_tokens":32},"request_id":"xxx"}

id:8
event:result
:HTTP_STATUS/200
data:{"output":{"choices":[{"message":{"content":"help you with?","role":"assistant"},"finish_reason":"stop"}]},"usage":{"total_tokens":58,"input_tokens":22,"output_tokens":36},"request_id":"xxx"}

Image input

For more information, see Vision understanding.

Python

Sample request

import os
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
messages = [
    {
        "role": "user",
        "content": [
            {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"},
            {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"},
            {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/rabbit.png"},
            {"text": "What are these?"}
        ]
    }
]
response = dashscope.MultiModalConversation.call(
    # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model='qwen-vl-max',
    messages=messages
    )
print(response)

Sample response

{
    "status_code": 200,
    "request_id": "3a031529-707f-9b7d-968c-172e7533debc",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "text": "Image 1 shows a woman playing with a dog on the beach.\nImage 2 is an illustration of a Bengal tiger walking towards the camera.\nImage 3 is a cute little white rabbit."
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 3743,
        "output_tokens": 41,
        "image_tokens": 3697
    }
}

Java

Sample request

// Copyright (c) Alibaba, Inc. and its affiliates.

import java.util.Arrays;
import java.util.Collections;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
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 simpleMultiModalConversationCall()
            throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("image", "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"),
                        Collections.singletonMap("image", "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"),
                        Collections.singletonMap("image", "https://dashscope.oss-cn-beijing.aliyuncs.com/images/rabbit.png"),
                        Collections.singletonMap("text", "What are these?"))).build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // If the environment variable is not configured, replace the following line with: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-vl-plus")
                .message(userMessage)
                .build();
        MultiModalConversationResult result = conv.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            simpleMultiModalConversationCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Sample response

{
  "requestId": "dcb38a0f-fd69-9071-bcde-c4530f9a7559",
  "usage": {
    "input_tokens": 3740,
    "output_tokens": 48
  },
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "text": "Image 1 shows a woman playing with a large golden retriever on the beach.\nImage 2 is a realistic photo of a Bengal tiger walking towards the camera.\nImage 3 is an illustration mainly featuring a rabbit."
            }
          ]
        }
      }
    ]
  }
}

curl

Sample request

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen-vl-plus",
    "input":{
        "messages":[
            {
                "role```html
                "role": "user",
                "content": [
                    {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"},
                    {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"},
                    {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/rabbit.png"},
                    {"text": "What are these?"}
                ]
            }
        ]
    }
}'

Sample response

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "text": "Image 1 shows a woman playing with a large golden retriever on the beach.\nImage 2 is a realistic photo of a Bengal tiger walking towards the camera.\nImage 3 is an illustration mainly featuring a rabbit."
            }
          ]
        }
      }
    ]
  },
  "usage": {
    "output_tokens": 48,
    "input_tokens": 3740,
    "image_tokens": 3697
  },
  "request_id": "eb6204ea-4cba-91b1-95ab-e7836b7355d6"
}

Tool calling

For a complete tool calling sample, see Function calling.

Python

Sample request

import os
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "This tool can help you query the current time.",
            "parameters": {}
        }
    },  
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "This tool can help you query the weather of a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "A city, county, or district, such as Beijing, Hangzhou, or Yuhang."
                    }
                }
            },
            "required": [
                "location"
            ]
        }
    }
]
messages = [{"role": "user", "content": "How is the weather in Hangzhou"}]
response = dashscope.Generation.call(
    # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model='qwen-plus',
    messages=messages,
    tools=tools,
    result_format='message'
)
print(response)

Sample response

{
  "status_code": 200,
  "request_id": "28d9b918-6287-95d1-9876-a67a9257c0c6",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "tool_calls",
        "message": {
          "role": "assistant",
          "content": "",
          "tool_calls": [
            {
              "function": {
                "name": "get_current_weather",
                "arguments": "{\"location\": \"Hangzhou\"}"
              },
              "index": 0,
              "id": "call_e63b80aab9df4950b391d0",
              "type": "function"
            }
          ]
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 218,
    "output_tokens": 18,
    "total_tokens": 236
  }
}

Java

Sample request

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import com.alibaba.dashscope.aigc.conversation.ConversationParam.ResultFormat;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.tools.FunctionDefinition;
import com.alibaba.dashscope.tools.ToolFunction;
import com.alibaba.dashscope.utils.JsonUtils;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.github.victools.jsonschema.generator.Option;
import com.github.victools.jsonschema.generator.OptionPreset;
import com.github.victools.jsonschema.generator.SchemaGenerator;
import com.github.victools.jsonschema.generator.SchemaGeneratorConfig;
import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder;
import com.github.victools.jsonschema.generator.SchemaVersion;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import com.alibaba.dashscope.protocol.Protocol;

public class Main {
    public class GetWeatherTool {
        private String location;
        public GetWeatherTool(String location) {
            this.location = location;
        }
        public String call() {
            return location+" is sunny today";
        }
    }
    public class GetTimeTool {
        public GetTimeTool() {
        }
        public String call() {
            LocalDateTime now = LocalDateTime.now();
            DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
            String currentTime = "Current time: " + now.format(formatter) + ".";
            return currentTime;
        }
    }
    public static void SelectTool()
            throws NoApiKeyException, ApiException, InputRequiredException {
        SchemaGeneratorConfigBuilder configBuilder =
                new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON);
        SchemaGeneratorConfig config = configBuilder.with(Option.EXTRA_OPEN_API_FORMAT_VALUES)
                .without(Option.FLATTENED_ENUMS_FROM_TOSTRING).build();
        SchemaGenerator generator = new SchemaGenerator(config);
        ObjectNode jsonSchema_weather = generator.generateSchema(GetWeatherTool.class);
        ObjectNode jsonSchema_time = generator.generateSchema(GetTimeTool.class);
        FunctionDefinition fdWeather = FunctionDefinition.builder().name("get_current_weather").description("Get the weather of a specific area")
                .parameters(JsonUtils.parseString(jsonSchema_weather.toString()).getAsJsonObject()).build();
        FunctionDefinition fdTime = FunctionDefinition.builder().name("get_current_time").description("Get the current time")
                .parameters(JsonUtils.parseString(jsonSchema_time.toString()).getAsJsonObject()).build();
        Message systemMsg = Message.builder().role(Role.SYSTEM.getValue())
                .content("You are a helpful assistant. When asked a question, use tools wherever possible.")
                .build();
        Message userMsg = Message.builder().role(Role.USER.getValue()).content("Hangzhou weather").build();
        List<Message> messages = new ArrayList<>();
        messages.addAll(Arrays.asList(systemMsg, userMsg));
        GenerationParam param = GenerationParam.builder()
                // If the environment variable is not configured, replace the following line with: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-plus")
                .messages(messages)
                .resultFormat(ResultFormat.MESSAGE)
                .tools(Arrays.asList(
                        ToolFunction.builder().function(fdWeather).build(),
                        ToolFunction.builder().function(fdTime).build()))
                .build();
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://dashscope-intl.aliyuncs.com/api/v1");
        GenerationResult result = gen.call(param);
        System.out.println(JsonUtils.toJson(result));
    }
    public static void main(String[] args) {
        try {
            SelectTool();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(String.format("Exception %s", e.getMessage()));
        }
        System.exit(0);
    }
}

Sample response

{
  "requestId": "4d81dc3d-6570-9e33-9e7d-199b20bf568f",
  "usage": {
    "input_tokens": 245,
    "output_tokens": 18,
    "total_tokens": 263
  },
  "output": {
    "choices": [
      {
        "finish_reason": "tool_calls",
        "message": {
          "role": "assistant",
          "content": "",
          "tool_calls": [
            {
              "type": "function",
              "id": "call_26a878c36995449195e7f6",
              "function": {
                "name": "get_current_weather",
                "arguments": "{\"location\": \"Hangzhou\"}"
              }
            }
          ]
        }
      }
    ]
  }
}

curl

Sample request

curl --location "https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text-generation/generation" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
    "model": "qwen-plus",
    "input": {
        "messages": [{
            "role": "user",
            "content": "How is the weather in Hangzhou"
        }]
    },
    "parameters": {
        "result_format": "message",
        "tools": [{
            "type": "function",
            "function": {
                "name": "get_current_time",
                "description": "This tool can help you query the current time.",
                "parameters": {}
            }
        },{
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "This tool can help you query the weather of a city.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "A city, county, or district, such as Beijing, Hangzhou, or Yuhang."
                        }
                    }
                },
                "required": ["location"]
            }
        }]
    }
}'

Sample response

{
  "output": {
    "choices": [
      {
        "finish_reason": "tool_calls",
        "message": {
          "role": "assistant",
          "tool_calls": [
            {
              "function": {
                "name": "get_current_weather",
                "arguments": "{\"location\": \"Hangzhou\"}"
              },
              "index": 0,
              "id": "call_aaab400803844cfc9fd6bd",
              "type": "function"
            }
          ],
          "content": ""
        }
      }
    ]
  },
  "usage": {
    "total_tokens": 236,
    "output_tokens": 18,
    "input_tokens": 218
  },
  "request_id": "10bdb494-05ee-9c45-9b38-bb544b5cb23e"
}

Asynchronous calling

Sample request

# Your Dashscope Python SDK version needs to be no less than 1.19.0.
import asyncio
import platform
import os
from dashscope.aigc.generation import AioGeneration
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
async def main():
    response = await AioGeneration.call(
        # If the environment variable is not configured, replace the following line with: api_key="sk-xxx",
        api_key=os.getenv('DASHSCOPE_API_KEY'),
        model="qwen-plus",
        messages=[{"role": "user", "content": "Who are you"}],
        result_format="message",
    )
    print(response)

if platform.system() == "Windows":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
asyncio.run(main())

Sample response

{
    "status_code": 200,
    "request_id": "124ca191-68a5-90b8-84bd-5ef944883a94",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "I am a large language model developed by Alibaba Cloud, and my name is Qwen. As a language model, my goal is to generate high-quality text related to given words, helping users obtain accurate and useful information, and solve their problems and confusions. Whether it's work-related needs, such as writing emails, creating reports, coding, or personal issues, such as emotional communication, daily life advice, or learning assistance, such as historical knowledge, geographical information, mathematical calculations, etc., I will do my best to provide help. Please feel free to ask me questions or seek help, and I will do my best to meet your needs."
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 10,
        "output_tokens": 114,
        "total_tokens": 124
    }
}

model string (Required)

Specifies the model name.

Supported models: Qwen LLMs (commercial version and open-source version) and Qwen-VL.

For specific model names and billing, see List of models.

messages array (Required)

A list of historical messages.

When using HTTP, include messages within the input object.

Message Types

System Message object

Specifies the purpose or role of the model. If this parameter is specified, the system message should be the first in the messages array.

Properties

content string (Required)

The content of the message.

role string (Required)

Set to system.

User Message object

The message that the user sends to the model.

Properties

content string or array(Required)

The content of the message. Use a string for Qwen models and an array for Qwen-VL models.

Properties

text string

The text input by the user.

image string

The image input by the user, which can be a URL.

role string (Required)

Set to user.

Assistant Message object

The response from the model to the User Message.

Properties

content string (Required)

The content of the message.

role string (Required)

Set to assistant.

Tool Message object

The output information of the tool. For more information, see Function calling.

Properties

content string (Required)

The message content, typically the output from the tool function.

role string (Required)

Set to tool.

temperature float (Optional)

Controls the diversity of the generated text.

A highertemperatureresults in more diversified text, while a lowertemperatureresults in more predictable text.

Valid values: [0,2).

For HTTP calls, include temperature in the parameters object.

top_p float (Optional)

The probability threshold for nucleus sampling, which controls the diversity of the generated text.

A highertop_presults in more diversified text, while a lowertop_presults in more predictable text.

Valid values: (0,1.0].

In the Java SDK, this parameter is topP. For HTTP calls, include top_p in the parameters object.

top_k integer (Optional)

The size of the candidate set for sampling.

A highertop_kresults in more diversified text, while a lowertop_kresults in more predictable text.

If top_k is left empty or set to a value greater than 100, top_k is disabled and only top_p takes effect.

In the Java SDK, this parameter is topK. For HTTP calls, include top_k in the parameters object.

repetition_penalty float (Optional)

Controls the repetition of the generated text.

A value above 1.0 reduces repetition.

The value must be greater than 0.

In the Java SDK, this parameter is repetitionPenalty. For HTTP calls, include repetition_penalty in the parameters object.

vl_high_resolution_images boolean (Optional)

Specifies whether to raise the default token limit for input images. Only qwen-vl-max supports this parameter. The default token limit is 1,280. If you set vl_high_resolution_images to true, the limit is raised to 16,384.

Default value: false.

The Java SDK does not support this parameter. For HTTP calls, include vl_high_resolution_images in the parameters object.

presence_penalty float (Optional)

Controls the repetition of the generated text.

Valid values: [-2.0, 2.0]. A positive value decreases repetition, while a negative value decreases repetition.

Scenarios:

A higher presence_penalty is ideal for scenarios demanding diversity, enjoyment, or creativity, such as creative writing or brainstorming.

A lower presence_penalty is ideal for scenarios demanding consistency and technical terminology, such as technical documentation and formal writing.

How it works

When set to a positive value, the model imposes a penalty on tokens already present in the text (irrespective of their frequency), thus decreasing their recurrence and enhancing variety.

Example

In the following example, the LLM is asked to translate a piece of Chinese text into English. The Chinese text contains many repetitive words. In the example, when presence_penalty is 2.0, the LLM translate the repetitive Chinese into diversified English words. When presence_penalty is -2.0, the repetitions are retained.

Prompt: Translate this sentence into English “这部电影很好。情节很好,演技很好,音乐也很好,总的来说,整部电影都很好。实际上,它真的很棒。情节非常好,演技也非常好,音乐也非常好。

With a value of 2.0: This movie is great. The plot is excellent, the acting is superb, and the music is delightful. Overall, the entire film is outstanding. Indeed, it is truly exceptional. The plot is thrilling, the acting is top-notch, and the music is melodious.

With a value of 0.0: This movie is good. The plot is good, the acting is good, the music is good, and overall, the movie is good. Indeed, it is really great. The plot is very good, the acting is outstanding, and the music is excellent.

With a value of -2.0: This movie is good. The plot is good, the acting is good, the music is good, and overall, the movie is good. Indeed, it is really great. The plot is good, the acting is good, and the music is good.

The Java SDK does not support this parameter. Include presence_penalty in the parameters object for HTTP calls.

max_tokens integer (Optional)

The maximum number of tokens that can be generated by the model.

The default and maximum values correspond to the maximum output length.

This parameter is useful in scenarios that require a limited word count, such as generating summaries or keywords, controlling costs, or improving response time.

In the Java SDK, this parameter is maxTokens. For HTTP calls, include max_tokens in the parameters object.

seed integer (Optional)

Specifying this parameter makes the text generation process more predictable.

If you specify the same seed every time you call a model, while keeping other parameters unchanged, the model is likely to return the same response.

Valid values: An unsigned 64-bit integer, ranging from 0 to 264−1.

For HTTP calls, include seed in the parameters object.

stream boolean (Optional)

Specifies whether to use the streaming output mode. Valid values:

  • false (default): The model delivers the complete response at a time.

  • true: The model returns output in chunks as content is generated.

Only the Python SDK supports this parameter. For the Java SDK, use streamCall. For HTTP calls, set X-DashScope-SSE to enable in the request header.

incremental_output boolean (Optional)

Specifies whether to enable incremental output in the streaming output mode. Valid values:

  • false (default): Each output includes the entire sequence generated so far.

    I
    I like
    I like apple
    I like apple.
  • true: Each output excludes previous content.

    I
    like
    apple
    .
In the Java SDK, this parameter is incrementalOutput. For HTTP calls, include incremental_output in the parameters object.

result_format string (Optional)

Specifies the format of the returned result.

Valid values: text (default) and message.

We recommend that you use message.

In the Java SDK, this parameter is resultFormat. For HTTP calls, include result_format in the parameters object.

stop string or array (Optional)

If you specify this parameter, the model stops generating content when the specified string or token is about to be generated.

You can set stop to sensitive words to control model response.

When stop is an array, it cannot contain both token_id and string types at the same time. For instance, ["Hello",104307] is not valid.

tools array (Optional)

Specifies an array of tools that the model can call.toolscan include one or more tool objects. The model selects one appropriate tool to use during each function calling process. During each process, you need to specify tools when initiating function calling and when submitting the results of a tool function to the model.

If you specify this parameter, you must also set result_format to message.

Qwen-VL does not support tools. We recommend that you use qwen-max or qwen-plus instead.

Properties

type string (Required)

The type of the tool. Valid value:function.

function object (Required)

Properties

name string (Required)

The name of the tool function, which can contain can contain letters, digits, underscores (_), and hyphens (-). It can be up to 64 characters in length.

description string (Required)

The description of the function. It tells the model when and how to use the tool function.

parameters object (Required)

The request parameters of the tool function. The request parameters must be specified in a valid JSON schema, see Understanding JSON Schema. If the parameters parameter is left empty, the function does not need request parameters.

For HTTP calls, include tools in the parameters object.

tool_choice string or object (Optional)

Controls the tool selection when using tools. Valid values:

  • "none": Do not call tools. If tools is left empty, "none" is the default value.

  • "auto": The model decides whether to call a tool. If tools is not empty, "auto" is the default value.

  • Use an object structure to specify a tool for the model to call. For example, tool_choice={"type": "function", "function": {"name": "user_function"}}.

    • type: set to "function".

    • function

      • name: the tool to be called, such as "get_current_time".

In the Java SDK, this parameter is toolChoice. For HTTP calls, include tool_choice in the parameters object.

chat response object

(Same for streaming and non-streaming output)

{
  "status_code": 200,
  "request_id": "902fee3b-f7f0-9a8c-96a1-6b4ea25af114",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "I am a large language model developed by Alibaba Cloud, and my name is Qwen."
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 22,
    "output_tokens": 17,
    "total_tokens": 39
  }
}

status_code string

The response code. The status code 200 indicates that the request is successful. Other status codes indicate that the request failed.

The Java SDK does not return this parameter. Instead, an exception is thrown with status_code and message.

request_id string

The request ID.

In the Java SDK, this is returned as requestId.

code string

The error code returned if the request failed. If the request was successful, no value is returned for this parameter.

This parameter is returned only for the Python SDK.

output object

The result of the request.

Properties

text string

The response generated by the model, returned when result_format is set to text.

finish_reason string

When you set result_format to text, this parameter is not left empty.

Valid values:

  • null: The model is generating the answer.

  • stop: Thestopinput parameter is met, or the output ends naturally.

  • length: The generation length exceeds the limit.

  • tool_calls: The model needs to call a tool.

choices array

The response generated by the model, returned when result_format is set to message.

Properties

finish_reason string

Valid values:

  • null: The model is generating the answer.

  • stop: Thestopinput parameter is met, or the output ends naturally.

  • length: The generation length exceeds the limit.

  • tool_calls: The model needs to call a tool.

message object

The message object returned from the model.

Properties

role string

The role of the message. Alwaysassistant.

content string

The content of the output message.

If function calling is initiated, this value is empty.

tool_calls array

This parameter is returned if the model needs to call a tool.

Properties

function object

The name and input parameters of the tool.

Properties

name string

The name of the tool.

arguments string

The input parameters for the tool, in JSON string format.

Given the randomness of LLM responses, the output JSON string may not always align with your function. We recommend that you validate parameter integrity before passing them to the function.

index integer

The index of the tool information within thetool_callsarray.

id string

The tool response ID.

type string

The type of the tool. Valid value:function.

usage object

The token consumed by this request.

Properties

input_tokens integer

The number of tokens converted from the user input.

output_tokens integer

The number of tokens converted from the model response.

total_tokens integer

The sum of input_tokens and output_tokens. This parameter is returned if the input is plain text.

image_tokens integer

The number of tokens of the input image. This parameter is returned if image is specified.

Error codes

If the request failed and error message is returned, see Status codes for troubleshooting.