阿里云百炼 API 调用教程：准备 API-Key、配置环境变量和调用 API 流程-阿里云开发者社区

在使用阿里云百炼平台的大模型能力时，API 调用是核心环节 —— 无论是开发 AI 应用、测试模型效果，还是搭建智能服务，都需要通过 API 将大模型能力集成到自己的系统中。不过对很多开发者来说，从准备密钥到实际调用的流程可能存在疑问，比如 “API-Key 怎么获取”“环境变量配置有什么用”“不同语言怎么写调用代码”。本文结合最新的实操细节，用通俗的语言把整个流程拆解开，从账号准备到多语言调用，每一步都附具体操作和代码示例，帮大家快速上手。

一、先搞懂基础：为什么需要 API-Key 和环境变量？

在开始操作前，先明确两个关键概念，避免后续步骤只知其然不知其所以然。

阿里云百炼平台：https://www.aliyun.com/product/bailian 打开如下图：

第一个是API-Key，它相当于你访问阿里云百炼 API 的 “身份凭证”。因为百炼平台的 API 调用不是完全免费的（有免费额度，但超额度后会计费），且需要区分不同用户的使用权限，所以每个开发者都需要专属的 API-Key。调用 API 时，平台会通过这个密钥识别你的身份，判断你是否有权限使用某个模型，以及计算你的调用用量，没有 API-Key 就无法发起有效请求。

第二个是环境变量配置，很多新手会疑惑 “为什么不能直接把 API-Key 写在代码里”。直接硬编码在代码里有两个大问题：一是如果代码需要分享给他人，或者上传到 GitHub 等公开平台，密钥很容易泄露，别人可能会用你的密钥产生高额费用；二是后续需要更换密钥时，得在所有用到的代码里逐一修改，非常麻烦。而配置到环境变量中，相当于把密钥存放在操作系统的 “安全仓库” 里，代码只从仓库中读取，既避免泄露风险，又方便统一管理。

另外需要注意，阿里云百炼的 API 调用目前支持北京、新加坡等多个地域的控制台，不同地域的接口地址略有差异，但核心流程一致。本文以北京地域为例，其他地域操作步骤完全相同，只需在后续调用时确认对应的接口域名即可。

更多关于阿里云百炼AI大模型平台的使用教程，请参考官方文档：https://help.aliyun.com/zh/model-studio/what-is-model-studio

二、第一步：账号准备与 API-Key 获取

要获取 API-Key，首先得完成账号注册和百炼服务开通，这是所有操作的前提。整个过程不需要复杂配置，按提示一步步走即可，具体分 3 个小步骤：

1. 注册并登录阿里云主账号

如果已经有阿里云账号（比如用过 ECS、RDS 等其他产品），可以直接跳过注册步骤；如果是新用户，需要先注册账号：

打开阿里云官网，点击右上角 “注册”，支持手机号、邮箱两种注册方式。以手机号为例，输入手机号后接收验证码，设置登录密码，完成账号注册。
注册后直接登录，首次登录可能需要完成实名认证（个人用户填身份证信息，企业用户填营业执照信息），不过百炼平台的免费额度使用通常不强制实名认证，可先跳过后续补充。

2. 开通百炼服务

登录后，需要手动开通百炼服务才能使用 API，步骤如下：

打开阿里云百炼官方控制台（可直接搜索 “阿里云百炼控制台”，或通过链接进入），选择你要使用的地域（推荐选 “北京” 或 “新加坡”，根据业务覆盖范围选择，国内业务优先选北京）。
进入控制台后，会看到 “开通百炼大模型平台” 的提示，点击 “免费体验”—— 这里的 “免费” 是指获得一定的免费调用额度（比如 100 万 Tokens，具体以平台最新提示为准），超额度后会按实际调用量计费，开通时不需要提前付费。
按提示阅读并同意服务协议，点击 “确认开通”，大概 10 秒左右就能完成开通，页面会自动跳转到百炼的主控制台。

3. 创建并获取 API-Key

