零基础玩转阿里云百炼 API：免费 Token 申领、API Key 创建、环境配置和接口调用实操指南-阿里云开发者社区

对于零基础的AI开发者、技术爱好者和小型开发团队来说，低成本、低门槛调用主流大模型接口，是开启AI项目原型开发的必经之路。百炼大模型服务平台汇集了百余款主流大模型，面向新用户提供大规模免费推理额度，不需要预先充值，即可完成文本生成、逻辑推理、代码编写、多模态解析等各类开发验证工作。很多新手在初次接触平台时，常常遇到不清楚免费额度规则、不知道如何生成API‑Key、环境配置错误、调用接口持续报错等一系列问题。本文完整梳理从账号注册、实名认证、免费额度领取、API‑Key创建备份、多操作系统环境变量配置，再到SDK调用、curl命令测试、流式对话开发的完整链路，附带全套可直接复制运行的命令与Python代码，梳理高频报错原因和对应的解决办法，同时讲解API‑Key安全管理规范，帮助开发者零成本完成大模型接口接入，快速开展原型验证、Agent开发、知识库问答等各类AI项目。

一、百炼平台免费额度完整权益与使用规则

百炼面向新开通服务的个人用户提供免费试用权益，完成实名认证之后即可获取千万级Token免费推理额度，有效期90天，覆盖平台绝大多数主流模型，包含千问系列对话模型、代码模型、多模态模型。不同模型的免费额度互相独立，某一个模型的免费额度耗尽之后，不会影响其他模型继续免费调用，开发者修改请求参数更换模型就可以继续使用免费资源。详情👉访问阿里云百炼大模型服务平台页面了解。

免费额度仅用于推理调用场景，不支持模型微调、超高并发批量推理等增值服务，足够满足个人学习、原型调试、小型Demo项目开发。免费额度仅在华北2北京地域生效，其他地域不享受免费权益。

重要扣费优先级规则：接口请求会按照「免费额度>资源包>节省计划>按量付费」顺序依次抵扣。Token Plan、Coding Plan的专属sk‑sp密钥不会消耗免费额度，如果想要使用免费额度，必须使用普通sk‑开头的通用API‑Key。免费额度耗尽，如果账号已经实名认证，会自动切换按量付费模式；希望避免意外扣费，可以在控制台开启“额度用尽即停止调用”开关。

二、账号注册、开通服务以及实名认证前置流程

想要使用免费额度，创建API‑Key，必须完成账号注册、开通百炼服务、个人实名认证三个前置步骤，未实名账号无法使用平台全部接口能力。

账号注册登录：完成账号注册，支持快捷登录方式，个人开发者不需要企业营业执照，个人身份即可开展开发工作。
开通百炼服务：进入百炼控制台，首次访问会弹出服务协议，阅读确认同意，即可开通平台服务；没有弹窗说明账号已经完成开通。
实名认证：进入账号中心完成个人实名认证，填写身份信息，完成核验。全部流程免费，实名完成之后，平台才会解锁免费额度领取、密钥创建、接口调用全部权限，没有实名的账号无法创建API‑Key。

提示：RAM子账号调用接口，还需要主账号分配对应的权限策略，普通个人开发者直接使用主账号即可。

三、免费额度手动核验与领取

完成实名认证之后，部分账号不会自动下发免费额度，需要手动操作领取。进入百炼控制台首页，找到新手资源横幅，点击领取按钮，即可获取90天有效期免费Token。

领取完成后，进入资源中心页面，查看各个模型剩余免费额度、到期时间。开发前建议确认目标模型是否还有剩余免费配额，避免调用失败。

四、API‑Key创建、备份与权限管理

API‑Key是调用大模型接口的鉴权凭证，所有SDK调用、curl请求、第三方Agent工具（OpenClaw、Hermes、Claude Code）都需要传入该凭证。

控制台左侧导航栏打开「密钥管理」页面，这是所有密钥统一管理入口，可以实现密钥创建、查看、作废、删除。
点击右上角创建API‑Key，归属账号选择主账号，业务空间选择默认业务空间。高级需求可以自定义权限，限制密钥可以访问的模型、IP白名单。
完成二次安全校验之后生成密钥。重点提醒：API‑Key只在创建弹窗完整展示一次，关闭弹窗刷新页面之后密钥内容脱敏，无法再次查看完整内容。必须立刻复制保存到记事本或者密码管理器。密钥丢失只能作废旧密钥，重新创建新密钥。

平台支持创建多个API‑Key，建议不同项目、不同开发环境分开使用独立密钥，一旦某个密钥泄露，只需要作废该密钥，不会影响其他业务项目。详情👉访问阿里云百炼大模型服务平台页面了解。

五、本地开发环境安装与环境变量配置

本地开发需要Python3.8以及以上版本，首先校验本地开发环境，打开终端执行下面命令：

#校验Python版本
python --version
#校验pip包管理器版本
pip --version

安装百炼官方dashscope SDK：

pip install dashscope --upgrade

Mac / Linux系统环境变量配置

临时配置，仅当前终端会话生效：

export DASHSCOPE_API_KEY="sk-你的完整APIKey"
#校验是否配置成功
echo $DASHSCOPE_API_KEY

写入zsh配置文件永久生效，重启终端自动加载：

echo "export DASHSCOPE_API_KEY=sk-你的完整APIKey" >> ~/.zshrc
source ~/.zshrc

Windows PowerShell环境变量配置

临时会话配置：

$env:DASHSCOPE_API_KEY="sk-你的完整APIKey"
#校验配置
$env:DASHSCOPE_API_KEY

写入用户环境变量永久保存：

