阿里云百炼API‑Key完整实操指南：账号开通、免费额度领取与多方式调用实战教程与排错全流程手册-阿里云开发者社区

随着大模型技术普及，越来越多开发者、科研人员、业务团队需要通过API接口调用各类大模型服务。百炼作为一站式大模型服务平台，聚合多款主流文本、多模态大模型，对外提供兼容OpenAI协议的标准API接口。无论是自主开发AI应用、调试知识库RAG项目，还是对接Claude‑Code、Hermes Agent、OpenClaw这类终端智能体工具，都必须获取合法有效的API‑Key作为身份鉴权凭证。

对于刚接触平台的新手，从账号注册、实名认证、服务开通，再到密钥创建、额度查看、代码调用，整套流程存在不少容易踩坑的细节。平台为新开通用户提供大额免费Tokens额度，不需要预先充值，就可以完成模型测试、项目原型开发。本文完整梳理整套操作链路，讲解密钥权限、地域接入地址、免费额度规则，附带shell、Python、cURL可直接复制运行的调用示例，同时梳理高频故障排查方案，兼顾个人开发者、小团队的使用场景，帮助使用者快速完成接入，安全可控地使用大模型API服务。详情👉访问阿里云百炼大模型服务平台页面了解。

一、前期账号准备：注册登录与实名认证

想要正常使用百炼平台API能力，账号登录与实名认证是不可跳过的硬性前置条件，未完成实名认证，既不能创建API‑Key，新人免费额度也无法生效。

1.1 账号注册与登录

使用者可以通过手机号、支付宝快捷登录等方式完成账号注册登录。已有账号直接登录即可，不需要重复注册。登录完成之后，才可以进入百炼控制台开展后续操作。

1.2 实名认证操作说明

实名认证分为个人认证与企业认证两类，个人开发者选用个人认证，借助支付宝刷脸就可以快速完成，整个过程耗时很短，不需要绑定银行卡，不需要预先充值就可以领取新人免费资源。
操作路径：登录账号之后，点击页面右上角头像，选择实名认证入口，跟随页面指引完成刷脸核验。

重要提示：未完成实名认证的账号，创建API‑Key按钮处于灰色不可点击状态，免费额度也不会发放，遇到按钮无法点击，优先排查实名认证状态。

二、开通百炼服务与新人免费额度详解

账号实名完成，下一步需要开通百炼大模型服务，开通完成新人免费Tokens额度会自动发放，不需要手动提交申领表单。详情👉访问阿里云百炼大模型服务平台页面了解。

2.1 进入百炼控制台

登录账号之后，在平台顶部搜索框输入“百炼”，选择“大模型服务平台百炼”，跳转进入控制台首页。首次访问会弹出服务开通弹窗。

2.2 开通平台服务

勾选服务使用协议，点击确认开通，整个开通流程免费。开通成功页面自动跳转至百炼主控制台。如果进入控制台没有弹窗，代表该账号此前已经完成开通，直接进行下一步操作。

2.3 新人免费额度完整规则

新用户开通服务之后，系统自动下发新人免费Tokens资源，总额度规模大，覆盖平台七十多款主流模型，每款模型分配对应免费调用额度。

有效期：从开通当日开始计算，有效期90天，无论是否调用都会持续计时，到期未使用完的额度直接失效，不能延期补发。
适用范围：额度仅抵扣实时推理API调用消耗，模型微调、批量异步任务、私有化模型部署等场景，不计入免费抵扣范围。
账号共享规则：主账号与RAM子账号共用同一套免费额度池，子账号消耗额度会统计在主账号名下。
地域限制：新人免费额度仅针对国内华北2（北京）地域生效，新加坡、海外其他地域不享有新人免费福利。

在控制台左侧导航栏找到额度管理菜单，可以查看各个模型剩余免费Tokens、已使用量、到期时间。建议开启“额度用完即停”保护开关，当免费额度全部耗尽之后，自动停止模型调用，避免程序循环调用产生非预期账单。

三、API‑Key创建、权限配置、地域接入地址

API‑Key相当于访问大模型服务的身份密码，所有API请求请求头都携带该凭证，平台校验密钥合法性之后才会返回模型推理结果。创建密钥前，需要确认账号权限、业务空间、地域接入点信息。详情👉访问阿里云百炼大模型服务平台页面了解。

3.1 账号权限说明

主账号：拥有全部权限，可以直接创建API‑Key。
RAM子账号：子账号不能直接创建密钥，需要主账号在RAM控制台授予对应的权限策略，同时在百炼控制台给子账号分配业务空间管理员权限，否则创建按钮置灰无法操作。

