阿里云大模型服务平台百炼汇集多款主流大模型，覆盖文本对话、多模态识图、文生视频、Agent智能体、知识库RAG等丰富能力。新开通服务的账号会自动发放超7000万免费Tokens额度，每款标准模型分配100万免费Token，非常适合开发者做原型验证、学习调试业务逻辑。想要通过程序、第三方AI工具调用平台各类大模型能力，API‑Key是核心身份凭证，每一次接口请求都依靠该密钥完成身份鉴权，确定调用账号、可用模型以及计费抵扣规则。详情👉访问阿里云百炼大模型服务平台页面 了解。
很多刚接触大模型接口开发的新手，常常卡在API‑Key创建、环境变量配置环节，会遇到无法创建密钥、环境变量不生效、鉴权401报错、密钥权限不足、RAM子账号调用失败等各类问题。同时密钥安全也是不可忽视的重点，一旦密钥泄露，其他人可以冒用身份调用接口产生大量消耗。本文完整讲解百炼API‑Key的控制台创建流程、归属业务空间概念、不同操作系统环境变量配置、第三方工具接入方式，提供curl、Python完整可运行代码示例，同时梳理权限管理规则、配额限制、高频故障排查，帮助开发者安全、快速完成大模型接口接入。
一、API‑Key完整创建流程
在创建密钥之前，账号需要完成实名认证，并且开通百炼平台服务。如果是团队使用，需要区分主账号和RAM子账号：主账号拥有全部权限，可以创建业务空间与密钥；RAM子账号需要管理员提前分配业务空间管理员权限，否则无法生成API‑Key。详情👉访问阿里云百炼大模型服务平台页面 了解。
完整创建步骤：
- 登录百炼控制台，进入平台主界面，点击右上角控制台入口，跳转到大模型服务平台。
- 在控制台常用功能栏目，找到【API Key】功能入口，进入密钥管理页面。
- 点击页面右上角【创建API Key】，弹出配置弹窗，需要填写三项核心配置：归属账号、归属业务空间、访问权限。
归属账号：个人开发者直接选择主账号，账号一般为一串数字ID。企业团队如果需要给应用、团队成员做权限隔离，选择RAM用户，使用RAM子账号生成独立密钥，实现权责分离，避免直接暴露主账号密钥。
归属业务空间：选择“默认业务空间”，该业务空间下生成的密钥，可以调用平台全部标准公开模型。企业多项目场景，可以新建多个子业务空间，不同业务空间做模型调用授权隔离，子业务空间内的密钥，仅能调用该空间已经授权的模型与内部调优模型。经过微调、部署的专属模型，只能被它所属业务空间的API‑Key调用，跨业务空间无法访问。
权限配置：默认选择全部权限；安全要求高的业务，切换为自定义权限，可以配置两项管控规则：IP访问白名单、可调用模型列表。IP白名单支持IPv4地址、网段，最多填写20个条目，可以限制该密钥仅从指定公网IP发起请求；也可以勾选模型白名单，限定该密钥只能调用指定几款模型，进一步缩小权限范围，降低密钥泄露带来的风险。
确认配置之后点击确定，生成API‑Key。密钥创建完成之后，仅展示完整字符串一次，务必立刻复制保存，关闭弹窗之后就无法再次查看完整密钥，只能删除重建。不要把密钥直接粘贴写进代码文件，严禁提交到代码仓库，一旦泄露要立刻在控制台删除对应密钥。
配额限制规则：单个主账号最多创建20个业务空间，每一个业务空间内部，最多支持创建20个API‑Key，足够绝大多数个人与中小团队使用。
二、API‑Key两种配置使用方式
拿到密钥之后，有两大类使用场景：第一类是Chatbox、Cline、Dify这类第三方AI工具；第二类是开发者自己写脚本、业务程序，通过curl、Python SDK调用接口，推荐使用环境变量的方式保存密钥，不要硬编码在代码中。
方式一：第三方AI工具接入配置
绝大多数兼容OpenAI协议的AI客户端工具，接入百炼接口，需要填写三项信息：
- API‑Key：刚刚从控制台复制得到的密钥字符串；
- Base‑URL接口地址：
中国大陆环境：https://dashscope.aliyuncs.com/compatible-mode/v1
国际版环境：https://dashscope‑intl.aliyuncs.com/compatible-mode/v1 - 模型名称，例如 qwen‑plus、qwen3‑max、deepseek‑r1等，根据业务需求选择对应模型。
市面上大量Agent工具、IDE插件、本地大模型客户端，都支持自定义Base‑URL，填入上面三项参数，就可以直接消费百炼平台的模型能力。
方式二：操作系统环境变量配置
重要区分：临时环境变量仅当前终端会话生效；永久环境变量重启终端、重启机器依旧保留配置。
Linux / macOS系统
临时会话设置（关闭终端就失效，适合临时调试）
export DASHSCOPE_API_KEY='替换为你的API‑Key'
echo "当前会话密钥前缀：${DASHSCOPE_API_KEY:0:10}********"
写入配置文件实现永久生效：
echo "export DASHSCOPE_API_KEY='替换为你的API‑Key'" >> ~/.bashrc
source ~/.bashrc
echo "永久环境变量配置完成，密钥前缀：${DASHSCOPE_API_KEY:0:10}********"
如果使用zsh终端，需要写入~/.zshrc配置文件。
Windows系统
PowerShell设置临时环境变量：
$env:DASHSCOPE_API_KEY="替换为你的API‑Key"
想要永久生效：Win+Q搜索“编辑系统环境变量”，系统变量新建，变量名填写DASHSCOPE_API_KEY，变量值粘贴API‑Key。配置完成，必须关闭已经打开的终端、IDE编辑器，重新打开才会加载新环境变量。
注意：使用
sudo执行脚本的时候，sudo默认不会继承当前用户环境变量，需要使用sudo -E python demo.py携带‑E参数传递环境变量，否则程序读取不到密钥。
三、完整代码调用实操示例
curl命令行测试接口连通性
export DASHSCOPE_API_KEY="替换你的API‑Key"
curl https://dashscope.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":"你是技术助手，回答简洁。"},
{"role":"user","content":"写一段shell脚本实现日志文件自动清理"}
],
"max_tokens":1024,
"temperature":0.3
}'
Python代码调用示例，读取环境变量，兼容OpenAI接口
# pip install openai python‑dotenv
import os
from openai import OpenAI
from dotenv import load_dotenv
# 优先读取系统环境变量，也可以加载本地.env文件
load_dotenv()
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)
def llm_chat(prompt:str,model:str="qwen‑plus"):
resp = client.chat.completions.create(
model=model,
messages=[
{
"role":"system","content":"你是专业开发助手，输出清晰可执行的结果。"},
{
"role":"user","content":prompt}
],
max_tokens=2048,
temperature=0.4
)
return resp.choices[0].message.content
if __name__ == "__main__":
result = llm_chat("解释什么是Agent智能体，用通俗语言说明")
print(result)
shell脚本封装简易调用，适合自动化脚本场景
#!/bin/bash
export DASHSCOPE_API_KEY="替换你的API‑Key"
OUT_LOG="./llm_call.log"
call_llm(){
local prompt="$1"
curl -s https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
-H "Content‑Type:application/json" \
-d "{
\"model\":\"qwen‑plus\",
\"messages\":[{\"role\":\"user\",\"content\":\"${prompt}\"}],
\"max_tokens\":512
}" >> ${OUT_LOG}
}
call_llm("给出Python处理csv文件的简易示例")
echo "调用完成，输出保存在${OUT_LOG}"
四、API‑Key权限管理核心规则
- 权限跟随业务空间：同一个业务空间下，所有生成的API‑Key权限完全一致，不需要为不同模型分别创建不同密钥。默认业务空间密钥可以调用全部标准公开模型；子业务空间密钥，仅能调用本业务空间已经授权的模型。
- 自定义权限两项能力
- IP白名单：限制密钥请求来源IP，生产环境强烈建议配置，防止密钥泄露之后被外部恶意调用；IPv6仅华北2地域支持，国际地域仅支持IPv4。最多支持20个IP或者网段，逗号分隔填写。
- 模型访问白名单：勾选之后，该密钥仅允许调用勾选范围内模型，缩小攻击面。
- 调优后私有模型限制：经过微调部署生成的私有模型，只允许所属业务空间的密钥调用，其他业务空间的密钥即使属于同一个主账号，也无法访问。
- RAM子账号使用注意：RAM用户想要使用API‑Key，主账号需要预先给RAM账号分配业务空间管理员权限，否则无法创建、使用密钥。
- 详情👉访问阿里云百炼大模型服务平台页面 了解。
五、高频问题与故障排查
问题1：无法创建API‑Key
创建按钮灰色、弹窗提示无权限。
原因：当前登录账号不是业务空间管理员。主账号默认拥有全部权限；RAM子账号，需要主账号在控制台分配业务空间管理员权限之后，才可以创建密钥。
问题2：已经设置环境变量，代码仍然提示找不到API‑Key
- 使用临时环境变量，重启终端、重启IDE之后临时变量就消失，改用永久环境变量配置。
- 修改系统环境变量之后，已经打开的IDE、终端不会自动加载新变量，需要全部关闭，重新打开。
- 使用systemd、supervisor托管运行后台服务，普通shell设置的环境变量不会被服务读取，需要在服务单元配置文件内写入环境变量配置。
- 使用sudo运行脚本，sudo默认不继承用户环境变量，改用
sudo -E python xxx.py。
问题3：调用返回401 Unauthorized鉴权失败
排查顺序：确认密钥字符串复制完整，没有多余空格换行；确认Base‑URL地址正确；确认密钥归属业务空间已经授权对应模型；RAM子账号确认权限配置正确；IP白名单开启情况下，确认发起请求的公网IP在白名单列表内。
问题4：调用私有调优模型返回无权限
私有部署调优模型，必须使用该模型部署所在业务空间生成的API‑Key，跨业务空间的密钥不能访问私有模型。
问题5：密钥意外泄露应急处理
立刻进入百炼控制台API‑Key管理页面，删除泄露的密钥，旧密钥马上失效；重新生成新API‑Key，更新所有业务、脚本、第三方工具的密钥配置；查看调用用量，确认是否存在异常大量消耗。
六、生产环境安全最佳实践
- 禁止硬编码密钥，业务代码、脚本不要直接写死API‑Key字符串，优先使用系统环境变量；容器部署可以使用容器环境变量注入。严禁提交密钥到git代码仓库。
- 生产业务务必开启IP白名单，限制请求来源公网IP。
- 企业多项目，尽量新建多个独立业务空间，不同项目使用独立业务空间，实现模型访问权限隔离。
- 区分个人调试密钥和线上业务密钥，线上业务使用RAM子账号生成的密钥，不要直接使用主账号密钥。
- 定期查看密钥列表，把不再使用的旧API‑Key及时删除，减少安全风险点。
- 开启用量告警，当Token消耗突增的时候收到通知，及时发现密钥泄露或者业务异常。
总结
API‑Key是访问百炼大模型服务的身份凭证，整个接入流程分为开通服务、创建密钥、配置环境变量、业务调用四个主要步骤。创建密钥重点理解归属账号、业务空间、自定义权限三个配置项，业务空间决定密钥能够访问哪些模型，自定义IP白名单、模型白名单可以极大提升密钥的安全等级。开发调试阶段可以使用临时环境变量，线上生产环境配置永久环境变量，不要把密钥写死进代码。针对第三方AI工具，填入API‑Key、兼容模式Base‑URL、模型名称就可以快速完成对接。同时掌握curl、Python的基础调用代码，可以快速验证接口连通性，调试业务逻辑。开发者需要重点关注密钥安全，密钥一旦泄露会带来非预期的Token消耗；一旦泄露，第一时间在控制台删除旧密钥。遇到鉴权报错、读取不到环境变量的问题，按照本文的排坑步骤逐项定位。做好权限隔离、用量监控，就可以安全稳定的把百炼平台各类大模型能力集成到脚本、自研业务系统、各类Agent开发框架当中。
