阿里云百炼 API 怎么用？2026年阿里云百炼 API 调用教程：从密钥准备到多语言实现-阿里云开发者社区

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

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

图片.png

一、基础概念：API-Key 与环境变量的作用

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

（一）API-Key：访问的 “身份凭证”

API-Key 相当于访问阿里云百炼 API 的 “钥匙”。由于百炼 API 调用有免费额度限制（超额度后计费），且需区分用户权限，每个开发者都需要专属 API-Key。调用时，平台通过密钥识别身份，判断是否有权使用模型、计算调用用量，没有 API-Key 无法发起有效请求。

（二）环境变量：安全管理密钥的方式

很多新手会直接把 API-Key 写在代码里，这存在两大问题：一是代码分享或上传到 GitHub 时，密钥易泄露，可能被他人滥用产生高额费用；二是更换密钥时需逐行修改代码，十分麻烦。配置到环境变量，相当于把密钥存到操作系统的 “安全仓库”，代码仅从仓库读取，既避免泄露，又方便统一管理。

此外，百炼 API 支持北京、新加坡等多个地域，不同地域接口地址略有差异，但核心流程一致，本文以北京地域为例，其他地域只需后续调用时确认对应接口域名即可。

二、第一步：获取 API-Key（账号准备到密钥创建）

获取 API-Key 需先完成账号注册和百炼服务开通，具体分 3 步：

（一）注册并登录阿里云账号

已有阿里云账号（用过 ECS、RDS 等产品）可直接登录；新用户需打开阿里云官网，通过手机号或邮箱注册，设置登录密码后完成登录。首次登录可能提示实名认证（个人填身份证信息，企业填营业执照信息），百炼免费额度使用通常不强制实名认证，可后续补充。

（二）开通百炼服务

登录后，打开阿里云百炼官方控制台（搜索 “阿里云百炼控制台” 或通过官方链接进入），选择地域（国内业务优先选北京，海外业务可选新加坡）。进入控制台后，点击 “免费体验”（免费指获取一定免费调用额度，超额度后按实际用量计费），阅读并同意服务协议，点击 “确认开通”，10 秒左右即可完成，页面自动跳转到百炼主控制台。

（三）创建并保存 API-Key

在百炼控制台左侧菜单栏找到 “密钥管理”，进入后选择 “API-Key” 页签（仅主账号或有 “API-Key 管理权限” 的子账号可操作）。
点击 “创建 API-KEY” 按钮，系统会立即生成一对类似 “sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx” 的字符串，这就是你的 API-Key。
关键步骤：生成后立即复制保存到本地记事本，页面刷新后无法再次查看完整密钥，忘记保存需删除旧密钥重新创建。一个账号可创建多个 API-Key（如不同项目用不同密钥），若担心泄露，可在 “密钥管理” 页面随时删除旧密钥、创建新密钥（删除后旧密钥立即失效）。

阿里云服务器ECS https://www.aliyun.com/product/ecs 打开如下图：

阿里云轻量服务器：https://www.aliyun.com/product/swas 打开如下图：

阿里云GPU云服务器 https://www.aliyun.com/product/egs 打开如下图：

用户可登录阿里云权益中心（https://www.aliyun.com/benefit），领取上云礼包、算力补贴优惠券或满减券，降低初次购买成本，但需注意优惠券使用期限与适用产品范围。

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

环境变量配置需根据操作系统区分，核心是 “将 API-Key 存入系统变量，让代码能读取到”，以下分系统说明操作步骤和验证方法：

（一）macOS/Linux 系统（两种生效方式）

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

1. 永久生效（推荐，一次配置长期可用）

原理是将环境变量写入 Shell 配置文件，每次打开终端自动加载：

Zsh（macOS 默认）：打开终端，执行命令（替换 “your-api-key” 为实际密钥）：bash

运行

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

该命令将密钥配置追加到~/.zshrc文件，同时立即加载让配置生效。
Bash（Linux 常见）：执行命令：bash

运行

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

注意用~/.bash_profile文件，与 Zsh 配置文件不能混用，否则不生效。

2. 临时生效（适合短期测试）

若仅临时测试，无需永久配置，终端直接执行：

bash

运行

export DASHSCOPE_API_KEY="your-api-key"

当前终端窗口可读取变量，关闭后配置消失，下次需重新执行。

3. 验证配置

执行命令echo $DASHSCOPE_API_KEY，若输出完整 API-Key，说明配置成功；若输出空值或错误，需检查命令是否正确（如配置文件路径、密钥是否输对）。

