如何获取API Key - 大模型服务平台百炼

使用阿里云百炼的大模型或应用前，请先获取API Key作为鉴权凭证。

说明

本文介绍的是百炼按量付费的 API Key。如果您使用的是 Token Plan 或 Coding Plan，请使用对应的专属 API Key（以sk-sp-开头），获取方式请参见Token Plan API Key和Coding Plan 的 API Key。

获取API Key

重要

需使用主账号，或具备管理员或API-Key页面权限的子账号操作。

华北2（北京）、新加坡等地域

前往阿里云百炼控制台首页，在页面右上角选择华北2（北京）、 新加坡、日本（东京）、中国香港、德国（法兰克福）地域，进入API Key页面，单击创建API Key。
在弹窗中配置以下信息，并单击确定：
- 归属业务空间：建议选择默认业务空间。
- 描述（可选，最多200字符）：输入描述信息，方便后续识别该 API Key 的用途。
- 权限：建议选择全部，若有更精细的权限控制需求，可以选择自定义来控制可访问 IP 和可访问模型。
如何选择 API Key 的权限配置？
阿里云百炼提供两种类型的权限配置，请根据实际需求进行选择：
- 全部：授予该 API Key 调用所有模型与应用的权限。
- 自定义：可配置访问 IP 白名单和可访问模型范围。
  IP 白名单默认设置：IPv4 （0.0.0.0/0）和 IPv6 （仅北京地域支持）全部放通。
  IP 白名单支持设置最多 20 个 IPv4、IPv6 的地址或网段。
创建成功后，弹窗会显示完整的 API Key 和 API Host（服务端点地址）。请立即复制或下载保存，注意妥善保管，任何获取到该密钥的人都能以您的身份发起服务请求并产生费用。关闭弹窗后将无法再次查看或复制明文 API Key。如果丢失，请重置或创建新的密钥。
主账号可以查看全部API Key，子账号仅能查看自己创建的API Key。

美国（弗吉尼亚）地域

前往阿里云百炼控制台首页，在页面右上角切换到美国（弗吉尼亚）地域，进入API Key管理页面，单击创建API Key。
在弹窗中配置以下信息，并单击确定：
- 归属业务空间：建议选择默认业务空间。
- 归属账号：选择该 API Key 归属的账号。
- 描述（可选，最多200字符）：输入描述信息，方便后续识别该 API Key 的用途。
创建成功后，弹窗会显示完整的 API Key。请立即复制并妥善保存，关闭弹窗后将无法再次查看完整的 API Key。
在API Key列表中，点击API Key旁的图标可复制脱敏后的API Key。
主账号可以查看全部API Key，子账号仅能查看自己创建的API Key。

API Key 管理操作

在 API Key 列表中，您可以对已有 API Key 执行以下操作：

编辑：修改 API Key 的描述和权限配置。
删除：永久删除该 API Key，删除后不可恢复。
禁用（美国（弗吉尼亚）地域除外）：暂停该 API Key 的使用，不影响密钥保存，可随时重新启用。
重置（美国（弗吉尼亚）地域除外）：生成新的密钥值，旧密钥立即失效。

何时选择其他归属账号或业务空间？

如果您有团队协作或成本分摊需求，可以了解以下概念：

归属业务空间：用于隔离不同项目或团队的资源和权限。若需管控某类用户可调用的模型，或对模型调用的费用进行分账，请创建/选择列表中的子业务空间。

详情请参见API Key 权限以及账单查询与成本管理。

配置API Key到环境变量

建议您把API Key配置到环境变量，从而避免在代码里显式地配置API Key，降低泄漏风险。

Linux系统

添加永久性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。

执行以下命令来将环境变量设置追加到~/.bashrc 文件中。
```
# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc
```
也可以手动修改~/.bashrc 文件。
手动修改
执行以下命令，打开~/.bashrc 文件。
```
nano ~/.bashrc
```
在配置文件中添加以下内容。
```
# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
```
在nano编辑器中，按Ctrl + X，接着按Y，再按Enter以保存并关闭文件。
执行以下命令，使变更生效。
```
source ~/.bashrc
```
重新打开一个终端窗口，运行以下命令检查环境变量是否生效。
```
echo $DASHSCOPE_API_KEY
```

添加临时性环境变量

如果您仅希望在当前会话中使用该环境变量，可以添加临时性环境变量。

