获取与配置 API Key

​

套餐类型识别

百炼提供三种 API Key 类型。API Key 与 Base URL 必须配套使用，否则调用 Anthropic 兼容接口时可能返回 401 或 403 错误。

API Key 前缀	套餐类型	Anthropic 兼容 Base URL
sk-	按量付费	https://dashscope.aliyuncs.com/apps/anthropic
sk-sp-	Token Plan	https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic
sk-ws-	Coding Plan	https://coding.dashscope.aliyuncs.com/apps/anthropic

​

查看套餐类型

1. 登录百炼控制台。
2. 单击顶部导航栏的订阅，展开后选择Token Plan，或进入我的订阅页面。
3. 在我的订阅页面，通过Coding Plan和Token Plan页签查看各自的订阅状态，以及对应的 API Key 和 Base URL。

​

获取 API Key

1. 前往阿里云百炼API Key页面，在右上角选择地域。每个地域有独立的接入域名、API Key 和模型列表，不能跨地域混用，各地域的 API Key 入口和接入域名请参见各地域接入信息。
2. 若已有可用 API Key，直接在列表中复制。若需创建，单击创建 API Key，在弹窗中配置以下选项后单击确定（若无法创建，请联系超级管理员或业务空间管理员）：
   • 归属账号：默认选择阿里云账号（主账号）（账号名通常为一串数字）。如需为团队成员或应用创建权责独立的 API Key 并结合业务空间做精细化模型访问控制，可选择RAM 用户（账号格式 username@<AccountAlias>.onaliyun.com）。
   • 归属业务空间：默认选择默认业务空间，此空间下的 Key 可调用所有标准模型（数量上限与主账号配额见时效性与限制）。如需权限隔离、精细化模型访问控制或独立成本核算，请选择非默认业务空间，参见业务空间管理。
   • 权限：建议选择全部。如需精细控制，可选择自定义，配置可访问 IP 和可访问模型范围（数量限制见时效性与限制）。
3. 点击新创建的 API Key 旁的图标复制 API Key。

​

配置 API Key 到环境变量

• 方式一：在第三方工具中进行配置 如果在 Chatbox 等工具或平台中调用模型，您可能需要输入三个信息：
  • 本文获取的 API Key
  • Base URL：
    • 新加坡：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
    • 其他地域：请参见Base URL 总览
  • 模型名称，如 qwen-plus、qwen-max、deepseek-v4-pro 等。
  百炼 API Key 用于调用百炼的 API 端点，不同套餐对应的 API Key 前缀与 Base URL 请以本文「套餐类型识别」章节为准。部分第三方工具的千问模式使用千问网页版账号登录（qwenauth），与百炼 API Key 属于不同的认证方式：工具要求填写 API Key 时，请使用百炼 API Key；工具要求账号登录时，请使用千问网页版账号。两者不能混用，否则调用会失败，并可能返回「没有额度」等错误。
