阿里云大模型服务平台百炼首次调用千问API教程：OpenAI接口、DashScope SDK等接入方式-阿里云开发者社区

阿里云百炼支持通过API调用大模型，涵盖OpenAI兼容接口、DashScope SDK等接入方式。阿里云大模型服务平台百炼调用千问API的完整流程可分为账号准备、环境配置、API调用方式选择及实际请求执行四个核心步骤，具体如下：

阿里云百炼产品.png

一、账号设置

1.注册账号：若无阿里云账号，需首先注册。
2.开通阿里云百炼：使用阿里云主账号前往阿里云百炼大模型服务平台：https://www.aliyun.com/product/bailian 阅读并同意协议后，将自动开通阿里云百炼，如果未弹出服务协议，则表示您已经开通。

阿里云百炼使用展示.png

3.获取API Key：前往API Key页面，单击创建API Key，即可通过API KEY调用大模型。

4.获取业务空间ID：使用华北2（北京）、新加坡、日本（东京）或德国（法兰克福）地域的模型时，需在Base URL中填入业务空间ID（WorkspaceId），可在业务空间管理页面中查看。

二、配置API Key到环境变量

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

2.1 Linux系统

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

1.执行以下命令来将环境变量设置追加到~/.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以保存并关闭文件。

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

```
source ~/.bashrc
```

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

```
echo $DASHSCOPE_API_KEY
```

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

1.执行以下命令。

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

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

```
echo $DASHSCOPE_API_KEY
```

2.2 macOS系统

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

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

```
echo $SHELL
```

2.根据默认Shell类型进行操作。

####### Zsh

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以保存并关闭文件。

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

    ```
    source ~/.zshrc
    ```

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

    ```
    echo $DASHSCOPE_API_KEY
    ```


####### Bash

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以保存并关闭文件。

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

    ```
    source ~/.bash_profile
    ```

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

    ```
    echo $DASHSCOPE_API_KEY
    ```

添加临时性环境变量

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

以下命令适用于 Zsh 和 Bash。

执行以下命令。

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

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

2.3 Windows系统

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

1、系统属性

在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-ee16697?fe4
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>

2、CMD

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

在CMD中运行以下命令。

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

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

3、添加临时性环境变量

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

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

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

echo %DASHSCOPE_API_KEY%

4、PowerShell

添加永久性环境变量
如果您希望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

步骤 1：配置Python环境

检查您的Python版本

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

您的Python需要为3.8或以上版本。

python -V
pip --version

以Windows的CMD为例：

常见问题

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

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

解决办法如下：

# Windows系统

请确认是否已参考安装Python 在您的计算环境中安装Python，并将python.exe添加至环境变量PATH中。
如果已安装了Python并添加了环境变量，仍报此错，请关闭当前终端，重新打开一个新的终端窗口，再进行尝试。

Linux、macOS系统

请确认是否已参考安装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

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

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

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

安装 DashScope 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

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

新建一个文件，命名为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="qwen-plus",  # 模型列表: 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，则需在文件名前指定具体文件路径。

运行后您将会看到输出结果：
```
我是阿里云开发的一款超大规模语言模型，我叫千问。
```

DashScope Python SDK

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

新建一个文件，命名为hello_qwen.py。

将以下代码复制到hello_qwen.py中并保存。

import os
from dashscope import Generation
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': 'You are a helpful assistant.'},
    {'role': 'user', 'content': '你是谁？'}
]
response = Generation.call(
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key = "sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"), 
    model="qwen-plus",   # 模型列表：https://help.aliyun.com/model-studio/getting-started/models
    messages=messages,
    result_format="message"
)

if response.status_code == 200:
    print(response.output.choices[0].message.content)
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文件所在目录执行，如果想要在任意位置执行，请在文件名前指定具体文件路径。

运行后您将会看到输出结果：
```
我是来自阿里云的大规模语言模型，我叫千问。
```

Node.js

步骤 1：配置Node.js环境

检查Node.js安装状态

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

node -v
npm -v

以Windows的CMD为例：

这将打印出您当前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: "qwen-plus",  //模型列表: 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。

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

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

Java

步骤 1：配置Java环境

检查您的Java版本

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

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

以Windows的CMD为例：

为了使用DashScope Java SDK，您的Java需要在Java 8或以上版本。您可以查看打印信息中的第一行确认Java版本，例如打印信息：openjdk version "16.0.1" 2021-04-20表明当前Java版本为Java 16。

安装模型调用SDK

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

XML

打开您的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集成开发环境为例：

Gradle

打开您的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集成开发环境为例：

步骤 2：调用大模型API

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

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.protocol.Protocol;

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        // 以下为华北2（北京）地域的URL，各地域的URL不同。调用时请将WorkspaceId替换为真实的业务空间ID。
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://{WorkspaceId}.cn-beijing.maas.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("你是谁？")
                .build();
        GenerationParam param = GenerationParam.builder()
                // 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 模型列表：https://help.aliyun.com/model-studio/getting-started/models
                .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(result.getOutput().getChoices().get(0).getMessage().getContent());
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.err.println("错误信息："+e.getMessage());
            System.out.println("请参考文档：https://help.aliyun.com/model-studio/developer-reference/error-code");
        }
        System.exit(0);
    }
}

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

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

curl

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

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

OpenAI兼容-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\": \"qwen-plus\",
    \"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": "qwen-plus",
    "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": "qwen-plus",
    "id": "chatcmpl-39799876-eda8-9527-9e14-2214d641cf9a"
}

DashScope-HTTP

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

Windows

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

Linux/macOS

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/text-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "input":{
        "messages":[
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "你是谁？"
            }
        ]
    },
    "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: "qwen-plus",
        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)
}

PHP

