首次调用千问API - 阿里云百炼

若您熟悉大模型调用，可直接查看API参考文档文本生成。
若您不熟悉编程，可参考Chatbox，通过图形化界面与千问模型对话。
API调用与操作系统版本无关，只要网络能连通即可正常使用。

本文以千问为例，引导您完成大模型API调用。您将了解到：

如何获取 API Key
如何配置本地开发环境
如何调用千问 API

账号设置

注册账号：若无阿里云账号，需首先注册。
如遇问题，请参见注册阿里云账号。
开通阿里云百炼：使用阿里云主账号前往阿里云百炼大模型服务平台，阅读并同意协议后，将自动开通阿里云百炼，如果未弹出服务协议，则表示您已经开通。
如果开通服务时提示“您尚未进行实名认证”，请先进行实名认证。
获取API Key：前往API Key页面，单击创建API Key，即可通过API KEY调用大模型。创建 API Key 时无需选择模型，调用时通过请求体中的model参数指定要调用的模型（例如model="qwen-plus"），可用模型请参见模型列表。如需限制该 API Key 可调用的模型范围，创建时选择自定义权限，并开启访问模型范围开关，开启后该 API Key 仅能调用已选择的模型。
获取业务空间ID：使用华北2（北京）、新加坡、日本（东京）或德国（法兰克福）地域的模型时，需在Base URL中填入业务空间ID（WorkspaceId），可在业务空间管理页面中查看。

配置API Key到环境变量

建议您把API Key配置到环境变量，避免在代码里显式地配置API Key，降低泄露风险。

配置步骤

Linux系统
macOS系统
Windows系统

添加永久性环境变量
添加临时性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。

执行以下命令来将环境变量设置追加到~/.bashrc文件中。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc

也可以手动修改~/.bashrc文件。

手动修改

执行以下命令，打开~/.bashrc文件。

nano ~/.bashrc

在配置文件中添加以下内容。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

在nano编辑器中，按Ctrl + X，接着按Y，再按Enter以保存并关闭文件。

执行以下命令，使变更生效。

source ~/.bashrc

重新打开一个终端窗口，运行以下命令检查环境变量是否生效。

echo $DASHSCOPE_API_KEY

如果您仅希望在当前会话中使用该环境变量，可以添加临时性环境变量。

执行以下命令。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

执行以下命令，验证该环境变量是否生效。

echo $DASHSCOPE_API_KEY

添加永久性环境变量
添加临时性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。

在终端中执行以下命令，查看默认Shell类型。

echo $SHELL

根据默认Shell类型进行操作。
- Zsh
- Bash
1. 执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。
# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.zshrc
也可以手动修改~/.zshrc 文件。
手动修改
执行以下命令，打开Shell配置文件。
nano ~/.zshrc
在配置文件中添加以下内容。
# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
在nano编辑器中，按Ctrl + X，接着按Y，再按Enter以保存并关闭文件。
1. 执行以下命令，使变更生效。
source ~/.zshrc
1. 重新打开一个终端窗口，运行以下命令检查环境变量是否生效。
echo $DASHSCOPE_API_KEY
1. 执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。
# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bash_profile
也可以手动修改~/.bash_profile 文件。
手动修改
执行以下命令，打开Shell配置文件。
nano ~/.bash_profile
在配置文件中添加以下内容。
# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
在nano编辑器中，按Ctrl + X，接着按Y，再按Enter以保存并关闭文件。
1. 执行以下命令，使变更生效。
source ~/.bash_profile
1. 重新打开一个终端窗口，运行以下命令检查环境变量是否生效。
echo $DASHSCOPE_API_KEY

如果您仅希望在当前会话中使用该环境变量，可以添加临时性环境变量。

以下命令适用于 Zsh 和 Bash。

执行以下命令。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

执行以下命令，验证该环境变量是否生效。

echo $DASHSCOPE_API_KEY

在Windows系统中，您可以通过系统属性、CMD或PowerShell配置环境变量。

系统属性
CMD
PowerShell