开通服务后，就能创建专属的 API-Key 了，这一步是核心，操作时要注意保存好密钥：

在百炼控制台左侧菜单栏找到 “密钥管理”，点击进入后选择 “API-Key” 页签 —— 这里要注意，只有主账号或被授予 “API-Key 管理权限” 的子账号才能操作，普通子账号没有创建权限。
点击页面中的 “创建 API-KEY” 按钮，系统不会自动生成历史密钥，必须手动点击创建。创建时不需要填写额外信息，点击后会立即生成一对 “API-Key”（类似 “sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx” 的字符串）。
关键步骤：生成后一定要立即复制保存，因为页面刷新后就无法再次查看完整密钥（只能看到部分隐藏的字符），如果忘记保存，只能删除旧密钥重新创建。建议复制后存到本地的记事本里，后续配置环境变量会用到。

另外需要提醒，一个账号可以创建多个 API-Key，比如不同项目用不同密钥，方便后续区分用量。如果担心密钥泄露，也可以在 “密钥管理” 页面随时删除旧密钥，创建新的，删除后旧密钥会立即失效，避免风险。

三、第二步：配置 API-Key 到环境变量（分系统操作）

环境变量的配置需要根据操作系统来区分，常见的 Windows、macOS、Linux 操作步骤不同，但核心都是 “把 API-Key 存入系统变量，让代码能读取到”。下面分系统详细说明，每一步都附具体命令和验证方法：

1. macOS/Linux 系统配置（两种生效方式）

macOS 和 Linux 的终端操作逻辑类似，主要区别在于默认的 Shell 类型（macOS 默认是 Zsh，Linux 常见的是 Bash），配置时需要对应不同的配置文件。

方式一：永久生效（推荐，一次配置长期可用）

永久生效的原理是把环境变量写入 Shell 的配置文件，每次打开终端都会自动加载，适合长期使用：

首先打开终端（macOS 用 Launchpad 里的 “终端”，Linux 直接打开终端窗口）。
如果是Zsh（macOS 默认） ，执行以下命令（把命令中的 “your-api-key” 换成你刚才保存的实际 API-Key）：bash

运行

echo "export DASHSCOPE_API_KEY='your-api-key'" >> ~/.zshrc && source ~/.zshrc

这个命令的意思是：把 “export DASHSCOPE_API_KEY=' 密钥 '” 这行内容追加到～/.zshrc 文件中，然后立即加载该文件让配置生效。
如果是Bash（Linux 常见，或手动切换的 Shell） ，执行以下命令：bash

运行

echo "export DASHSCOPE_API_KEY='your-api-key'" >> ~/.bash_profile && source ~/.bash_profile

这里用的配置文件是～/.bash_profile，和 Zsh 的配置文件不同，不能混用，否则配置不会生效。

方式二：临时生效（适合短期测试，关闭终端后失效）

如果只是临时测试 API 调用，不想永久配置环境变量，可以用临时生效的方式：

不管是 Zsh 还是 Bash，直接在终端执行以下命令：bash

运行

export DASHSCOPE_API_KEY="your-api-key"

执行后，当前终端窗口中可以读取到这个环境变量，但关闭终端后配置会消失，下次打开需要重新执行。

验证配置是否成功

配置后一定要验证是否生效，避免后续调用时因读取不到密钥报错：

在终端中执行命令：echo $DASHSCOPE_API_KEY
如果输出的是你刚才配置的完整 API-Key，说明配置成功；如果输出空值或错误信息，需要检查命令是否正确，比如配置文件路径是否写错、API-Key 是否输对。

2. Windows 系统配置（分 PowerShell 和 CMD）

Windows 系统有两种常用的命令行工具：PowerShell（推荐，功能更全）和 CMD（传统命令行），两者的环境变量配置方式不同，需要分别操作。

方式一：PowerShell 永久配置（推荐）

永久配置需要修改 PowerShell 的_profile 文件，步骤如下：