3.2 不同地域Base‑URL接入地址

不同地域对应独立接口地址，API‑Key和请求接口地域必须匹配，混用地域会直接返回鉴权401报错，国内业务开发优先选用华北2（北京）地域。

华北2（北京）：https://dashscope.aliyuncs.com/compatible-mode/v1
新加坡地域：https://dashscope‑intl.aliyuncs.com/compatible‑mode/v1
美国弗吉尼亚地域：https://dashscope‑us.aliyuncs.com/compatible‑mode/v1

3.3 创建API‑Key完整步骤

在百炼控制台左侧菜单栏找到API‑Key / 密钥管理页面，进入密钥管理页签。
点击创建API‑Key按钮，弹出配置弹窗。
配置归属业务空间，普通个人开发者直接选择默认业务空间，默认空间生成的密钥可以调用平台全部标准大模型。企业多项目隔离场景，可以新建独立业务空间，做模型访问权限隔离。
权限配置分为全部权限与自定义权限两种模式。
- 个人测试、学习开发场景：直接选择全部权限，配置简单。
- 企业生产环境：选用自定义权限，配置IP访问白名单，仅填写业务服务器公网IP，禁止设置0.0.0.0/0全网放开访问，降低密钥泄露带来的安全风险。
点击确定完成创建，密钥完整字符串只在创建弹窗展示一次，立刻复制保存，关闭弹窗之后无法再次查看完整密钥内容。

运维实践建议：不同业务项目，建议分开创建独立API‑Key。当某一套密钥发生泄露，可以单独删除对应密钥，不会影响其他业务正常运行。

四、多种调用方式实操，可直接复制运行代码

拿到API‑Key以及对应地域Base‑URL之后，可以使用环境变量、Python SDK、cURL命令行、对接第三方AI工具四种方式发起模型调用。强烈建议使用环境变量保存密钥，禁止直接把密钥硬编码写入代码提交到公开代码仓库，防止密钥泄露被盗刷额度。

4.1 环境变量配置方式

Linux/macOS终端配置临时环境变量（当前终端会话生效）

export DASHSCOPE_API_KEY="sk‑xxxx填写你的API‑Key"
export DASHSCOPE_BASE_URL="https://dashscope.aliyuncs.com/compatible‑mode/v1"
export DASHSCOPE_MODEL="qwen3.7‑plus"

Windows Git‑Bash环境变量配置：

set DASHSCOPE_API_KEY=sk‑xxxx填写你的API‑Key
set DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible‑mode/v1
set DASHSCOPE_MODEL=qwen3.7‑plus

如果需要永久保存环境变量，Linux/macOS把上面export语句写入~/.bashrc或者~/.zshrc配置文件，执行source ~/.zshrc生效。Windows系统进入高级系统设置，新增系统环境变量实现永久保存。

4.2 Python代码调用示例（兼容OpenAI客户端）

首先安装openai依赖包

pip install openai python‑dotenv

调用代码示例，优先读取系统环境变量，不硬编码密钥：

import os
from openai import OpenAI

# 初始化客户端，从环境变量读取配置
client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url=os.getenv("DASHSCOPE_BASE_URL")
)

# 发起对话请求
resp = client.chat.completions.create(
    model=os.getenv("DASHSCOPE_MODEL"),
    messages=[
        {
   "role":"system","content":"你是专业技术助手，回答简洁准确"},
        {
   "role":"user","content":"简单介绍API‑Key在大模型调用当中的作用"}
    ],
    max_tokens=1024,
    temperature=0.7
)

# 打印返回结果
print("模型返回结果：")
print(resp.choices[0].message.content)

4.3 cURL命令行直接调用，不需要安装SDK

适合服务器快速验证密钥是否可用，直接在终端执行：

curl -X POST "https://dashscope.aliyuncs.com/compatible‑mode/v1/chat/completions" \
‑H "Authorization: Bearer sk‑xxxx你的API‑Key" \
‑H "Content‑Type: application/json" \
‑d '{
"model":"qwen3.7‑plus",
"messages":[
{"role":"user","content":"测试调用，请输出ok"}
],
"max_tokens":256
}'

请求正常会返回json格式模型输出内容，如果返回401，代表密钥或者接口地址配置存在错误。

4.4 对接第三方AI工具Claude‑Code实操

Hermes Agent、OpenClaw、Claude‑Code这类终端AI智能体，全部兼容OpenAI标准接口，修改对应环境变量即可接入百炼模型服务。