此方式配置的环境变量永久生效。
修改系统环境变量需具备管理员权限。
配置环境变量后不会立即影响已经打开的命令窗口、IDE或其他正在运行的应用程序。您需要重新启动这些程序或者打开新的命令行使环境变量生效。

在Windows系统桌面中按Win+Q键，在搜索框中搜索编辑系统环境变量，单击打开系统属性界面。
在系统属性窗口，单击环境变量，然后在系统变量区域下单击新建，变量名填入DASHSCOPE_API_KEY，变量值填入您的DashScope API Key。
依次单击三个窗口的确定，关闭系统属性配置页面，完成环境变量配置。
打开CMD（命令提示符）窗口或Windows PowerShell窗口，执行如下命令检查环境变量是否生效。
- CMD查询命令：

echo %DASHSCOPE_API_KEY%

Microsoft Windows [版本 10.0.19045.5371]
(c) Microsoft Corporation。保留所有权利。
C:\Windows\system32>echo %DASHSCOPE_API_KEY%
sk-ee166797fe40xxx
C:\Windows\system32>

Windows PowerShell查询命令：

echo $env:DASHSCOPE_API_KEY

Windows PowerShell
版权所有 (C) Microsoft Corporation。保留所有权利。
尝试新的跨平台 PowerShell https://aka.ms/pscore6
PS C:\Windows\system32> echo $env:DASHSCOPE_API_KEY
sk-ee166797fe40xxx
PS C:\Windows\system32>

添加永久性环境变量
添加临时性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以按如下操作。

在CMD中运行以下命令。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
setx DASHSCOPE_API_KEY "YOUR_DASHSCOPE_API_KEY"

打开一个新的CMD窗口。
在新的CMD窗口运行以下命令，检查环境变量是否生效。

echo %DASHSCOPE_API_KEY%

如果您仅希望在当前会话中使用该环境变量，可以在CMD中运行以下命令。

REM 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
set DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

您可以在当前会话运行以下命令检查环境变量是否生效。

echo %DASHSCOPE_API_KEY%

添加永久性环境变量
添加临时性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以按如下操作。

在PowerShell中运行以下命令。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "YOUR_DASHSCOPE_API_KEY", [EnvironmentVariableTarget]::User)

打开一个新的PowerShell窗口。
在新的PowerShell窗口运行以下命令，检查环境变量是否生效。

echo $env:DASHSCOPE_API_KEY

如果您仅希望在当前会话中使用该环境变量，可以在PowerShell中运行以下命令。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
$env:DASHSCOPE_API_KEY = "YOUR_DASHSCOPE_API_KEY"

您可以在当前会话运行以下命令检查环境变量是否生效。

echo $env:DASHSCOPE_API_KEY

选择开发语言

选择您熟悉的语言或工具，用于调用大模型API。

Python
Node.js
Java
curl
其它语言

步骤 1：配置Python环境

检查您的Python版本

您的Python需要为3.8或以上版本，请您参考安装Python进行安装。您可以在终端中输入以下命令查看当前计算环境是否安装了Python和pip：

python -V
pip --version

以Windows的CMD为例：

C:\Users\Administrator>python -V
Python 3.13.2

C:\Users\Administrator>pip --version
pip 24.3.1 from C:\Users\Administrator\AppData\Local\Programs\Python\Python313\Lib\site-packages\pip (python 3.13)

常见问题

Q：执行python -V、pip --version报错：

'python' 不是内部或外部命令，也不是可运行的程序或批处理文件。
'pip' 不是内部或外部命令，也不是可运行的程序或批处理文件。
-bash: python: command not found
-bash: pip: command not found

解决办法如下：

Windows系统
Linux、macOS系统

请确认是否已参考安装Python，在您的计算环境中安装Python，并将python.exe添加至环境变量PATH中。安装 Python 3.13.2 时，在安装向导底部勾选Add python.exe to PATH，将 Python 添加到系统环境变量，然后单击Install Now完成安装。
如果已安装了Python并添加了环境变量，仍报此错，请关闭当前终端，重新打开一个新的终端窗口，再进行尝试。