执行以下命令。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

执行以下命令，验证该环境变量是否生效。
```
echo $DASHSCOPE_API_KEY
```

macOS系统

添加永久性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。

在终端中执行以下命令，查看默认Shell类型。
```
echo $SHELL
```
根据默认Shell类型进行操作。
Zsh
1. 执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。
```
# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.zshrc
```
  也可以手动修改~/.zshrc 文件。
  手动修改
  执行以下命令，打开Shell配置文件。
  nano ~/.zshrc
  在配置文件中添加以下内容。
  # 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
  在nano编辑器中，按Ctrl + X，接着按Y，再按Enter以保存并关闭文件。
2. 执行以下命令，使变更生效。
```
source ~/.zshrc
```
3. 重新打开一个终端窗口，运行以下命令检查环境变量是否生效。
```
echo $DASHSCOPE_API_KEY
```
Bash
1. 执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。
```
# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bash_profile
```
  也可以手动修改~/.bash_profile 文件。
  手动修改
  执行以下命令，打开Shell配置文件。
  nano ~/.bash_profile
  在配置文件中添加以下内容。
  # 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
  在nano编辑器中，按Ctrl + X，接着按Y，再按Enter以保存并关闭文件。
2. 执行以下命令，使变更生效。
```
source ~/.bash_profile
```
3. 重新打开一个终端窗口，运行以下命令检查环境变量是否生效。
```
echo $DASHSCOPE_API_KEY
```

添加临时性环境变量

如果您仅希望在当前会话中使用该环境变量，可以添加临时性环境变量。

以下命令适用于 Zsh 和 Bash。

执行以下命令。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

执行以下命令，验证该环境变量是否生效。
```
echo $DASHSCOPE_API_KEY
```

Windows系统

在Windows系统中，您可以通过系统属性、CMD或PowerShell配置环境变量。

系统属性

说明

此方式配置的环境变量永久生效。
修改系统环境变量需具备管理员权限。
配置环境变量后不会立即影响已经打开的命令窗口、IDE或其他正在运行的应用程序。您需要重新启动这些程序或者打开新的命令行使环境变量生效。

在Windows系统桌面中按Win+Q键，在搜索框中搜索编辑系统环境变量，单击打开系统属性界面。
在系统属性窗口，单击环境变量，然后在系统变量区域下单击新建，变量名填入DASHSCOPE_API_KEY，变量值填入您的DashScope API Key。
依次单击三个窗口的确定，关闭系统属性配置页面，完成环境变量配置。

打开CMD（命令提示符）窗口或Windows PowerShell窗口，执行如下命令检查环境变量是否生效。

CMD查询命令：

echo %DASHSCOPE_API_KEY%

Microsoft Windows [版本 10.0.19045.5371]
(c) Microsoft Corporation。保留所有权利。
C:\Windows\system32>echo %DASHSCOPE_API_KEY%
sk-ee16697?fe4
C:\Windows\system32>

Windows PowerShell查询命令：

echo $env:DASHSCOPE_API_KEY

Windows PowerShell
版权所有 (C) Microsoft Corporation。保留所有权利。
尝试新的跨平台 PowerShell https://aka.ms/pscore6
PS C:\Windows\system32> echo $env:DASHSCOPE_API_KEY
sk-ee166797fe40xxx
PS C:\Windows\system32>

CMD

添加永久性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以按如下操作。

在CMD中运行以下命令。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
setx DASHSCOPE_API_KEY "YOUR_DASHSCOPE_API_KEY"

打开一个新的CMD窗口。
在新的CMD窗口运行以下命令，检查环境变量是否生效。
```
echo %DASHSCOPE_API_KEY%
```

添加临时性环境变量

如果您仅希望在当前会话中使用该环境变量，可以在CMD中运行以下命令。

REM 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
set DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

您可以在当前会话运行以下命令检查环境变量是否生效。

echo %DASHSCOPE_API_KEY%

PowerShell

添加永久性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以按如下操作。

在PowerShell中运行以下命令。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "YOUR_DASHSCOPE_API_KEY", [EnvironmentVariableTarget]::User)

打开一个新的PowerShell窗口。
在新的PowerShell窗口运行以下命令，检查环境变量是否生效。
```
echo $env:DASHSCOPE_API_KEY
```

添加临时性环境变量

如果您仅希望在当前会话中使用该环境变量，可以在PowerShell中运行以下命令。