export ANTHROPIC_BASE_URL="https://dashscope.aliyuncs.com/compatible‑mode/v1"
export ANTHROPIC_AUTH_TOKEN="sk‑xxxx你的API‑Key"
export ANTHROPIC_MODEL="qwen3.7‑plus"
# 启动claude‑code工具
claude

启动完成之后，工具就会通过百炼平台完成大模型推理请求。

五、密钥安全管理规范

API‑Key具备调用模型、消耗账户额度的权限，一旦泄露，外部人员可以盗用账号额度，必须做好安全防护。

不要直接写死密钥在源代码，严禁上传到公共代码仓库；优先操作系统环境变量、.env加密配置文件加载密钥。
生产业务环境开启IP白名单，限制只有业务服务器公网IP可以使用该密钥。
按照项目拆分不同API‑Key，当密钥怀疑泄露，直接在控制台删除该密钥，业务更换新密钥，不需要改动其他项目。
定期轮换API‑Key，降低长期使用同一密钥带来的泄露风险。
不要把密钥截图、字符串直接发送至聊天软件、公开论坛。

六、高频问题排查与故障解决方案

6.1 创建API‑Key按钮灰色，无法点击

故障诱因：账号没有完成实名认证，或者RAM子账号没有被授予对应业务空间权限。
处理方案：个人账号完成实名认证；RAM子账号场景，由主账号完成RAM策略授权，并且在百炼控制台分配业务空间管理员权限。

6.2 API调用返回401鉴权失败

排查步骤：

核对API‑Key字符串，确认不存在多余空格换行。
确认请求Base‑URL地域和密钥归属地域保持一致，国内密钥不能填写海外地域接口地址。
如果开启IP白名单，确认发起请求服务器公网IP处于白名单列表内。
确认密钥没有在控制台被手动删除。

6.3 新人免费额度看不到，调用直接产生计费

确认账号实名认证已经完成。
确认选用华北2（北京）地域，海外地域没有新人免费额度。
确认调用的是实时推理接口，调优、批量任务不参与免费抵扣。
进入额度管理页面，查看额度到期时间，确认额度没有已经过期耗尽。

6.4 Tokens额度消耗速度超出预期

大模型输入输出、会话上下文缓存全部会消耗Tokens。长文档问答、多轮持续对话场景，上下文不断累积，会加快额度消耗。
处理办法：业务代码控制单轮输入文档长度；多轮对话定期裁剪过期历史消息；控制台开启额度告警通知，额度到达阈值收到提醒。

6.5 RAM子账号看不到免费额度

主账号和全部RAM子账号共享一套免费额度池，子账号不需要单独领取额度，消耗统一统计在主账号额度池。

七、额度查看与耗尽处理策略

在百炼控制台额度管理页面，可以按模型、时间维度筛选，查看Tokens消耗明细，清晰观察各个业务调用量。

免费额度耗尽之后，实时推理调用就会触发计费。建议提前开启额度告警、用完即停开关，避免程序异常循环调用带来高额账单。
额度耗尽，需要继续使用，可以选购付费资源包，也可以选用Token‑Plan、Coding‑Plan订阅套餐，适配不同业务场景。
日常开发测试，优先选用免费额度；正式上线业务，评估日均调用量，选购对应付费套餐，保障服务稳定性。

八、全文总结

百炼平台提供标准化兼容OpenAI协议的大模型API，个人开发者、小团队只需要完成账号注册、实名认证、开通服务，就可以拿到新人免费Tokens，零成本完成原型开发、模型测试。API‑Key作为身份鉴权凭证，创建的时候注意业务空间、地域、IP白名单权限配置，严格做好密钥安全管理，杜绝密钥泄露风险。

调用层面支持环境变量、Python SDK、cURL命令行，同时可以无缝对接Claude‑Code、Hermes Agent、OpenClaw等第三方AI智能体工具。实际使用中，优先选用环境变量方式加载密钥，不要硬编码密钥到业务代码。遇到鉴权报错、额度异常，优先核对地域、密钥字符串、实名认证状态、IP白名单配置。

企业生产落地的时候，建议按项目拆分独立API‑Key，配置IP访问白名单，开启额度告警和用完即停保护，从权限、监控、密钥轮换多维度，兼顾业务可用性与账号资产安全。整套流程上手门槛低，参考文中的代码示例，就可以快速完成大模型API接入，开展AI应用开发、智能体调试、知识库RAG项目实践。

阿里云百炼API‑Key完整实操指南：账号开通、免费额度领取与多方式调用实战教程与排错全流程手册