请确认是否已参考安装Python，在您的计算环境中安装的Python。
如果已安装Python后，仍报此错，请输入which python pip命令查询系统中是否有python、pip。
- 如果返回如下结果，请关闭当前连接终端，重新打开一个新的终端窗口，再进行尝试。

/usr/bin/python
/usr/bin/pip

如果返回如下结果，则再次输入which python3 pip3查询。

/usr/bin/which: no python in (/root/.local/bin:/root/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin)
/usr/bin/which: no pip in (/root/.local/bin:/root/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin)

如果返回结果如下，则使用python3 -V、pip3 --version查询版本。

/usr/bin/python3
/usr/bin/pip3

配置虚拟环境（可选）

如果您的Python已安装完成，可以创建一个虚拟环境来安装OpenAI Python SDK或DashScope Python SDK，这可以帮助您避免与其它项目发生依赖冲突。

创建虚拟环境 您可以运行以下命令，创建一个命名为.venv的虚拟环境：

# 如果运行失败，您可以将python替换成python3再运行
python -m venv .venv

激活虚拟环境 若您使用Windows系统，请运行以下命令来激活虚拟环境：

.venv\Scripts\activate

如果您使用macOS或者Linux系统，请运行以下命令来激活虚拟环境：

source .venv/bin/activate

安装 OpenAI Python SDK或DashScope Python SDK

您可以通过OpenAI的Python SDK或DashScope的Python SDK来调用阿里云百炼平台上的模型。

安装 OpenAI Python SDK
安装 DashScope Python SDK

通过运行以下命令安装或升级 OpenAI Python SDK：

# 如果运行失败，您可以将pip替换成pip3再运行
pip install -U openai

当终端出现Successfully installed ... openai-x.x.x的提示后，表示您已经成功安装OpenAI Python SDK。

通过运行以下命令安装或升级 DashScope Python SDK：

# 如果运行失败，您可以将pip替换成pip3再运行
pip install -U dashscope

当终端出现Successfully installed ... dashscope-x.x.x的提示后，表示您已经成功安装DashScope Python SDK。

步骤 2：调用大模型API

OpenAI Python SDK
DashScope Python SDK

如果您安装完成了Python以及OpenAI的Python SDK，可以参考以下步骤发送您的API请求。

示例代码中的import os用于读取环境变量，请勿省略。如果您使用.env文件管理API Key，需同时导入os和dotenv：

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv("DASHSCOPE_API_KEY")

缺少import os会导致NameError，请勿将其误判为.env文件加载失败。

新建一个文件，命名为hello_qwen.py。
将以下代码复制到hello_qwen.py中并保存。

import os
from openai import OpenAI

try:
    client = OpenAI(
        # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为: api_key="sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # 以下为华北2（北京）地域的URL，各地域的URL不同。调用时请将{WorkspaceId}替换为真实的业务空间ID。
        base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
    )

    completion = client.chat.completions.create(
        model="qwen3.8-max",  # 模型列表: https://help.aliyun.com/model-studio/getting-started/models
        messages=[
            {'role': 'system', 'content': 'You are a helpful assistant.'},
            {'role': 'user', 'content': '你是谁？'}
        ]
    )
    print(completion.choices[0].message.content)
except Exception as e:
    print(f"错误信息：{e}")
    print("请参考文档：https://help.aliyun.com/model-studio/developer-reference/error-code")

通过命令行运行python hello_qwen.py或python3 hello_qwen.py。
若提示No such file or directory，则需在文件名前指定具体文件路径。
运行后您将会看到输出结果：

我是阿里云开发的一款超大规模语言模型，我叫千问。

如果您安装完成了Python以及DashScope的Python SDK，可以参考以下步骤发送您的API请求。

新建一个文件，命名为hello_qwen.py。
将以下代码复制到hello_qwen.py中并保存。

import os
from dashscope import MultiModalConversation
import dashscope

# 以下为华北2（北京）地域的URL，各地域的URL不同。调用时请将{WorkspaceId}替换为真实的业务空间ID。
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'
messages = [
    {'role': 'system', 'content': [{'text': 'You are a helpful assistant.'}]},
    {'role': 'user', 'content': [{'text': '你是谁？'}]}
]
response = MultiModalConversation.call(
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key = "sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen3.8-max",   # 模型列表：https://help.aliyun.com/model-studio/getting-started/models
    messages=messages,
)

