大模型服务平台汇集了文本对话、多模态识图、文生视频、Agent智能体、知识库RAG等丰富能力。新开通服务的账号会自动发放超7000万免费Tokens额度，每一款标准模型分配100万免费Token，非常适合开发者开展原型验证、学习调试业务逻辑。想要通过程序、第三方AI工具调用平台各类大模型能力，API‑Key是核心身份凭证，每一次接口请求都依靠该密钥完成身份鉴权，用来确认调用账号、可用模型以及计费抵扣规则。
很多刚刚接触大模型接口开发的新手，经常卡在API‑Key创建、环境变量配置环节，遇到无法创建密钥、环境变量不生效、接口返回401鉴权报错、密钥权限不足、RAM子账号调用失败等一系列问题。同时密钥安全是开发工作中不可忽视的重点，一旦密钥发生泄露，外部人员可以冒用身份调用接口，产生大量非预期消耗。本文完整讲解百炼API‑Key控制台创建流程、业务空间概念、不同操作系统环境变量配置、第三方AI工具接入方式，提供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客户端、Agent工具、IDE插件，接入百炼接口，都需要填写三项核心信息：
- 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等，根据业务需求选择对应模型。
将上面三项参数填入工具配置面板，就可以直接消费百炼平台的模型推理能力。
方式二：操作系统环境变量配置
需要区分临时环境变量和永久环境变量：临时环境变量仅当前终端会话生效；永久环境变量关闭终端、重启机器配置依旧保留。
Linux / macOS系统
临时会话设置（关闭终端就失效，适合临时调试）
export DASHSCOPE_API_KEY='替换为你的API‑Key'
echo "当前会话密钥前缀：${DASHSCOPE_API_KEY:0:10}********"
写入配置文件实现永久生效（bash终端）：
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开发框架当中。
