在使用百炼大模型服务平台进行接口开发的时候，API‑Key是访问大模型服务最重要的身份凭证，所有模型推理请求、多模态生成、Agent工具调用都依靠这串密钥完成身份鉴权。很多刚接触平台的开发者会遇到找不到密钥入口、创建失败、权限不对、环境变量配置不生效、跨地域调用报错等一系列问题。很多新手不清楚业务空间、RAM账号、自定义权限、IP白名单的相互关系，生产环境还会出现密钥泄露带来额度被盗刷的风险。本文完整讲解百炼API‑Key的核心作用，一步步演示控制台创建操作，详细解析归属账号、业务空间、权限管控规则，提供Linux、Windows多系统环境变量配置命令，curl、Python可直接运行调用示例，同时覆盖第三方AI工具接入、配额限制、大量高频报错排查，给出开发和生产环境下密钥安全管理最佳实践，帮助个人开发者以及企业技术团队规范使用API‑Key。
一、API‑Key核心作用与基础概念
API‑Key是百炼平台对外接口调用的身份凭证，相当于访问平台服务的通行证，格式以sk‑开头，每一串密钥绑定归属账号与对应的业务空间。所有通过HTTP接口发起的模型对话、图像生成、语音解析、Embedding向量生成等请求，请求头携带该密钥，平台才会识别调用方身份，完成鉴权、额度扣减、用量统计。详情👉访问阿里云百炼大模型服务平台页面 了解。
重要安全提醒：任何拿到API‑Key的外部人员，都可以使用你的账号身份发起模型调用，并且消耗账号下免费Tokens或者付费资源，因此密钥不可以公开，禁止上传至代码仓库、聊天记录、公开文档。创建密钥的时候明文只会展示一次，复制保存完成关闭弹窗之后，控制台只能看到脱敏后的内容，密钥丢失只能执行重新创建，旧密钥会直接失效。
同时要区分两套不同密钥体系：普通按量/免费额度使用的sk‑开头API‑Key；Token Plan订阅套餐使用sk‑sp‑前缀专属密钥，两套密钥不能混用，对应不同Base‑URL，混用直接鉴权失败。
地域强隔离规则：不同地域之间API‑Key、接入域名互相独立，不能跨地域复用。例如华北2（北京）地域生成的密钥，不能直接用于新加坡、法兰克福地域接口，切换地域需要在对应地域控制台重新创建密钥。新人免费Tokens仅华北2（北京）地域生效，测试免费额度务必确认控制台地域已经切换为华北2（北京）。
二、控制台完整创建API‑Key详细步骤
前置条件
能够创建API‑Key的账号角色为主账号超级管理员或者业务空间管理员，普通成员账号没有创建密钥的权限，如果按钮置灰，需要联系管理员授予权限。详情👉访问阿里云百炼大模型服务平台页面 了解。
操作步骤：
- 登录阿里云账号，进入百炼大模型服务平台控制台，页面右上角确认切换目标地域（测试免费额度选华北2（北京））。
- 在控制台常用功能区域找到【API Key】模块，进入密钥管理页面。
- 点击右上角【创建API Key】，弹出配置弹窗，填写三项核心配置：归属账号、归属业务空间、权限配置。
归属账号选项说明
- 主账号：默认选择，适合个人开发者直接使用。
- RAM用户：企业团队场景使用，选择RAM子账号，实现权责隔离，子账号需要提前被授予百炼相关权限策略。
归属业务空间选项说明
业务空间是平台资源隔离单元，同一个主账号最多支持20个业务空间。
- 默认业务空间：绝大多数个人开发者选择此项，该空间下密钥可以调用全部已授权标准模型。
- 新建/其他子业务空间：企业用来做项目隔离，不同业务空间实现成本、权限分开核算；部署调优之后生成的自定义模型，只能被该模型所属业务空间的API‑Key调用，跨空间无法访问。
权限配置选项，分为【全部】与【自定义】两种模式
- 全部权限：该业务空间下所有授权模型均可调用，适合个人开发快速调试。
- 自定义权限，适合生产环境做最小权限管控，可以配置两类限制：
- IP访问白名单：限制发起请求的来源IP，最多支持20个IP或者网段，英文逗号分隔；华北2地域支持IPv6，海外部分地域仅支持IPv4。默认
0.0.0.0/0代表不限制来源IP。 - 访问模型范围：开启开关之后，该密钥仅可以调用勾选的模型列表，最多勾选30个模型，防止密钥泄露之后调用不需要的高成本大模型。
- IP访问白名单：限制发起请求的来源IP，最多支持20个IP或者网段，英文逗号分隔；华北2地域支持IPv6，海外部分地域仅支持IPv4。默认
填写完成，补充简单描述用来标记密钥用途，点击确定，立刻弹出完整API‑Key明文，马上复制保存，关闭弹窗后就再也无法查看完整密钥。
配额限制：单个业务空间最多创建20个API‑Key；主账号最多20个业务空间。不需要使用的旧密钥及时在控制台删除，降低泄露风险。
三、API‑Key环境变量配置实操
开发规范：生产环境严禁把API‑Key硬编码写进源代码，优先使用操作系统环境变量，或者专业密钥管理服务保存凭证。下面分别给出Linux/macOS、Windows PowerShell、Windows CMD的临时、永久配置命令。
Linux / macOS
临时配置（仅当前终端会话生效，关闭终端丢失）
export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# 打印部分字符校验是否配置成功
echo ${DASHSCOPE_API_KEY:0:12}******
永久配置写入bashrc（bash终端）
echo "export DASHSCOPE_API_KEY='sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'" >> ~/.bashrc
source ~/.bashrc
echo ${DASHSCOPE_API_KEY:0:12}******
zsh终端用户写入~/.zshrc：
echo "export DASHSCOPE_API_KEY='sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'" >> ~/.zshrc
source ~/.zshrc
Windows PowerShell
临时会话配置：
$env:DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
$env:DASHSCOPE_API_KEY.Substring(0,12)+"******"
Windows CMD命令提示符临时配置
set DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
echo %DASHSCOPE_API_KEY%
重要提示：临时环境变量不会对已经打开的IDE、应用生效，配置完成需要重启VS Code、终端程序。使用
sudo执行脚本的时候sudo默认不会继承用户环境变量，可以使用sudo -E python demo.py参数传递环境变量。
四、接口调用实操，curl与Python完整可运行代码
兼容OpenAI接口地址，中国大陆华北2地域：https://dashscope.aliyuncs.com/compatible-mode/v1；国际版地址：https://dashscope‑intl.aliyuncs.com/compatible‑mode/v1。
curl命令行测试调用：
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":"简单介绍百炼API‑Key的作用"}
],
"temperature":0.7,
"max_tokens":1024
}'
Python代码调用示例，使用openai兼容SDK，先执行安装依赖：
pip install openai
完整代码：
import os
from openai import OpenAI
# 从系统环境变量读取密钥，不硬编码
client = OpenAI(
api_key=os.environ.get("DASHSCOPE_API_KEY"),
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)
def llm_api_test(model_name, user_input):
messages = [
{
"role":"system","content":"你是模型接口测试助手，输出简短清晰。"},
{
"role":"user","content":user_input}
]
try:
resp = client.chat.completions.create(
model=model_name,
messages=messages,
temperature=0.6,
max_tokens=1024,
stream=False
)
print("模型返回结果：")
print(resp.choices[0].message.content)
usage = resp.usage
print(f"\n输入Token:{usage.prompt_tokens}，输出Token:{usage.completion_tokens}")
return resp
except Exception as err:
err_text = str(err)
print(f"接口调用异常：{err_text}")
return None
if __name__ == "__main__":
llm_api_test("qwen‑plus","写一段读取json文件的python示例代码")
原生dashscope SDK调用方式：
pip install dashscope
import os
import dashscope
from dashscope import Generation
dashscope.api_key = os.environ.get("DASHSCOPE_API_KEY")
resp = Generation.call(
model="qwen‑flash",
messages=[{
"role":"user","content":"解释API‑Key为什么不要硬编码写代码"}],
result_format="message"
)
if resp.status_code == 200:
print(resp.output.choices[0].message.content)
else:
print(f"错误码：{resp.code}，错误信息：{resp.message}")
五、第三方AI工具接入配置方式
Chatbox、Cline、Claude Code、Dify、Postman这类第三方工具接入百炼，需要填写三项关键信息：
- API‑Key：控制台复制
sk‑开头密钥；Token Plan套餐填入sk‑sp‑专属密钥。 - Base‑URL：区分国内、国际地域地址，Token Plan套餐使用对应专属访问地址。
- 模型ID：例如
qwen‑plus、qwen3.8‑max，模型ID参考平台模型广场文档。
以Chatbox配置为例子，工具内选择自定义OpenAI兼容服务，依次填入上面三项内容保存，即可发起请求。
六、权限规则深度解读
- API‑Key权限完全由归属业务空间决定，同一个业务空间下所有生成的API‑Key权限保持一致，不需要针对每一个模型单独创建密钥。
- 默认业务空间密钥，可以调用全部标准公开模型。
- 子业务空间密钥，仅能够调用该业务空间已经完成授权的模型；调优、微调之后部署的私有模型，只能使用该模型所属业务空间的密钥调用。
- 自定义权限开启模型访问范围之后，即使业务空间已经授权该模型，如果没有勾选，该密钥依旧无法调用。
- RAM账号移出业务空间，该RAM账号对应的API‑Key立刻失效；RAM账号被删除，密钥同步失效。
- API‑Key本身没有过期时间，如果需要短期临时凭证，可以使用平台临时API‑Key，最长有效期1800秒，到期自动失效。
七、高频问题排查汇总
无法点击创建API Key按钮
当前账号不是超级管理员或者业务空间管理员，需要主账号在RAM控制台授予对应权限，并且把账号加入目标业务空间。环境变量已经设置，代码依旧提示找不到API‑Key
- 临时环境变量仅当前终端会话有效，IDE、其他终端窗口不会继承；配置完成务必重启IDE、终端。
- 使用
sudo运行脚本，sudo默认不携带用户环境变量，使用sudo -E参数。 - systemd、supervisord托管服务，需要在服务配置文件中单独写入环境变量。
返回401 InvalidApiKey无效密钥报错
核对密钥复制完整无多余空格换行；确认地域与密钥匹配；普通密钥和Token Plan专属密钥不要混用；确认密钥没有被删除。可以调用公开模型，但是无法调用微调之后私有模型
微调部署的模型绑定所属业务空间，切换至该模型所在业务空间，使用该业务空间生成的API‑Key。设置IP白名单之后调用失败
检查填写IP地址是否为公网出口IP；确认地域对IPv6支持情况；多个IP使用英文逗号分隔，不能中文逗号。免费额度调用不生效
确认地域切换华北2（北京）；使用普通sk‑开头密钥，不能使用Token Plan的sk‑sp‑密钥。密钥泄露风险怎么处理
立刻进入控制台删除泄露的API‑Key，旧密钥马上失效；重新生成新密钥；查看用量报表确认是否存在异常调用。
八、密钥安全管理生产最佳实践
- 权限最小化原则：生产环境优先开启自定义权限，配置IP白名单，限制可调用模型列表；不要全部权限直接给到线上业务。
- 禁止硬编码密钥，禁止提交Git代码仓库；开发环境使用环境变量，正式生产业务使用密钥管理服务。
- 企业业务尽量使用RAM子账号创建API‑Key，不要直接使用主账号密钥做线上业务调用。
- 定期清理控制台废弃、长期不用的API‑Key，减少暴露面。
- 高风险业务场景，优先使用平台临时短期API‑Key，避免长期有效的静态密钥。
- 开启用量监控告警，当调用量突增及时排查是否密钥发生泄露。
- 区分普通密钥和Token Plan专属密钥，两套密钥不要混淆，各自使用对应的Base‑URL。
总结
API‑Key是访问百炼大模型接口的身份凭证，地域、归属账号、业务空间共同决定密钥的实际权限。创建密钥需要管理员权限，明文只展示一次，务必要立刻保存。个人开发者优先默认业务空间全部权限；企业生产环境建议开启自定义权限，配置IP白名单、模型调用范围，落实最小权限安全策略。详情👉访问阿里云百炼大模型服务平台页面 了解。
配置凭证优先操作系统环境变量，提供了Linux、macOS、Windows多平台命令示例，同时提供curl、Python两套可直接运行的调用代码，也支持各类第三方AI工具接入。需要注意地域隔离、普通密钥和Token Plan专属密钥的差异，遇到401鉴权、环境变量不生效等问题，对照排错清单定位原因。
密钥安全是开发当中不可忽视的环节，一旦泄露会带来额度被盗刷风险，线上业务尽量使用RAM子账号、IP白名单、临时密钥，定期清理废弃密钥，做好用量监控，保障大模型业务安全稳定运行。