if response.status_code == 200:
    print(response.output.choices[0].message.content[0]["text"])
else:
    print(f"HTTP返回码：{response.status_code}")
    print(f"错误码：{response.code}")
    print(f"错误信息：{response.message}")
    print("请参考文档：https://help.aliyun.com/model-studio/developer-reference/error-code")

通过命令行运行python hello_qwen.py或python3 hello_qwen.py。
本示例使用的运行命令需在Python文件所在目录执行，如果想要在任意位置执行，请在文件名前指定具体文件路径。
运行后您将会看到输出结果：

我是来自阿里云的大规模语言模型，我叫千问。

步骤 1：配置Node.js环境

检查Node.js安装状态

您可以在终端中输入以下命令查看当前计算环境是否安装了Node.js和npm：

node -v
npm -v

以Windows的CMD为例：

C:\Users\Administrator>node -v
v22.14.0

C:\Users\Administrator>npm -v
10.9.2

这将打印出您当前Node.js 版本。如果您的环境中没有Node.js，请访问Node.js官网进行下载。

安装模型调用SDK

您可以在终端运行以下命令：

npm install --save openai
# 或者
yarn add openai

如果安装失败，您可以通过配置镜像源的方法来完成安装，如：

npm config set registry https://registry.npmmirror.com/

配置镜像源后，您可以重新运行安装SDK的命令。

当终端出现added xx package in xxs的提示后，表示您已经成功安装OpenAI SDK。您可以使用npm list openai查询具体版本信息。

步骤 2：调用大模型API

新建一个hello_qwen.mjs文件。
将以下代码复制到文件中。

import OpenAI from "openai";

try {
    const openai = new OpenAI(
        {
            // 若没有配置环境变量，请用阿里云百炼API Key将下行替换为: apiKey: "sk-xxx",
            apiKey: process.env.DASHSCOPE_API_KEY,
            // 以下为华北2（北京）地域的URL，各地域的URL不同。调用时请将{WorkspaceId}替换为真实的业务空间ID。
            baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
        }
    );
    const completion = await openai.chat.completions.create({
        model: "qwen3.8-max",  //模型列表: https://help.aliyun.com/model-studio/getting-started/models
        messages: [
            { role: "system", content: "You are a helpful assistant." },
            { role: "user", content: "你是谁？" }
        ],
    });
    console.log(completion.choices[0].message.content);
} catch (error) {
    console.log(`错误信息：${error}`);
    console.log("请参考文档：https://help.aliyun.com/model-studio/developer-reference/error-code");
}

通过命令行运行以下命令来发送API请求：

node hello_qwen.mjs

本示例使用的运行命令需在hello_qwen.mjs文件所在目录执行，如果想要在任意位置执行，请在文件名前指定具体文件路径。
请确保已在hello_qwen.mjs文件所在目录中安装了SDK，如果SDK与文件不在同一目录下，则会报错Cannot find package 'openai' imported from xxx。

运行成功后您将会看到输出结果：

PS D:\node_project> node hello_qwen.mjs
(node:25072) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
我是来自阿里云的语言模型，我叫通义千问。
PS D:\node_project>

步骤 1：配置Java环境

检查您的Java版本

您可以在终端运行以下命令：

java -version
# （可选）如果使用maven管理和构建java项目，还需确保maven已正确安装到您的开发环境中
mvn --version

以Windows的CMD为例：

C:\Users\Administrator>java --version
java 23.0.2 2025-01-21
Java(TM) SE Runtime Environment (build 23.0.2+7-58)
Java HotSpot(TM) 64-Bit Server VM (build 23.0.2+7-58, mixed mode, sharing)

C:\Users\Administrator>mvn --version
Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: C:\Program Files\apache-maven-3.9.9
Java version: 23.0.2