打开 PowerShell（按 Win+R，输入 “powershell”，回车）。
首先执行命令查看_profile 文件路径：$PROFILE，系统会输出一个路径，比如 “C:\Users\ 你的用户名 \Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1”。
执行命令创建并编辑这个文件：notepad $PROFILE，如果提示 “文件不存在”，点击 “确定” 创建新文件。
在打开的记事本中，输入以下内容（替换 “your-api-key” 为实际密钥）：powershell

[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "your-api-key", "User")

这里的 “User” 表示配置的是当前用户的环境变量，其他用户登录后不会生效；如果想让所有用户都能用，可把 “User” 换成 “Machine”（需要管理员权限）。
保存记事本并关闭，然后关闭当前 PowerShell 窗口，重新打开一个新窗口 —— 环境变量配置需要重启 PowerShell 才能生效。

方式二：CMD 临时配置（适合短期测试）

如果用 CMD 命令行，只能临时配置环境变量，步骤如下：

按 Win+R，输入 “cmd”，回车打开 CMD 窗口。
执行命令：set DASHSCOPE_API_KEY=your-api-key（注意 “=” 前后不能有空格，否则会把空格当成密钥的一部分）。
这种方式的生效范围仅限当前 CMD 窗口，关闭窗口后配置消失，下次使用需要重新执行命令。

验证配置是否成功

如果是 PowerShell，重新打开后执行命令：[Environment]::GetEnvironmentVariable("DASHSCOPE_API_KEY", "User")，输出完整密钥即成功。
如果是 CMD，执行命令：echo %DASHSCOPE_API_KEY%，输出完整密钥即成功。

四、第三步：调用 API（以 Python 为例，附两种核心方式）

完成密钥和环境变量配置后，就可以正式调用 API 了。Python 是最常用的开发语言，因为它的 SDK 支持完善，代码简洁，适合快速测试。下面介绍两种主流调用方式：OpenAI 兼容接口（适合熟悉 OpenAI 的开发者）和 DashScope SDK（阿里云官方 SDK，功能更全），两种方式都能实现调用，可根据自己的熟悉程度选择。

1. 前置准备：安装依赖库

无论用哪种方式，都需要先安装对应的 Python 库，打开终端（或 CMD/PowerShell）执行以下命令：

bash

运行

pip install -U openai dashscope

“openai” 库用于支持 OpenAI 兼容接口，即使你不用 OpenAI 的服务，也需要安装这个库才能用兼容格式调用百炼 API。
“dashscope” 库是阿里云官方的 SDK，用于直接调用百炼的原生 API。
“-U” 参数表示 “升级到最新版本”，避免因旧版本存在 bug 导致调用失败。

如果执行命令时出现 “pip 不是内部或外部命令” 的错误，说明 Python 的环境变量没配置好，需要先检查 Python 是否正确安装，或手动指定 Python 路径（比如 “python -m pip install ...”）。

2. 方式一：OpenAI 兼容接口

很多开发者之前用过 OpenAI 的 API，百炼提供了兼容 OpenAI 的接口格式，意味着你可以几乎不修改原有代码，只需更换 API-Key 和接口地址，就能调用百炼的模型（比如通义千问、DeepSeek 等）。

代码示例（以调用 “qwen-plus” 模型为例）

python

运行

# 导入必要的库：os用于读取环境变量，OpenAI是兼容接口的核心库
import os
from openai import OpenAI
# 创建客户端对象：这里的配置是关键
client = OpenAI(
    # 从环境变量中读取API-Key，避免硬编码
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 百炼的OpenAI兼容接口地址，固定为这个格式
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)
# 发起API调用：向模型发送请求并获取响应
completion = client.chat.completions.create(
    # 模型名称，可根据需求更换，比如“deepseek-r1”“qwen-turbo”等
    model="qwen-plus",
    # 消息内容：role是角色（user表示用户输入），content是具体问题
    messages=[{"role": "user", "content": "你是谁？请简单介绍一下自己"}]
)
# 打印结果：从响应中提取模型的回答内容
print("模型回答：")
print(completion.choices[0].message.content)

关键说明