• 方式二：配置 API Key 到环境变量，后续支持 cURL 和代码调用
  请勿在客户端代码（如浏览器、移动应用）或不可信环境中配置或使用长期有效的 API Key。可以使用临时 API Key（最长 1800 秒）。
  以下示例中的 <YOUR_API_KEY> 需替换为真实的 API Key。
  • Linux系统
  • macOS系统
  • Windows系统

  • 添加永久性环境变量
  • 添加临时性环境变量
  • 服务管理器 (systemd)

  将环境变量设置追加到~/.bashrc文件中。

  Copy

  echo "export DASHSCOPE_API_KEY='<YOUR_API_KEY>'" >> ~/.bashrc
  source ~/.bashrc
  echo "百炼 API Key 永久配置为：${DASHSCOPE_API_KEY:0:10}*********"
  

  Copy

  export DASHSCOPE_API_KEY='<YOUR_API_KEY>'
  echo "当前会话百炼 API Key 配置为：${DASHSCOPE_API_KEY:0:10}*********"
  

  以下操作适用于将应用作为后台服务部署的场景。

  1. 创建环境文件

  Copy

  sudo sh -c "echo 'DASHSCOPE_API_KEY=<YOUR_API_KEY>' > /etc/your-app/env"
  sudo chmod 600 /etc/your-app/env # 限制只有root用户有访问权限
  

  2. 修改 systemd 服务文件（如 /etc/systemd/system/your-app.service）：

  Copy

  [Service]
  # 加载密钥文件
  EnvironmentFile=/etc/your-app/env
  ExecStart=/usr/bin/python /opt/your-app/main.py
  

  3. 重载服务

  Copy

  sudo systemctl daemon-reload
  sudo systemctl restart your-app
  

  • 添加永久性环境变量
  • 添加临时性环境变量

  将环境变量设置追加到~/.bash_profile或~/.zshrc文件中。

  Copy

  VAR_VALUE="<YOUR_API_KEY>"; \
  echo "export DASHSCOPE_API_KEY='$VAR_VALUE'" >> ~/.zshrc 2>/dev/null
  echo "export DASHSCOPE_API_KEY='$VAR_VALUE'" >> ~/.bash_profile 2>/dev/null
  source ~/."${SHELL##*/}rc" 2>/dev/null
  echo "百炼 API Key 永久配置为：${DASHSCOPE_API_KEY:0:10}*********"
  

  Copy

  export DASHSCOPE_API_KEY='<YOUR_API_KEY>'
  echo "当前会话百炼 API Key 配置为：${DASHSCOPE_API_KEY:0:10}*********"
  

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

  • 系统属性
  • CMD
  • PowerShell

  系统属性方式注意事项：

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

  1. 在Windows系统桌面中按Win+Q键，在搜索框中搜索编辑系统环境变量，单击打开系统属性界面。
  2. 在系统属性窗口，单击环境变量，然后在系统变量区域下单击新建，变量名填入DASHSCOPE_API_KEY，变量值填入您的DashScope API Key。
  3. 依次单击三个窗口的确定，关闭系统属性配置页面，完成环境变量配置。
  4. 打开CMD（命令提示符）窗口或Windows PowerShell窗口，执行如下命令检查环境变量是否生效。
     • CMD查询命令：

  Copy

  echo 百炼 API Key 永久配置为：%DASHSCOPE_API_KEY:~0,10%*********
  

  • Windows PowerShell查询命令：

  Copy

  Write-Host "百炼 API Key 永久配置为：$($env:DASHSCOPE_API_KEY.Substring(0, [Math]::Min(10, $env:DASHSCOPE_API_KEY.Length)))*********"
  

  • 添加永久性环境变量
  • 添加临时性环境变量

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

  1. 在CMD中运行以下命令。

  Copy

  setx DASHSCOPE_API_KEY "<YOUR_API_KEY>"
  

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

  Copy

  echo 百炼 API Key 永久配置为：%DASHSCOPE_API_KEY:~0,10%*********
  

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

  Copy

  set "DASHSCOPE_API_KEY=<YOUR_API_KEY>"
  

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

  Copy

  echo 当前会话百炼 API Key 配置为：%DASHSCOPE_API_KEY:~0,10%*********
  

  • 添加永久性环境变量
  • 添加临时性环境变量

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

  1. 在PowerShell中运行以下命令。

  Copy

  [Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "<YOUR_API_KEY>", [EnvironmentVariableTarget]::User)
  

  2. 打开一个新的PowerShell窗口。
  3. 在新的PowerShell窗口运行以下命令，检查环境变量是否生效。

  Copy

  Write-Host "百炼 API Key 永久配置为：$($env:DASHSCOPE_API_KEY.Substring(0, [Math]::Min(10, $env:DASHSCOPE_API_KEY.Length)))*********"
  

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

  Copy

  $env:DASHSCOPE_API_KEY = "<YOUR_API_KEY>"
  Write-Host "当前会话百炼 API Key 配置为：$($env:DASHSCOPE_API_KEY.Substring(0, [Math]::Min(10, $env:DASHSCOPE_API_KEY.Length)))*********"
  