为了使用DashScope Java SDK，您的Java需要在Java 8或以上版本。您可以查看打印信息中的第一行确认Java版本，例如打印信息：openjdk version "16.0.1" 2021-04-20表明当前Java版本为Java 16。如果您当前计算环境没有Java，或版本低于Java 8，请前往Java下载进行下载与安装。

安装模型调用SDK

如果您的环境中已安装Java，请安装DashScope Java SDK。SDK的版本请参考：DashScope Java SDK。执行以下命令来添加 Java SDK 依赖，并将 the-latest-version 替换为最新的版本号。

XML
Gradle

打开您的Maven项目的pom.xml文件。
在<dependencies>标签内添加以下依赖信息。

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <!-- 请将 'the-latest-version' 替换为最新版本号：https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java -->
    <version>the-latest-version</version>
</dependency>

保存pom.xml文件。
使用Maven命令（如mvn compile或mvn clean install）来更新项目依赖，这样Maven会自动下载并添加DashScope Java SDK到您的项目中。

以Windows的IDEA集成开发环境为例：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema ...
    <url>http://maven.apache.org</url>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>dashscope-sdk-java</artifactId>
            <!-- 请将 'the-latest-version' 替换为最新版本号：https://mvnrepository.com/artifact/com.alibaba... -->
            <version>2.18.2</version>
        </dependency>
    </dependencies>
</project>

~\Desktop\test_project
mvn compile
[INFO] Scanning for projects...
[INFO]
[INFO] ----------------------< org.example:test_project >----------------------
[INFO] Building test_project 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ test_project ---
[INFO] skip non existing resourceDirectory C:\Users\Administrator\Desktop\test_project\src\main\resources
[INFO]
[INFO] --- compiler:3.13.0:compile (default-compile) @ test_project ---
[INFO] Nothing to compile - all classes are up to date.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  0.627 s
[INFO] Finished at: 2025-02-17T13:15:30+08:00
[INFO] ------------------------------------------------------------------------

打开您的Gradle项目的build.gradle文件。
在dependencies块内添加以下依赖信息。

dependencies {
    // 请将 'the-latest-version' 替换为最新版本号：https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
    implementation group: 'com.alibaba', name: 'dashscope-sdk-java', version: 'the-latest-version'
}

保存build.gradle文件。
在命令行中，切换到您的项目根目录，执行以下Gradle命令来更新项目依赖。这将会自动下载并添加DashScope Java SDK到您的项目中。

./gradlew build --refresh-dependencies

以Windows的IDEA集成开发环境为例：build.gradle 完整文件示例：

group = 'org.example'
version = '1.0-SNAPSHOT'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.apache.groovy:groovy:4.0.14'
    testImplementation platform('org.junit:junit-bom:5.10.0')
    testImplementation 'org.junit.jupiter:junit-jupiter'
    implementation group: 'com.alibaba', name: 'dashscope-sdk-java', version: '2.18.2'
}

test {
    useJUnitPlatform()
}

执行构建命令后，终端输出结果：

~/Desktop/test_project
./gradlew build --refresh-dependencies

Welcome to Gradle 8.10!

Here are the highlights of this release:
  - Support for Java 23
  - Faster configuration cache
  - Better configuration cache reports

For more details see https://docs.gradle.org/8.10/release-notes.html

BUILD SUCCESSFUL in 7m 51s
2 actionable tasks: 2 executed

步骤 2：调用大模型API

您可以运行以下代码来调用大模型API。

import java.util.Arrays;
import java.lang.System;
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 java.util.Collections;
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.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {Constants.baseHttpApiUrl="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";}
    public static MultiModalConversationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage systemMsg = MultiModalMessage.builder()
                .role(Role.SYSTEM.getValue())
                .content(Arrays.asList(Collections.singletonMap("text", "You are a helpful assistant.")))
                .build();
        MultiModalMessage userMsg = MultiModalMessage.builder()
                .role(Role.USER.getValue())
                .content(Arrays.asList(Collections.singletonMap("text", "你是谁？")))
                .build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 模型列表：https://help.aliyun.com/model-studio/getting-started/models
                .model("qwen3.8-max")
                .messages(Arrays.asList(systemMsg, userMsg))
                .build();
        return conv.call(param);
    }
    public static void main(String[] args) {
        try {
            MultiModalConversationResult result = callWithMessage();
            System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
        } catch (ApiException | NoApiKeyException | InputRequiredException | UploadFileException e) {
            System.err.println("错误信息："+e.getMessage());
            System.out.println("请参考文档：https://help.aliyun.com/model-studio/developer-reference/error-code");
        }
        System.exit(0);
    }
}

