阿里云百炼支持通过 API 调用大模型，涵盖 OpenAI 兼容接口、DashScope SDK 等接入方式。本文以千问为例，引导您完成大模型 API 的首次调用，您将了解到：如何获取 API Key、如何配置本地开发环境、如何调用千问 API。无论您熟悉 Python、Node.js、Java，还是习惯使用 curl 或其他语言，都能在下文中找到对应的完整示例。
一、账号设置：注册、开通与获取凭证
在正式调用千问 API 之前，需要完成四项账号准备工作。
第一步，注册账号。 若您还没有阿里云账号，需首先注册阿里云账号，这是使用百炼平台的前提。
第二步，开通阿里云百炼。 使用阿里云主账号前往阿里云百炼大模型服务平台，阅读并同意协议后，将自动开通阿里云百炼；如果未弹出服务协议，则表示您已经开通。需要提醒的是，如果开通服务时提示"您尚未进行实名认证"，请先完成实名认证后再继续操作。阿里云百炼官方平台：https://www.aliyun.com/product/bailian
第三步，获取 API Key。 前往 API Key 页面，单击"创建 API Key"，即可通过 API Key 调用大模型。创建 API Key 时无需选择模型，调用时通过请求体中的 model 参数指定要调用的模型（例如 model="qwen-plus"），可用模型可参见模型列表。如需限制该 API Key 可调用的模型范围，创建时选择"自定义"权限，并开启"访问模型范围"开关，开启后该 API Key 仅能调用已选择的模型，安全性更高。
第四步，获取业务空间 ID。 使用华北2（北京）、新加坡、日本（东京）或德国（法兰克福）地域的模型时，需在 Base URL 中填入业务空间 ID（WorkspaceId），该 ID 可在业务空间管理页面中查看。
二、配置 API Key 到环境变量
建议您把 API Key 配置到环境变量，避免在代码里显式地配置 API Key，从而降低泄露风险。以下分别介绍 Linux、macOS、Windows 三大系统的配置方法。
Linux 系统
添加永久性环境变量：如果您希望环境变量在当前用户的所有新会话中生效，可执行以下命令将配置追加到 ~/.bashrc 文件中：
# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc
也可以执行 nano ~/.bashrc 手动打开文件，在配置文件中添加 export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"，然后在 nano 编辑器中按 Ctrl + X，接着按 Y，再按 Enter 保存并关闭。随后执行 source ~/.bashrc 使变更生效，并重新打开一个终端窗口运行 echo $DASHSCOPE_API_KEY 检查环境变量是否生效。
添加临时性环境变量：如果仅希望在当前会话中使用，可直接执行 export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"，再运行 echo $DASHSCOPE_API_KEY 验证即可。
macOS 系统
首先在终端中执行 echo $SHELL 查看默认 Shell 类型，再分别操作：
- Zsh：执行
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.zshrc追加配置（也可用nano ~/.zshrc手动修改），然后执行source ~/.zshrc使变更生效，重新打开终端窗口运行echo $DASHSCOPE_API_KEY检查。 - Bash：执行
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bash_profile追加配置（也可用nano ~/.bash_profile手动修改），然后执行source ~/.bash_profile生效，并重新打开终端验证。
临时性环境变量（Zsh 和 Bash 通用）：执行 export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY" 后，用 echo $DASHSCOPE_API_KEY 验证。
Windows 系统
Windows 下可通过系统属性、CMD 或 PowerShell 三种方式配置。
系统属性方式（永久生效，需管理员权限）：按 Win+Q 搜索"编辑系统环境变量"，打开系统属性界面；单击"环境变量"，在"系统变量"区域下单击"新建"，变量名填入 DASHSCOPE_API_KEY，变量值填入您的 DashScope API Key；依次单击确定关闭页面。需要注意的是，配置后不会立即影响已打开的命令窗口、IDE 或正在运行的应用程序，需重新启动这些程序或打开新的命令行才能生效。验证时，CMD 中使用 echo %DASHSCOPE_API_KEY%，PowerShell 中使用 echo $env:DASHSCOPE_API_KEY。
CMD 方式：永久性配置运行 setx DASHSCOPE_API_KEY "YOUR_DASHSCOPE_API_KEY"，然后打开新的 CMD 窗口运行 echo %DASHSCOPE_API_KEY% 检查；临时性配置运行 set DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY，在当前会话用 echo %DASHSCOPE_API_KEY% 检查。
PowerShell 方式：永久性配置运行 [Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "YOUR_DASHSCOPE_API_KEY", [EnvironmentVariableTarget]::User)，打开新窗口后用 echo $env:DASHSCOPE_API_KEY 检查；临时性配置运行 $env:DASHSCOPE_API_KEY = "YOUR_DASHSCOPE_API_KEY"，在当前会话验证。
三、选择开发语言：配置环境并调用千问 API
Python 方式
步骤 1：配置 Python 环境。 您的 Python 需要为 3.8 或以上版本。在终端中输入 python -V 和 pip --version 查看是否已安装 Python 和 pip。如果执行后报错（如 'python' 不是内部或外部命令 或 -bash: python: command not found），Windows 系统需确认已安装 Python 并将 python.exe 添加至环境变量 PATH（安装向导中勾选"Add python.exe to PATH"后单击 Install Now），若已配置仍报错则关闭终端重新打开；Linux、macOS 系统需确认已安装 Python，可用 which python pip 或 which python3 pip3 查询，若系统中仅有 python3，则使用 python3 -V、pip3 --version 查询版本。
配置虚拟环境（可选）：为避免与其他项目发生依赖冲突，可运行 python -m venv .venv 创建虚拟环境；Windows 下运行 .venv\Scripts\activate 激活，macOS 或 Linux 下运行 source .venv/bin/activate 激活。
安装 SDK：您可以通过 OpenAI 或 DashScope 的 Python SDK 调用百炼平台上的模型。安装 OpenAI Python SDK 运行 pip install -U openai，终端出现 Successfully installed ... openai-x.x.x 即表示成功；安装 DashScope Python SDK 运行 pip install -U dashscope，出现相应成功提示即可（若运行失败可将 pip 替换成 pip3）。
步骤 2：调用大模型 API。 使用 OpenAI Python SDK 时，新建 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",
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}")
需要特别注意的是，示例代码中的 import os 用于读取环境变量，请勿省略；如果您使用 .env 文件管理 API Key，需同时导入 os 和 dotenv 并执行 load_dotenv()，缺少 import os 会导致 NameError，请勿将其误判为 .env 文件加载失败。通过命令行运行 python hello_qwen.py 或 python3 hello_qwen.py，运行后您将看到输出结果："我是阿里云开发的一款超大规模语言模型，我叫千问。"
使用 DashScope Python SDK 时，同样新建 hello_qwen.py，通过 from dashscope import MultiModalConversation 导入，设置 dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'，调用 MultiModalConversation.call() 时传入 api_key=os.getenv("DASHSCOPE_API_KEY")、model="qwen3.8-max" 及 messages 参数；若 response.status_code == 200 则打印 response.output.choices[0].message.content[0]["text"]，否则打印错误码与错误信息并参考官方错误码文档。运行成功后输出："我是来自阿里云的大规模语言模型，我叫千问。"
Node.js 方式
步骤 1：配置 Node.js 环境。 在终端中输入 node -v 和 npm -v 检查安装状态，若未安装可访问 Node.js 官网下载。随后运行 npm install --save openai 或 yarn add openai 安装 SDK；如果安装失败，可通过 npm config set registry https://registry.npmmirror.com/ 配置镜像源后重新安装。终端出现 added xx package in xxs 即表示安装成功，可用 npm list openai 查询版本。
步骤 2：调用大模型 API。 新建 hello_qwen.mjs 文件，通过 import OpenAI from "openai" 导入，创建客户端时传入 apiKey: process.env.DASHSCOPE_API_KEY 和 baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"，再调用 openai.chat.completions.create()，指定 model: "qwen3.8-max" 及 system、user 两条消息，最后 console.log(completion.choices[0].message.content)。在文件所在目录运行 node hello_qwen.mjs 即可（请确保 SDK 已安装在该目录下，否则会报错 Cannot find package 'openai' imported from xxx）。运行成功后输出："我是来自阿里云的语言模型，我叫通义千问。"
Java 方式
步骤 1：配置 Java 环境。 在终端运行 java -version 检查版本（使用 DashScope Java SDK 需要 Java 8 或以上），如使用 Maven 管理项目还需运行 mvn --version 确认 Maven 已安装。若没有 Java 或版本过低，请前往 Oracle 官网下载安装。
安装 SDK：Maven 项目打开 pom.xml，在 <dependencies> 标签内添加依赖：groupId 为 com.alibaba，artifactId 为 dashscope-sdk-java，并将 the-latest-version 替换为最新版本号，保存后执行 mvn compile 或 mvn clean install 更新依赖。Gradle 项目则在 build.gradle 的 dependencies 块中添加 implementation group: 'com.alibaba', name: 'dashscope-sdk-java', version: 'the-latest-version'，保存后在项目根目录执行 ./gradlew build --refresh-dependencies。
步骤 2：调用大模型 API。 编写 Main 类，通过静态代码块设置 Constants.baseHttpApiUrl="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"，使用 MultiModalConversation 构建 system 与 user 消息，在 MultiModalConversationParam 中通过 .apiKey(System.getenv("DASHSCOPE_API_KEY")) 传入密钥、.model("qwen3.8-max") 指定模型，调用后打印返回内容中的 text 字段。运行后输出："我是阿里云开发的一款超大规模语言模型，我叫千问。"
curl 方式
您可以通过 OpenAI 兼容的 HTTP 方式或 DashScope 的 HTTP 方式调用模型。若没有配置环境变量，需将 -H "Authorization: Bearer $DASHSCOPE_API_KEY" 替换为 -H "Authorization: Bearer sk-xxx"。
OpenAI 兼容-HTTP：Linux/macOS 下执行 curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions，携带 Authorization 与 Content-Type 请求头，请求体中指定 model 为 qwen3.8-max 及 messages 数组；Windows 下语法类似，使用 ^ 换行并以 %DASHSCOPE_API_KEY% 引用变量。发送请求后可获得包含 choices、usage（prompt_tokens、completion_tokens、total_tokens）等字段的 JSON 回复，content 为"我是来自阿里云的大规模语言模型，我叫千问。"
DashScope-HTTP：请求地址为 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation，请求体中除 model 外，messages 置于 input 字段下，并添加 "parameters": {"result_format": "message"}。返回结果包含 output.choices 与 usage 信息。
其它语言（Go、PHP、C#）
对于 Go、PHP、C# 等语言，同样可通过 OpenAI 兼容的 HTTP 接口调用。核心思路一致：构建包含 model（qwen3.8-max）和 messages 的 JSON 请求体，向 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions 发送 POST 请求，并在请求头中设置 Authorization: Bearer 加 API Key（通过 os.Getenv("DASHSCOPE_API_KEY")、getenv('DASHSCOPE_API_KEY')、Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY") 等方式读取环境变量），最后读取并输出响应内容。若未配置环境变量，可直接将密钥以 sk-xxx 形式写入代码。
四、常见问题
1. 免费额度用完后如何购买 Token？
您可以访问费用与成本中心，确保您的账户没有欠费即可调用千问模型。调用千问模型会自动扣费，出账周期为分钟级（即一条账单代表一分钟内的费用），消费明细可前往账单详情查看。
2. 调用大模型 API 后报错 Model.AccessDenied，如何处理？
该报错是因为您使用了子业务空间的 API Key，而子业务空间无法访问主账号空间的应用或模型。使用子空间 API Key 需由主账号管理员为对应子空间开通模型授权（如本文使用的 qwen3.8-max 模型），授权后即可正常调用。
五、下一步：更多探索方向
完成首次调用后，您可以继续深入探索：一是查看更多模型，示例代码以 qwen3.8-max 为例，百炼还支持其他千问模型与 DeepSeek、Llama 等第三方模型；二是了解进阶用法，如流式输出、结构化输出、Function Calling 等；三是在线体验大模型，通过对话框与大模型互动（需注意千问官网将千问 API 与联网搜索、网页解析等工具进行了集成，与直接调用千问 API 效果略有差异；图像生成模型仅支持单轮对话，如需在原图基础上修改，需将图片保存到本地后重新上传并输入新的编辑指令）；四是0 代码进行大模型微调，阿里云百炼提供了 0 代码微调功能，您仅需提供数据集即可；五是调用自训练模型，如果您在百炼平台部署了自训练模型，调用时需使用模型部署页面生成的模型 code 作为 model 参数，而非模型 ID，否则将报错 Model not exist。
六、阿里云百炼平台AI选型与定价
通过阿里云百炼调用千问大模型的推理服务价格，主要包括Token Plan个人版、节省计划、组合购、资源包等，具体如下：
1、Token Plan个人版
1. Lite版本
- 价格：¥39.00/1个月
- 官网折扣价：¥39.00/1个月
- 套餐类型：基础套餐
- 购买时长：包月
2. Standard版本
- 价格：¥139.00/1个月
- 官网折扣价：¥139.00/1个月
- 套餐类型：标准套餐
- 购买时长：包月
3. Pro版本
- 价格：¥499.00/1个月
- 官网折扣价：¥499.00/1个月
- 套餐类型：高级套餐
- 购买时长：包月
更多Token Plan收费标准可参考：https://www.aliyun.com/benefit/scene/tokenplan
2、节省计划
1. 大语言模型推理旗舰模型
- 描述：覆盖千问LLM、VL模型以及阿里云百炼上架的三方文…
- 价格：¥20.00/1月
- 官网折扣价：¥20.00/1月
- 承诺消费金额：20元
- 有效期：1个月
2. 千问-大语言模型推理通用抵…
- 描述：覆盖千问LLM、VL模型以及阿里云百炼上架的三方文…
- 价格：¥100.00/3月
- 官网折扣价：¥100.00/3月
- 承诺消费金额：100元
- 有效期：3个月
3. 万相-视觉生成旗舰模型
- 描述：根据承诺消费金额阶梯折扣，最低9折，可抵扣wan系…
- 价格：¥20.00/3月
- 官网折扣价：¥20.00/3月
- 承诺消费金额：20元
- 有效期：3个月
更多节省计划详情可参考：https://help.aliyun.com/zh/model-studio/savings-plan-and-resource-package
3、组合购
1. AI 编程全能包 · 入门版
- 描述：轻松上手，个人开发与日常高频编码首选，TP_Lite 套餐含 2,500 Credits / 7天
- 标签：适合独立开发者入门体验；TP_Lite 套餐：2,500 Credits / 7天
- 合计：¥98.00
- 官网折扣价：¥98.00
- 包含内容：
- Token Plan 个人版｜套餐类型：Lite套餐｜购买时长：包月｜¥39.00
- Qoder CN 个人版订阅｜订阅计划：个人专业版 Pro｜购买时长：1个月｜¥59.00
2. AI 编程全能包 · 专业版
- 描述：高频重度开发，模型与编程双档升级，TP_Standard 套餐含 10,000 Credits / 7天
- 标签：适合专业开发者高频生产；TP_Standard 套餐：10,000 Credits / 7天
- 合计：¥308.00
- 官网折扣价：¥308.00
- 包含内容：
- Token Plan 个人版｜套餐类型：Standard套餐｜购买时长：包月｜¥139.00
- Qoder CN 个人版订阅｜订阅计划：个人高级版 Pro+｜购买时长：1个月｜¥169.00
更多组合购套餐及价格可通过专属活动查询：https://www.aliyun.com/benefit/client/package
4、资源包
1. 千问-Qwen-Image图像生成…
- 描述：可抵扣qwen-image、qwen-image-edit模型生图推理…
- 价格：¥20.00/3月
- 官网折扣价：¥20.00/3月
- 资源包容量：80张
- 有效期：3个月
2. 千问-Qwen-Plus模型推理资…
- 描述：可抵扣1200万qwen-plus稳定版以及latest版本的toke…
- 价格：¥11.66/3月
- 官网折扣价：¥11.66/3月
- 资源包容量：12000千tokens
- 有效期：3个月
3. 千问-Qwen-Max模型推理资…
- 描述：可抵扣1800万qwen-max稳定版以及latest版推理toke…
- 价格：¥57.60/1年
- 官网折扣价：¥57.60/1年
- 资源包容量：18000千tokens
- 有效期：1年
通过以上步骤，从账号开通、API Key 获取、环境变量配置，到多语言环境搭建与首次调用，您就已经完整走通了阿里云百炼调用千问 API 的全流程。接下来，不妨尝试切换不同模型、探索进阶能力，让大模型真正融入您的业务与开发工作流。