模型名称：百炼支持的模型都可以填在这里，比如轻量版 “qwen-turbo”、标准版 “qwen-plus”、DeepSeek 系列 “deepseek-r1” 等，具体可在百炼控制台的 “模型广场” 查看所有支持的模型名称。
消息格式：除了 “user” 角色，还可以加 “system” 角色设置系统提示（比如 “你是一个专业的程序员，回答时要简洁”），示例如下：python

运行

messages=[
    {"role": "system", "content": "你是一个专业的程序员，回答时要简洁，只用代码说明"},
    {"role": "user", "content": "用Python写一个计算1到100求和的代码"}
]

响应解析：completion.choices[0].message.content是固定的解析格式，因为 API 响应会包含多个可能的回答（choices 列表），通常取第一个（索引 0）即可。

3. 方式二：DashScope SDK（官方原生接口）

如果你是第一次接触 API 调用，或者需要使用百炼的专属功能（比如流式输出、模型微调结果调用），建议用官方的 DashScope SDK，它对百炼的功能支持更全面，且报错信息更详细，方便排查问题。

代码示例（同样调用 “qwen-plus” 模型）

python

运行

# 导入库：os读取环境变量，Generation是DashScope的核心调用类
import os
from dashscope import Generation
# 发起调用：原生SDK的调用格式
response = Generation.call(
    # 从环境变量读取API-Key，也可以直接写字符串（不推荐）
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 模型名称，和兼容接口一致
    model="qwen-plus",
    # 消息内容，格式和兼容接口相同
    messages=[{"role": "user", "content": "你是谁？请简单介绍一下自己"}],
    # 输出格式：设置为“message”，让响应格式更易读
    result_format="message"
)
# 处理响应：先判断调用是否成功，再提取结果
if response.status_code == 200:
    # 调用成功，打印模型回答
    print("模型回答：")
    print(response.output.choices[0].message.content)
else:
    # 调用失败，打印错误信息（方便排查问题）
    print("调用失败：")
    print(f"错误码：{response.status_code}")
    print(f"错误信息：{response.message}")

关键说明

状态码判断：response.status_code == 200是判断调用是否成功的关键，200 表示成功，其他码表示失败（比如 401 表示 API-Key 错误，403 表示权限不足，500 表示服务器错误）。
流式输出：如果需要模型 “边思考边输出”（比如生成长篇内容时避免等待太久），可以在Generation.call中加stream=True参数，示例如下：python

运行

# 流式调用示例
response = Generation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen-plus",
    messages=[{"role": "user", "content": "写一段100字的春天描写"}],
    result_format="message",
    stream=True  # 开启流式输出
)
# 逐段打印结果
print("模型回答（流式输出）：")
for chunk in response:
    if chunk.status_code == 200 and chunk.output.choices:
        print(chunk.output.choices[0].message.content, end="")

错误排查：如果调用失败，response.message会给出具体原因，比如 “API-Key 无效”“模型不存在”“免费额度已用完”，根据提示调整即可。

五、第四步：其他语言调用（Node.js、Java 示例）

除了 Python，百炼 API 也支持 Node.js、Java 等主流开发语言，核心逻辑和 Python 一致：读取 API-Key、设置接口地址、发送请求并处理响应。下面分别给出两种语言的简化示例，帮助不同技术栈的开发者快速上手。

1. Node.js 调用（使用 OpenAI 兼容接口）

Node.js 开发者可以用openai库（和 Python 的库同名，但属于 Node.js 版本），步骤如下：

第一步：安装依赖

打开终端，在项目目录下执行：

bash

运行

npm install openai

第二步：调用代码示例

javascript

运行