（二）Windows 系统（分 PowerShell 和 CMD）

Windows 有 PowerShell（推荐，功能全）和 CMD（传统命令行）两种工具，配置方式不同：

1. PowerShell 永久配置（推荐）

需修改 PowerShell 的profile文件：

按 Win+R，输入 “powershell” 打开 PowerShell，执行$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” 表示仅当前用户生效，想让所有用户可用，可替换为 “Machine”（需管理员权限）。
保存关闭记事本，重启 PowerShell 让配置生效。

2. CMD 临时配置

按 Win+R，输入 “cmd” 打开 CMD，执行：

cmd

set DASHSCOPE_API_KEY=your-api-key

注意 “=” 前后不能有空格，否则空格会被当作密钥一部分。配置仅当前 CMD 窗口生效，关闭后消失。

3. 验证配置

PowerShell：重启后执行[Environment]::GetEnvironmentVariable("DASHSCOPE_API_KEY", "User")，输出完整密钥即成功。
CMD：执行echo %DASHSCOPE_API_KEY%，输出完整密钥即成功。

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

完成密钥和环境变量配置后，即可调用 API。Python 是常用开发语言，SDK 支持完善、代码简洁，以下介绍两种主流调用方式：

（一）前置准备：安装依赖库

打开终端（或 CMD/PowerShell），执行命令安装所需库：

bash

运行

pip install -U openai dashscope

“openai” 库用于支持 OpenAI 兼容接口（即使不用 OpenAI 服务，也需安装才能用兼容格式调用百炼 API）。
“dashscope” 库是阿里云官方 SDK，支持百炼原生 API。
“-U” 参数表示升级到最新版本，避免旧版本 bug 导致调用失败。若提示 “pip 不是内部或外部命令”，需检查 Python 环境变量配置，或用 “python -m pip install ...” 指定 Python 路径。

（二）方式一：OpenAI 兼容接口（适合熟悉 OpenAI 的开发者）

百炼提供 OpenAI 兼容接口格式，原有 OpenAI 代码几乎不用修改，只需更换 API-Key 和接口地址，即可调用百炼模型（如通义千问、DeepSeek）。

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

python

运行

# 导入库：os读取环境变量，OpenAI是兼容接口核心库
import os
from openai import OpenAI
# 创建客户端对象：关键配置
client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 从环境变量读取密钥
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"  # 百炼兼容接口地址
)
# 发起调用：发送请求并获取响应
completion = client.chat.completions.create(
    model="qwen-plus",  # 模型名称，可换“deepseek-r1”“qwen-turbo”等
    messages=[{"role": "user", "content": "你是谁？请简单介绍一下自己"}]  # 消息内容
)
# 打印结果：提取模型回答
print("模型回答：")
print(completion.choices[0].message.content)

关键说明

模型名称：可在百炼控制台 “模型广场” 查看所有支持的模型名称（如轻量版 “qwen-turbo”、标准版 “qwen-plus”）。
消息格式：除 “user” 角色（用户输入），还可加 “system” 角色设置系统提示，示例：python

运行

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

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

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

若首次接触 API 调用，或需使用百炼专属功能（如流式输出、模型微调结果调用），建议用官方 SDK，功能更全面、报错信息更详细，方便排查问题。

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

python

运行

# 导入库：os读取环境变量，Generation是DashScope核心调用类
import os
from dashscope import Generation
# 发起调用：原生SDK格式
response = Generation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 从环境变量读取密钥
    model="qwen-plus",  # 模型名称，与兼容接口一致
    messages=[{"role": "user", "content": "你是谁？请简单介绍一下自己"}],
    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表示调用成功，其他码表示失败（401=API-Key 错误，403 = 权限不足，500 = 服务器错误）。
流式输出：若需模型 “边思考边输出”（如生成长篇内容），可加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 等主流语言，核心逻辑都是 “读取 API-Key→设置接口地址→发送请求→处理响应”，以下给出简化示例：

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

1. 安装依赖

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

bash

运行

npm install openai

2. 代码示例

javascript

运行

// 导入openai库
const { OpenAI } = require('openai');
// 创建客户端对象
const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,  // Node.js中用process.env读取环境变量
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1'  // 百炼兼容接口地址
});
// 定义异步调用函数（Node.js推荐异步操作）
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();

3. 运行方式

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

（二）Java 调用（DashScope SDK）