运行后您将会看到对应的输出结果：

我是阿里云开发的一款超大规模语言模型，我叫千问。

您可以通过OpenAI兼容的HTTP方式或DashScope的HTTP方式来调用阿里云百炼平台上的模型。模型列表请参考：选择模型。

若没有配置环境变量，请用阿里云百炼API Key将：-H "Authorization: Bearer $DASHSCOPE_API_KEY" \ 换为：-H "Authorization: Bearer sk-xxx" \ 。

OpenAI兼容-HTTP
DashScope-HTTP

您可以运行以下命令发送API请求：

Windows

curl -X POST "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions" ^
-H "Authorization: Bearer %DASHSCOPE_API_KEY%" ^
-H "Content-Type: application/json" ^
-d "{
    \"model\": \"qwen3.8-max\",
    \"messages\": [
        {
            \"role\": \"system\",
            \"content\": \"You are a helpful assistant.\"
        },
        {
            \"role\": \"user\",
            \"content\": \"你是谁？\"
        }
    ]
}"

Linux/macOS

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3.8-max",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "你是谁？"
        }
    ]
}'

发送API请求后，可以得到以下回复：

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "我是来自阿里云的大规模语言模型，我叫千问。"
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 22,
        "completion_tokens": 16,
        "total_tokens": 38
    },
    "created": 1728353155,
    "system_fingerprint": null,
    "model": "qwen3.8-max",
    "id": "chatcmpl-39799876-eda8-9527-9e14-2214d641cf9a"
}

您可以运行以下命令发送API请求：

Windows

curl -X POST "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" ^
-H "Authorization: Bearer %DASHSCOPE_API_KEY%" ^
-H "Content-Type: application/json" ^
-d "{
  \"model\": \"qwen3.8-max\",
  \"input\": {
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": [{\"text\": \"You are a helpful assistant.\"}]
      },
      {
        \"role\": \"user\",
        \"content\": [{\"text\": \"你是谁？\"}]
      }
    ]
  },
  \"parameters\": {
    \"result_format\": \"message\"
  }
}"

Linux/macOS

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3.8-max",
    "input":{
        "messages":[
            {
                "role": "system",
                "content": [{"text": "You are a helpful assistant."}]
            },
            {
                "role": "user",
                "content": [{"text": "你是谁？"}]
            }
        ]
    },
    "parameters": {
        "result_format":"message"
    }
}'

发送API请求后，可以得到以下回复：

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "我是来自阿里云的大规模语言模型，我叫千问。"
                }
            }
        ]
    },
    "usage": {
        "total_tokens": 38,
        "output_tokens": 16,
        "input_tokens": 22
    },
    "request_id": "87f776d7-3c82-9d39-b238-d1ad38c9b6a9"
}

调用大模型API

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() {
	// 创建 HTTP 客户端
	client := &http.Client{}
	// 构建请求体
	requestBody := RequestBody{
		// 模型列表：https://help.aliyun.com/model-studio/getting-started/models
		Model: "qwen3.8-max",
		Messages: []Message{
			{
				Role:    "system",
				Content: "You are a helpful assistant.",
			},
			{
				Role:    "user",
				Content: "你是谁？",
			},
		},
	}
	jsonData, err := json.Marshal(requestBody)
	if err != nil {
		log.Fatal(err)
	}
	// 创建 POST 请求
	// 以下为华北2（北京）地域的URL，各地域的URL不同。调用时请将{WorkspaceId}替换为真实的业务空间ID。
	req, err := http.NewRequest("POST", "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions", bytes.NewBuffer(jsonData))
	if err != nil {
		log.Fatal(err)
	}
	// 设置请求头
	// 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：apiKey := "sk-xxx"
	apiKey := os.Getenv("DASHSCOPE_API_KEY")
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	// 发送请求
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	// 读取响应体
	bodyText, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	// 打印响应内容
	fmt.Printf("%s\n", bodyText)
}