// 导入openai库
const { OpenAI } = require('openai');
// 创建客户端对象
const client = new OpenAI({
  // 读取环境变量中的API-Key（Node.js中用process.env读取）
  apiKey: process.env.DASHSCOPE_API_KEY,
  // 百炼的兼容接口地址
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
});
// 定义调用函数（因为Node.js推荐异步操作，用async/await）
async function callBailianAPI() {
  try {
    // 发起调用
    const completion = await client.chat.completions.create({
      model: 'qwen-plus',
      messages: [{ role: 'user', content: '用Node.js写一个Hello World程序' }]
    });
    // 打印结果
    console.log('模型回答：');
    console.log(completion.choices[0].message.content);
  } catch (error) {
    // 捕获错误并打印
    console.log('调用失败：');
    console.log(`错误信息：${error.message}`);
  }
}
// 执行函数
callBailianAPI();

运行方式

如果是 Windows 系统，在 CMD 中先配置临时环境变量：set DASHSCOPE_API_KEY=your-api-key，再执行node 文件名.js。
如果是 macOS/Linux，在终端中执行export DASHSCOPE_API_KEY=your-api-key && node 文件名.js。

2. Java 调用（使用官方 DashScope SDK）

Java 调用需要用阿里云官方提供的dashscope-sdk-java，适合企业级应用开发，步骤如下：

第一步：添加依赖（Maven 项目）

在pom.xml文件中添加以下依赖（版本需≥2.12.0，确保功能完整）：

xml

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>2.12.0</version>
</dependency>

第二步：调用代码示例

java

运行

import com.aliyun.dashscope.DashScope;
import com.aliyun.dashscope.exception.ApiException;
import com.aliyun.dashscope.exception.InputRequiredException;
import com.aliyun.dashscope.exception.NoApiKeyException;
import com.aliyun.dashscope.generation.Generation;
import com.aliyun.dashscope.generation.GenerationParam;
import com.aliyun.dashscope.generation.GenerationResult;
public class BailianApiDemo {
    public static void main(String[] args) {
        // 1. 设置API-Key：从环境变量读取（Java中用System.getenv读取）
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        DashScope.baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1");
        DashScope.apiKey(apiKey);
        try {
            // 2. 构建请求参数
            GenerationParam param = GenerationParam.builder()
                    .model("qwen-plus") // 模型名称
                    .messages(GenerationParam.Message.builder()
                            .role("user")
                            .content("用Java写一个计算1到100求和的方法")
                            .build())
                    .resultFormat(GenerationParam.ResultFormat.MESSAGE) // 输出格式
                    .build();
            // 3. 发起调用
            GenerationResult result = Generation.call(param);
            // 4. 处理结果
            if (result.getStatus() == GenerationResult.Status.SUCCESS) {
                System.out.println("模型回答：");
                System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent());
            } else {
                System.out.println("调用失败：");
                System.out.println("错误信息：" + result.getMessage());
            }
        } catch (NoApiKeyException e) {
            System.out.println("错误：未找到API-Key，请检查环境变量配置");
        } catch (InputRequiredException e) {
            System.out.println("错误：请求参数缺失，比如模型名称或消息内容");
        } catch (ApiException e) {
            System.out.println("错误：API调用失败，错误码：" + e.getCode());
            System.out.println("错误信息：" + e.getMessage());
        }
    }
}

运行方式

配置环境变量：Windows 系统在 IDE 中设置环境变量（比如 IntelliJ IDEA 中，Run→Edit Configurations→Environment Variables），macOS/Linux 在终端中执行export DASHSCOPE_API_KEY=your-api-key后再运行 IDE。
直接运行：通过 IDE 的 “Run” 按钮执行，或用 Maven 命令mvn compile exec:java -Dexec.mainClass="BailianApiDemo"运行。

六、常见问题排查：避免踩坑的关键细节

在实际操作中，很多开发者会遇到 “调用失败” 的情况，这里整理几个高频问题及解决方案，帮大家快速定位问题：

1. API-Key 相关错误

症状：调用时提示 “401 Unauthorized”“API-Key 无效”。
原因：可能是 API-Key 复制错误（比如多了空格、少了字符），或者密钥已被删除 / 过期，也可能是环境变量配置错误导致代码读取不到。
解决方案：重新检查 API-Key 是否正确，在终端中验证环境变量是否能正常输出；如果确认密钥正确，登录百炼控制台的 “密钥管理”，检查该密钥是否处于 “正常” 状态，若已删除则重新创建。