​

时效性与限制

API Key 没有失效时间限制，若需要有时效性的 API Key，可生成临时 API Key（最长 1800 秒）。 API Key 的状态随账号操作而变化：

触发操作	主账号的 API Key	RAM 账号的 API Key
主动删除 API Key	删除后立即失效，不可恢复	删除后立即失效，不可恢复
将账号移出业务空间	—	移出业务空间后 API Key 失效，重新加入后恢复生效
在RAM 控制台删除账号/角色	—	删除后立即失效，不可恢复

​

数量与权限限制

API Key 相关限制汇总：

• API Key 数量：账号+地域维度最多 50 个，不按业务空间限制；单个主账号最多 10 个业务空间（含默认业务空间）。
• 自定义权限可选模型：最多 30 个，限于该业务空间已授权的模型。
• IP 白名单：最多 20 个地址或网段；IPv4（0.0.0.0/0）默认全部放通；IPv6 仅华北2（北京）地域支持，美国（弗吉尼亚）地域仅支持 IPv4；批量输入用英文逗号隔开。输入 IP 地址后需按回车键确认，系统才会识别并保存，不按回车直接单击确定不会保存该地址。白名单按请求连接 IP 校验，不校验 X-Forwarded-For 等请求头 IP；通过代理或网关访问时请添加代理节点出口 IP。白名单以外 IP 的请求将被拒绝，返回 HTTP 403 及 IP access denied by API-Key restrictions。
• 临时 API Key：最长 1800 秒。

​

API 调用

请访问文本生成以及更多模型的 API 参考。 OpenAI SDK 支持的模型，请参考OpenAI 兼容。

​

常见问题

​

无法创建 API Key？

API Key 的创建需使用超级管理员或业务空间管理员操作。若系统返回 Apikey limit number exceeded for MainAccount，表示当前账号的 API Key 数量已达上限，请删除不再使用的 API Key 后重试。

​

如何管理 API Key 的权限？

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

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

调用在阿里云百炼调优后的模型：此类模型部署成功后，仅能用其所在业务空间的API Key调用。 如需在业务空间之外做更细粒度的控制，可在创建或编辑 API Key 时将权限切换为自定义，配置：

• IP 白名单规则：默认放通全部 IPv4，完整规则参见时效性与限制。
• 访问模型范围：开关开启后，该 API Key 仅能调用已勾选的模型（限于该业务空间已授权的模型，数量限制参见时效性与限制）。

​

环境变量已设置，为何代码仍提示找不到 API Key？

具体原因如下：

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

​

百炼 API Key 与 RAM AccessKey 有何区别？

两者是用途不同的凭证。百炼 API Key 不是密钥对，创建后只会得到一个字符串，不存在 AccessKeyId 与 AccessKeySecret，因此在API Key 页面看不到"访问密钥密文"。具体区别如下：

• 格式：百炼 API Key 是以sk-开头的单个字符串；RAM AccessKey 由 AccessKeyId 和 AccessKeySecret 组成密钥对。
• 用途：百炼 API Key 用于调用百炼的模型与应用服务；RAM AccessKey 用于调用阿里云 OpenAPI。
• 获取方式：百炼 API Key 在阿里云百炼的API Key 页面创建，具体步骤参见本文"获取 API Key"；RAM AccessKey 在 RAM 控制台创建。
• 显示规则：百炼 API Key 仅在创建成功的弹窗中完整显示一次，供您复制或下载保存，关闭弹窗后列表中只显示脱敏形式，无法再次查看完整明文；RAM AccessKey 的 AccessKeySecret 同样仅在创建时显示一次。

​

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

每个主账号下最多可创建10个业务空间（包括默认业务空间）；API Key 数量为账号+地域维度 50 个，不按业务空间限制。

​

百炼是否支持批量导出所有 API Key 信息？

不支持。百炼控制台的API Key 管理页面未提供批量导出或下载功能，如需获取多个 API Key 的信息，请在该页面逐个查看并复制。