# 用您的阿里云百炼API Key代替YOUR_DASHSCOPE_API_KEY
$env:DASHSCOPE_API_KEY = "YOUR_DASHSCOPE_API_KEY"

您可以在当前会话运行以下命令检查环境变量是否生效。

echo $env:DASHSCOPE_API_KEY

使用API Key

方式一：在第三方工具中调用模型
常用工具配置：Chatbox、Cline、Claude Code、Dify、OpenClaw、Postman、Qwen Code。
方式二：通过代码调用模型
通过代码首次调用千问API，建议配置API Key到环境变量，以避免硬编码在代码中导致泄露风险。

请勿以任何方式公开API Key，避免因未经授权的使用导致安全风险或资金损失。

API Key 安全升级说明

百炼已对按量付费 API Key 生成和存储机制进行安全升级（美国（弗吉尼亚）地域除外）。升级前已创建的sk-开头的 API Key 可继续正常使用，不受影响。升级后新创建的 API Key 统一以sk-ws开头。

下表列出了升级前后 API Key 的主要差异。

对比项	升级前创建的 API Key	升级后创建的 API Key
Key 格式	以 `sk-` 开头，长度较短（约 32 位）	以 `sk-ws` 开头，长度较长
明文查看	可在控制台随时复制完整明文	仅在创建时展示一次明文，关闭弹窗后无法再次查看。如果丢失，请进行重置或重新创建
调用能力	可正常调用模型，功能不受影响	可正常调用模型，与升级前功能完全一致
建议操作	建议创建新密钥替换旧密钥，以获得更完善的安全保障	创建后请立即复制保存，妥善保管

API Key权限说明

API Key的调用权限完全由其归属业务空间决定。同一空间内的API Key权限相同，无需为不同模型（如文生文、文生图、语音合成）创建不同的API Key。

默认业务空间下的API Key：可调用所有标准模型，以及默认业务空间内的应用。
子业务空间下的API Key：可调用该子业务空间已获得授权的标准模型，以及该子业务空间内的应用。

说明

您可以在创建API Key 或点击已有 API Key 操作列的编辑时，将权限切换为自定义，即可配置：

仅美国（弗吉尼亚）地域不支持以下配置

IP 访问白名单：仅允许名单内的 IP 使用该 API Key 发起调用（支持 IPv4、IPv6 与网段）。
访问权限范围：为该API Key 勾选可访问的模型或应用；未勾选的资源无法通过此API Key 调用。

API Key时效性说明

创建的API Key没有失效日期，手动删除后即失效。

若需为第三方应用或用户提供临时访问权限，或需严格控制敏感数据访问、删除等高风险操作，可生成临时API Key（有效期60秒），避免暴露长期有效的API Key，降低泄露风险。

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。

常见问题

Q：单个主账号下最多能创建多少个API Key？

A：对于新加坡、华北2（北京）、中国香港、日本（东京）和德国（法兰克福）地域，每个主账号在每个地域最多可创建50个API Key。

对于美国（弗吉尼亚）地域，每个归属账号（包括主账号）最多可创建20个API Key。

Q：RAM用户被删除后，其创建的API Key是否依然可用？

A：在RAM控制台中禁用或删除RAM用户后，其创建的所有API Key均将失效，无法再用于模型调用。

Q：用echo命令确认环境变量设置成功了，为什么运行代码还是提示找不到API Key？

A：具体原因如下：

情况一：没有设置永久性环境变量。临时环境变量只在当前终端会话有效，对于已经启动的 IDE 或其他应用程序并不会生效。请参考本文中设置永久性环境变量的方法。
情况二：没有重启IDE、命令行工具或应用。
- 通常需要重启IDE（如VS Code）或命令行工具，使其能够加载最新的环境变量。
- 如果在部署应用后设置了环境变量，可能需要重启应用服务，让应用能够重新加载环境变量。
情况三：需要在配置文件添加环境变量。如果您的应用是通过服务管理器（如systemd、supervisord）启动的，可能需要在服务管理器的配置文件中添加环境变量。
情况四：用了sudo命令。如果使用sudo python xx.py运行脚本，可能会遗漏当前用户环境变量，因为sudo默认不继承所有环境变量。您可采用sudo -E python xx.py命令，其中的-E 参数确保环境变量被传递。如有权限执行该脚本，可以直接执行 python xx.py。