2. 模型名称错误

症状：提示 “400 Bad Request”“模型不存在”。
原因：模型名称拼写错误（比如把 “qwen-plus” 写成 “qwenplus”），或者该模型不在你的权限范围内（比如某些付费模型需要单独开通）。
解决方案：在百炼控制台的 “模型广场” 中找到目标模型，复制官方给出的模型名称（确保完全一致）；如果是权限问题，查看模型详情页的 “权限说明”，按提示开通权限。

3. 环境变量读取不到

症状：代码报错 “api_key is None”“环境变量 DASHSCOPE_API_KEY 未定义”。
原因：环境变量配置后没有重启终端 / IDE，或者配置命令有误（比如 Windows 用了 PowerShell 的命令却在 CMD 中运行）。
解决方案：配置环境变量后，关闭所有终端和 IDE，重新打开；如果是 Windows 系统，区分 PowerShell 和 CMD 的配置方式，不要混用。

4. 免费额度用完

症状：提示 “403 Forbidden”“调用量超过免费额度”。
原因：百炼的免费额度有上限（比如 100 万 Tokens），超过后需要充值才能继续调用。
解决方案：登录百炼控制台，在 “费用中心” 查看剩余额度；如果额度已用完，按提示充值，或等待下个月的额度重置（具体以平台规则为准）。

七、总结：调用流程回顾与后续建议

整个阿里云百炼 API 调用的核心流程可以总结为 3 步：“获取 API-Key→配置环境变量→编写代码调用”，看似步骤多，但只要按顺序操作，每个环节都验证通过，就能顺利完成调用。

对于后续学习，有两个建议：一是多测试不同的模型，比如用 “deepseek-r1” 测试逻辑推理能力，用 “qwen-vl-plus” 测试图文理解能力，熟悉不同模型的特性；二是尝试使用百炼的进阶功能，比如流式输出、自定义系统提示、结合 RAG（检索增强生成）能力，这些功能能让 API 调用更贴合实际业务需求。

最后需要提醒，所有 API 调用都要注意用量控制，避免因代码循环调用、测试时忘记限制次数导致超额计费。如果是企业级应用，建议在代码中加入用量监控逻辑，实时查看调用量，确保成本可控。

阿里云百炼 API 调用教程：准备 API-Key、配置环境变量和调用 API 流程

一、先搞懂基础：为什么需要 API-Key 和环境变量？

二、第一步：账号准备与 API-Key 获取

1. 注册并登录阿里云主账号

2. 开通百炼服务

3. 创建并获取 API-Key

三、第二步：配置 API-Key 到环境变量（分系统操作）

1. macOS/Linux 系统配置（两种生效方式）

方式一：永久生效（推荐，一次配置长期可用）

方式二：临时生效（适合短期测试，关闭终端后失效）

验证配置是否成功

2. Windows 系统配置（分 PowerShell 和 CMD）

方式一：PowerShell 永久配置（推荐）

方式二：CMD 临时配置（适合短期测试）

验证配置是否成功

四、第三步：调用 API（以 Python 为例，附两种核心方式）

1. 前置准备：安装依赖库

2. 方式一：OpenAI 兼容接口

代码示例（以调用 “qwen-plus” 模型为例）

关键说明

3. 方式二：DashScope SDK（官方原生接口）

代码示例（同样调用 “qwen-plus” 模型）

关键说明

五、第四步：其他语言调用（Node.js、Java 示例）

1. Node.js 调用（使用 OpenAI 兼容接口）

第一步：安装依赖

第二步：调用代码示例

运行方式

2. Java 调用（使用官方 DashScope SDK）

第一步：添加依赖（Maven 项目）

第二步：调用代码示例

运行方式

六、常见问题排查：避免踩坑的关键细节

1. API-Key 相关错误

2. 模型名称错误

3. 环境变量读取不到

4. 免费额度用完

七、总结：调用流程回顾与后续建议

阿里云百炼

热门文章

最新文章

相关电子书