<?php
// 设置请求的URL
// 以下为华北2（北京）地域的URL，各地域的URL不同。调用时请将WorkspaceId替换为真实的业务空间ID。
$url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions';
// 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：$apiKey = "sk-xxx";
$apiKey = getenv('DASHSCOPE_API_KEY');
// 设置请求头
$headers = [
    'Authorization: Bearer '.$apiKey,
    'Content-Type: application/json'
];
// 设置请求体
$data = [
    // 模型列表：https://help.aliyun.com/model-studio/getting-started/models
    "model" => "qwen-plus",
    "messages" => [
        [
            "role" => "system",
            "content" => "You are a helpful assistant."
        ],
        [
            "role" => "user",
            "content" => "你是谁？"
        ]
    ]
];
// 初始化cURL会话
$ch = curl_init();
// 设置cURL选项
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
// 执行cURL会话
$response = curl_exec($ch);
// 检查是否有错误发生
if (curl_errno($ch)) {
    echo 'Curl error: ' . curl_error($ch);
}
// 关闭cURL资源
curl_close($ch);
// 输出响应结果
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)
    {
        // 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：string? apiKey = "sk-xxx";
        string? apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY");

        if (string.IsNullOrEmpty(apiKey))
        {
            Console.WriteLine("API Key 未设置。请确保环境变量 'DASHSCOPE_API_KEY' 已设置。");
            return;
        }
        // 以下为华北2（北京）地域的URL，各地域的URL不同。调用时请将WorkspaceId替换为真实的业务空间ID。
        string url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions";
        // 模型列表：https://help.aliyun.com/model-studio/getting-started/models
        string jsonContent = @"{
            ""model"": ""qwen-plus"",
            ""messages"": [
                {
                    ""role"": ""system"",
                    ""content"": ""You are a helpful assistant.""
                },
                {
                    ""role"": ""user"", 
                    ""content"": ""你是谁？""
                }
            ]
        }";

        // 发送请求并获取响应
        string result = await SendPostRequestAsync(url, jsonContent, apiKey);

        // 输出结果
        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"))
        {
            // 设置请求头
            httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
            httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

            // 发送请求并获取响应
            HttpResponseMessage response = await httpClient.PostAsync(url, content);

            // 处理响应
            if (response.IsSuccessStatusCode)
            {
                return await response.Content.ReadAsStringAsync();
            }
            else
            {
                return $"请求失败: {response.StatusCode}";
            }
        }
    }
}

四、调用智能体应用（可选高级用法）

若您已通过百炼控制台创建了智能体应用（如客服问答机器人），则可通过专属应用 API 调用，此时需提供：

应用 ID（Application ID）
API Key
请求地址为智能体应用专用端点

多轮对话需在请求中显式传入历史消息（含 role 为 user 和 assistant 的交替记录），并可复用 session_id 维持上下文。

五、注意事项与常见问题

地域限制：部分功能（如 DeepSeek 模型）仅支持特定地域（如北京）。
Token 计费：调用量约一小时后可在百炼控制台的模型监控页面查看 input_tokens 与 output_tokens 消耗情况。
网页解析能力：千问 API 本身无法直接访问或解析网页链接，需结合 Function Calling 或外部爬虫工具提取内容后再输入模型。
错误处理：若返回 code=401, message=Invalid API-key provided，说明 API Key 无效或未正确传递。

2026年阿里云AI产品与云产品优惠权益参考：
AI 产品权益主要包括阿里云百炼 Token Plan，提供多档位套餐，包月预算可控；HappyHorse-1.1 系列模型限时 6 折；阿里云百炼 Token Plan，提供多档位套餐，包月预算可控；Qwen3.6全模型通享 4.5 折；Qwen3.7-Max 发布限时 5 折；阿里云百炼优惠券，先用后返，最高200元，个企同享；阿里云 JVS Claw 39元起，一键接入 OpenClaw等。而云产品权益主要有轻量应用服务器限时抢购2核2G38元/年、2核4G9.9元1个月、199元/年；经济型e实例3.9折，通用算力型u2i实例3折，九代c9i、g9i、r9i等实例1年付6.4折起等优惠权益。详情可通过阿里云权益中心了解：https://www.aliyun.com/benefit

AI产品权益2026.png

综上，调用千问 API 的核心在于正确配置鉴权信息（API Key + WorkspaceId）、选择合适的接口模式（OpenAI 兼容或 DashScope 原生），并通过标准 HTTP 或 SDK 发起请求。对于无编程经验的用户，亦可使用 Chatbox 图形界面 直接与模型交互。

阿里云大模型服务平台百炼首次调用千问API教程：OpenAI接口、DashScope SDK等接入方式

一、账号设置

二、配置API Key到环境变量

2.1 Linux系统

2.2 macOS系统

添加临时性环境变量

2.3 Windows系统

用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY

三、选择开发语言

Python

步骤 1：配置Python环境

检查您的Python版本

常见问题

# Windows系统

Linux、macOS系统

配置虚拟环境（可选）

安装OpenAI Python SDK或DashScope Python SDK

安装 OpenAI Python SDK

安装 DashScope Python SDK

步骤 2：调用大模型API

OpenAI Python SDK

DashScope Python SDK

Node.js

步骤 1：配置Node.js环境

检查Node.js安装状态

安装模型调用SDK

步骤 2：调用大模型API

Java

步骤 1：配置Java环境

检查您的Java版本

安装模型调用SDK

XML

Gradle

步骤 2：调用大模型API

curl

OpenAI兼容-HTTP

DashScope-HTTP

其它语言

四、调用智能体应用（可选高级用法）

五、注意事项与常见问题

阿里云百炼

热门文章

最新文章

相关电子书