API参考

关于千问API的输入输出参数，请参见文本生成。
关于其他模型，请参见选择模型。

常见问题

免费额度用完后如何购买 Token？

A：您可以访问费用与成本中心，确保您的账户没有欠费即可调用千问模型。

调用千问模型会自动扣费，出账周期为分钟级（即一条账单代表一分钟内的费用）。消费明细请前往账单详情进行查看。

调用大模型API后报错`Model.AccessDenied`，如何处理？

A：该报错是因为您使用子业务空间的API Key，子业务空间无法访问主账号空间的应用或模型。使用子空间API Key需由主账号管理员为对应子空间开通模型授权（如本文使用qwen3.8-max模型）。详细操作步骤请参见设置模型调用权限。

如何接入Chatbox、Cherry Studio、Cline或Dify？

A：请根据您的使用情况参考以下步骤：

此处以使用较多的工具为例，其它大模型工具接入的方法较为类似。

Chatbox
Cherry Studio
Cline
Dify

请参见Chatbox。

单击左下角的设置按钮，在模型服务栏中找到阿里云百炼，API 密钥输入您的 API Key，获取方法请参见：获取与配置 API Key；API 地址填入https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/（请将WorkspaceId替换为业务空间ID）；单击添加。
在模型 ID填入您需要使用的千问模型，此处以 qwen3.8-max 为例（更多可用的模型请参考选择模型中的千问模型）； 模型名称与分组名称会自动生成。
在界面上方选中添加的模型，部分模型支持联网搜索，打开输入框处的联网搜索按钮。输入“杭州天气咋样？”进行测试：联网搜索按钮为输入框下方工具栏中的地球图标。开启后，模型成功返回杭州实时天气信息及未来几天天气预报，验证联网搜索功能正常。

下一步

查看更多模型	示例代码以 qwen3.8-max 模型为例，阿里云百炼还支持其他千问模型与 DeepSeek、Llama 等第三方模型，支持的模型以及对应的API参考文档请参见选择模型。
了解进阶用法	示例代码仅完成了简单问答，如果您想了解千问 API 的更多用法，如流式输出、结构化输出、Function Calling等，请参见概述目录。
在线体验大模型	如果您想像千问官网一样，通过对话框与大模型互动，请访问模型体验。千问官网将千问 API 与联网搜索、网页解析等工具进行了集成，与直接调用千问 API 效果略有差异。图像生成模型仅支持单轮对话，不支持多轮对话编辑。每次生成图片都是独立操作，无法在同一对话上下文中引用上一次的生成结果。如需在原图基础上修改，请将图片保存到本地，单击对话窗口的加号（+）按钮重新上传，然后输入新的编辑指令。
0代码进行大模型微调	通常来说，对大模型微调需要有人工智能知识背景与工程能力，阿里云百炼提供了0代码对大模型进行微调的功能，您仅需提供数据集即可。详情请参见在控制台进行模型调优。
调用自训练模型	如果您在百炼平台部署了自训练模型，调用时需使用模型部署页面生成的模型 code 作为`model`参数，而非模型 ID，否则将报错 Model not exist。详情请参见模型部署简介中的「部署后调用」章节。

​账号设置

​配置API Key到环境变量

​选择开发语言

步骤 1：配置Python环境

常见问题

步骤 2：调用大模型API

​API参考

​常见问题

​免费额度用完后如何购买 Token？

​调用大模型API后报错Model.AccessDenied，如何处理？

​如何接入Chatbox、Cherry Studio、Cline或Dify？

​下一步

账号设置

配置API Key到环境变量

选择开发语言

API参考

常见问题

免费额度用完后如何购买 Token？

调用大模型API后报错`Model.AccessDenied`，如何处理？

如何接入Chatbox、Cherry Studio、Cline或Dify？

下一步