适合企业级应用开发，需用阿里云官方dashscope-sdk-java：

1. 添加依赖（Maven 项目）

在pom.xml中添加依赖（版本≥2.12.0）：

xml

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

2. 代码示例

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
        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());
        }
    }
}

3. 运行方式

Windows：IDE（如 IntelliJ IDEA）中设置环境变量（Run→Edit Configurations→Environment Variables），再点击 “Run”。
macOS/Linux：终端执行export DASHSCOPE_API_KEY=your-api-key后，用 Maven 命令mvn compile exec:java -Dexec.mainClass="BailianApiDemo"运行。

五、常见问题排查

实际操作中，调用失败多因细节疏忽，以下是高频问题及解决方案：

（一）API-Key 相关错误（401 Unauthorized）

症状：提示 “API-Key 无效”。
原因：密钥复制错误（多空格、少字符）、密钥已删除 / 过期，或环境变量配置错误导致代码读取不到。
解决方案：终端验证环境变量是否正常输出；登录百炼 “密钥管理”，检查密钥是否 “正常”，若已删除则重新创建。

（二）模型名称错误（400 Bad Request）

症状：提示 “模型不存在”。
原因：模型名称拼写错误（如 “qwen-plus” 写成 “qwenplus”），或模型不在权限范围内（部分付费模型需单独开通）。
解决方案：在百炼 “模型广场” 复制官方模型名称；查看模型详情页 “权限说明”，按提示开通权限。

（三）环境变量读取不到（api_key is None）

症状：代码报错 “环境变量未定义”。
原因：配置后未重启终端 / IDE，或配置命令有误（如 Windows 用 PowerShell 命令却在 CMD 运行）。
解决方案：关闭所有终端和 IDE 重新打开；区分 Windows 不同命令行工具的配置方式，不混用。

（四）免费额度用完（403 Forbidden）

症状：提示 “调用量超过免费额度”。
原因：百炼免费额度有上限（如 100 万 Tokens），超额度后需充值。
解决方案：登录百炼 “费用中心” 查看剩余额度；额度用完可按提示充值，或等待下个月额度重置（以平台规则为准）。

六、总结与后续建议

百炼 API 调用核心流程可总结为 “获取 API-Key→配置环境变量→编写代码调用”，看似步骤多，只要逐步验证，就能顺利完成。后续学习可尝试两点：一是测试不同模型（如用 “deepseek-r1” 测逻辑推理，用 “qwen-vl-plus” 测图文理解），熟悉模型特性；二是探索进阶功能（流式输出、自定义系统提示、结合 RAG 检索增强），让 API 调用更贴合业务需求。

最后提醒，调用时需注意用量控制，避免代码循环调用或测试时忘记限制次数导致超额计费。企业级应用建议在代码中加入用量监控逻辑，实时查看调用量，确保成本可控。更多关于阿里云百炼AI大模型平台的使用教程，请参考官方文档：https://help.aliyun.com/zh/model-studio/what-is-model-studio 图片.png

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

阿里云百炼 API 怎么用？2026年阿里云百炼 API 调用教程：从密钥准备到多语言实现

一、基础概念：API-Key 与环境变量的作用

（一）API-Key：访问的 “身份凭证”

（二）环境变量：安全管理密钥的方式

二、第一步：获取 API-Key（账号准备到密钥创建）

（一）注册并登录阿里云账号

（二）开通百炼服务

（三）创建并保存 API-Key

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

（一）macOS/Linux 系统（两种生效方式）

1. 永久生效（推荐，一次配置长期可用）

2. 临时生效（适合短期测试）

3. 验证配置

（二）Windows 系统（分 PowerShell 和 CMD）

1. PowerShell 永久配置（推荐）

2. CMD 临时配置

3. 验证配置

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

（一）前置准备：安装依赖库

（二）方式一：OpenAI 兼容接口（适合熟悉 OpenAI 的开发者）

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

关键说明

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

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

关键说明

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

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

1. 安装依赖

2. 代码示例

3. 运行方式

（二）Java 调用（DashScope SDK）

1. 添加依赖（Maven 项目）

2. 代码示例

3. 运行方式

五、常见问题排查

（一）API-Key 相关错误（401 Unauthorized）

（二）模型名称错误（400 Bad Request）

（三）环境变量读取不到（api_key is None）

（四）免费额度用完（403 Forbidden）

六、总结与后续建议

热门文章

最新文章

相关电子书