[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY","sk-你的完整APIKey","User")

curl命令行快速测试接口，不需要Python环境

直接在终端发起http请求，快速验证密钥和网络连通性：

curl https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation \
-H "Authorization: Bearer sk-你的完整APIKey" \
-H "Content‑Type:application/json" \
-d '{
"model":"qwen‑turbo",
"input":{"messages":[{"role":"user","content":"简单介绍百炼API‑Key使用注意事项"}]}
}'

六、Python完整代码实战：普通调用、流式输出示例

示例1：普通非阻塞完整对话调用

from http import HTTPStatus
import dashscope
from dashscope import Generation

#优先读取环境变量，也可以直接赋值dashscope.api_key="sk‑xxx"
dashscope.api_key = dashscope.api_key

def normal_chat_demo(user_input: str):
    resp = Generation.call(
        model="qwen‑turbo",
        messages=[
            {
   "role":"system","content":"你是AI开发助手，回答简洁清晰"},
            {
   "role":"user","content":user_input}
        ],
        result_format="message",
        stream=False,
        temperature=0.7
    )
    if resp.status_code == HTTPStatus.OK:
        print("模型返回结果：")
        print(resp.output.choices[0].message.content)
        #打印本次token消耗统计
        print(f"输入token：{resp.usage.input_tokens}，输出token：{resp.usage.output_tokens}")
    else:
        print(f"调用失败，错误码：{resp.code}，错误信息：{resp.message}")

if __name__ == "__main__":
    normal_chat_demo("讲解大模型API开发入门需要注意什么")

示例2：流式输出，适合网页端实时展示回答

import dashscope
from dashscope import Generation

def stream_chat_demo(prompt:str):
    responses = Generation.call(
        model="qwen‑turbo",
        messages=[{
   "role":"user","content":prompt}],
        stream=True,
        incremental_output=True
    )
    for chunk in responses:
        if chunk.status_code == HTTPStatus.OK:
            print(chunk.output.choices[0].message.content,end="")
        else:
            print(f"\n请求异常 {chunk.message}")

if __name__ == "__main__":
    stream_chat_demo("简述API‑Key安全管理要点")

运行脚本命令：

python bailian_api_demo.py

终端可以实时看到模型逐段输出内容，流式模式非常适合做聊天交互页面。

七、常见报错原因以及解决方案

1. 鉴权401报错，密钥失效

常见诱因：密钥复制的时候带入换行、空格字符；密钥已经手动作废；使用Token Plan专属sk‑sp密钥调用普通按量免费额度。
处理方案：重新复制干净完整的sk‑开头通用API‑Key；区分普通密钥和订阅专属密钥；重新创建密钥。

2. 调用返回额度不足报错

原因：该模型免费额度已经全部消耗完毕，不会自动切换其他模型。
处理方案：进入资源中心查看各个模型剩余免费额度，修改代码中model参数切换尚有免费额度的模型；或者开启按量付费继续调用。

3. 实名认证完成，但没有免费额度

原因：开通百炼之后没有手动领取新手资源包；地域选择不是华北2北京地域。
处理方案：切换控制台地域为华北2（北京），进入资源中心手动领取免费额度；重启终端重新加载环境变量。

4. SDK版本过低，接口参数报错

旧版本SDK不兼容新模型参数定义。
解决方案执行升级命令：

pip install dashscope --upgrade

5. curl请求返回连接超时

检查本机网络，确认可以访问dashscope域名；排查防火墙、代理工具干扰。

八、API‑Key安全使用管理规范

禁止把完整API‑Key硬编码写进源代码，严禁提交到公开代码仓库、论坛、社交平台，密钥泄露会造成额度被盗刷，产生意料之外的消耗。优先使用系统环境变量注入密钥。
区分开发环境、生产环境，两套环境使用不同的API‑Key。本地调试使用测试密钥，线上业务使用独立生产密钥。
定期进入密钥管理页面查看调用日志，如果发现陌生异常调用记录，立刻作废泄露的密钥，重新生成新密钥。
长期不再使用的密钥，手动作废关闭，降低安全风险。
如果开启按量付费，建议设置消费告警阈值，当消耗达到阈值接收提醒，避免程序死循环造成大量消耗。

九、拓展：第三方AI工具接入

拿到普通sk‑开头API‑Key以及兼容接口地址https://dashscope.aliyuncs.com/compatible‑mode/v1，可以接入大量遵循OpenAI协议的第三方工具，OpenClaw、Hermes Agent、Claude Code、Cursor等，填入接口地址和密钥即可，免费额度会自动抵扣调用消耗。

注意：如果使用Token Plan订阅，则要使用sk‑sp开头专属密钥和对应的专属接口地址，二者不能混用。

总结

百炼平台的免费试用权益，为零基础开发者提供了零成本学习大模型API开发的通道。完整接入链路分为账号实名、领取免费额度、创建备份API‑Key、配置本地环境、编写调用代码几个关键步骤。详情👉访问阿里云百炼大模型服务平台页面了解。

开发者要分清普通API‑Key和Token Plan专属密钥的差异，普通sk‑开头密钥才可以消耗免费额度；API‑Key只生成时完整展示一次，务必要及时备份。开发过程优先使用环境变量保存密钥，杜绝明文硬编码，做好密钥安全防护。遇到报错优先排查密钥完整性、模型免费额度余量、SDK版本、地域配置。

完成基础API调用之后，开发者就可以基于平台能力，开展对话机器人、文档知识库RAG、代码助手、AI智能体等各类原型项目，积累大模型接口开发实战经验，为后续正式业务落地打下基础。

零基础玩转阿里云百炼 API：免费 Token 申领、API Key 创建、环境配置和接口调用实操指南