调用阿里云百炼 API：从开通服务到发送第一个请求

阿里云百炼是阿里云的大模型服务平台，把通义千问、DeepSeek 等模型集中在一个入口下，通过统一的 HTTP 接口对外提供调用能力。开发者拿到 API Key 之后，用一次 POST 请求就能把模型能力接进自己的应用，不需要自己部署模型，也不需要处理推理环境的运维。这篇教程面向第一次接入百炼的开发者，把从账号准备到发出第一个请求、再到把调用落到本地代码里的完整路径讲清楚。如果你习惯用图形化的接口调试工具来验证请求，可以参考阿里云百炼这一条目，本文的步骤与它配合使用即可。

整条链路可以拆成三件事：账号与服务开通、API Key 的生成、请求的构造与调试。三件事各自独立，任何一步没做对，后面的调用都会失败，所以下面按顺序展开，每一步都给出可执行的命令或参数。

准备工作

账号与实名认证

调用百炼的前提是一个可用的阿里云账号。注册并登录阿里云之后，在站内搜索「大模型服务平台百炼」，从搜索结果进入平台首页。首次进入时页面通常会提供「免费体验」入口，按引导走完开通流程即可；如果该活动已经结束，直接从「模型广场」选择要用的模型进入详情页，同样可以完成后续操作。

部分账号在领取免费额度时会提示未完成实名认证。这时回到阿里云首页，点击右上角的「账号中心」，进入「实名认证」页面，按提示完成个人认证。认证流程需要提交身份信息，完成后回到百炼继续开通即可。免费额度的具体额度、有效期和适用模型会随活动调整，实际以百炼控制台「模型广场」中对应模型页面显示的当前信息为准。

确认模型与免费额度

在「模型广场」里可以看到平台提供的模型清单，点开任意一个模型，就能看到该模型的说明、可用接口以及当前的免费额度情况。这一步值得花几分钟：不同模型的调用地址、请求字段和计费方式可能不同，先确认自己要用的模型名称，后面写请求时 model 字段要填的就是它。

创建 API Key

API Key 是调用模型的身份凭证，所有请求都要在请求头里带上它。生成路径有两处入口，取决于你看到的界面版本：

旧版界面：点击页面右上角的头像图标，在下拉菜单中选择「API-KEY」。
新版界面：直接点击左侧导航栏中的「API-Key」。

进入 API-KEY 管理页面后，点击「创建」按钮生成一个新的 Key。生成后请立即复制并妥善保存，把它当作密码对待：不要写进前端代码，不要提交到公开仓库，泄露后应在控制台及时删除并重建。一个账号可以创建多个 Key，按项目或环境区分有助于后续排查问题。

调试工具

验证请求最省事的方式是用一个支持 HTTP 请求的工具，把 cURL 粘进去直接发。这类工具通常会自动解析 cURL 中的方法、URL、请求头和请求体，省去逐项填写。你也可以直接用终端里的 curl，或者用 Python、JavaScript 写脚本，效果一致。

操作步骤

第一步：拿到模型的调用示例

不要凭记忆拼请求体。打开你要用的模型详情页，点击「API 参考」，定位到 HTTP 部分，页面会给出该模型的请求示例，包括请求地址、请求头和请求体结构。以这个示例为起点，再按需增删字段或修改参数值，是最不容易出错的做法。

下面是一个典型的请求示例，以 DeepSeek-V3 为例：

curl -X POST \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "9.9和9.11谁大"
      }
    ]
  }'

这段请求里有四个关键点：

请求方法：POST，模型调用都是提交数据，不是查询。
Authorization 头：格式为 Bearer 加一个空格再加 API Key。示例里的 $DASHSCOPE_API_KEY 是环境变量占位符，实际发送前必须替换成你自己的 Key。
Content-Type 头：固定为 application/json，请求体是 JSON。
请求体：model 指定模型，messages 是对话消息数组，每条消息包含 role 和 content；stream 控制是否以流式方式返回。

第二步：替换 API Key

如果你用的是图形化调试工具，把上面的 cURL 粘贴到地址栏后，工具会自动把请求头拆到 Headers 选项卡里。此时找到 Authorization 这一行，把 $DASHSCOPE_API_KEY 整体替换成你刚才创建的 Key，注意保留前面的 Bearer 前缀和中间的空格。

如果直接在终端里执行，可以先导出环境变量，再让 cURL 引用它，这样 Key 不会出现在命令历史里：

export DASHSCOPE_API_KEY="你的 API Key"

导出之后再执行上面的 cURL 命令，$DASHSCOPE_API_KEY 会被自动展开。

第三步：发送请求并读取响应

点击发送（或在终端回车）后，模型会返回生成结果。如果报错，第一件要检查的事就是 API Key 是否填写正确、是否带了 Bearer 前缀、是否有多余的空格或换行。

示例中 stream 设为 true，服务端会以 SSE（Server-Sent Events）格式逐条推送数据。图形化调试工具通常会自动把分条数据合并成一段完整结果展示；如果想看原始的分条数据，切换到「分条展示」视图即可。用 cURL 在终端里执行时，你会直接看到一条条 data: 开头的行，需要自己拼接。

第四步：切换到其他模型

换模型的方式很简单：把请求体里的 model 字段改成目标模型的名称即可，请求地址和鉴权方式通常保持不变。例如把 deepseek-v3 换成 deepseek-r1-distill-qwen-1.5b，就切换到了另一个模型。不同模型支持的参数可能不完全一致，切换后如果报参数错误，回到该模型的「API 参考」页面对照字段说明调整。

第五步：把调用落到本地代码

在调试工具里验证通过之后，可以把这次请求保存为接口，再通过「生成接口请求代码」功能导出 Python 或 JavaScript 代码，复制到本地运行。导出代码只是骨架，运行前需要先安装代码里 import 的库，缺什么装什么。本地运行时同样要把 API Key 通过环境变量注入，不要硬编码在源码里。

一个完整示例

下面把前面的步骤串成一个可以照着跑的最小流程。假设你已经完成实名认证并开通了百炼，目标是用 DeepSeek-V3 问一个问题并拿到回答。

1. 创建并保存 API Key。进入百炼控制台的 API-KEY 管理页面，点击「创建」，复制生成的 Key。

2. 在终端里设置环境变量。

export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxx"

3. 发送请求。把模型详情页「API 参考」中的 HTTP 示例复制出来，确认 model 字段与你要用的模型一致，然后执行：

curl -X POST \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "9.9和9.11谁大"
      }
    ]
  }'

4. 观察输出。终端会陆续打印以 data: 开头的行，每行是一段增量内容，最后以表示结束的标记收尾。把这些行的内容按顺序拼接，就是完整的回答。

5. 改成非流式再试一次。把 stream 改为 false，重新发送。此时服务端一次性返回完整结果，响应体是一个 JSON 对象，比逐条拼接更容易解析。调试阶段建议先用非流式确认请求结构和鉴权都没问题，再切回流式处理增量输出。

6. 换一个模型验证通用性。把 model 改成 deepseek-r1-distill-qwen-1.5b，其余不变，再发一次。如果能正常返回，说明你的鉴权、请求结构和解析逻辑都是通用的，后续接入其他模型只需要改这一个字段。

注意事项

免费额度会变。新用户额度、适用模型和有效期都属于活动性质，会随平台政策调整。调用前在「模型广场」对应模型页面确认当前额度，不要按旧文章里的数字做容量规划。
API Key 是敏感信息。不要写进前端代码或提交到版本库。怀疑泄露时，在控制台删除旧 Key 并重新创建。
鉴权失败优先查格式。最常见的错误是漏了 Bearer 前缀、Key 前后带了空格、或者把占位符 $DASHSCOPE_API_KEY 原样发了出去。
模型名称要精确。model 字段填错会直接报错，名称以模型详情页显示为准，不要自己缩写或猜测。
流式与非流式的解析方式不同。stream: true 返回 SSE 分条数据，需要按行解析并拼接；stream: false 返回单个 JSON 对象。两种模式的客户端处理逻辑不能混用。
不同模型的参数支持范围不同。换模型后如果出现参数校验错误，回到该模型的「API 参考」核对可用字段，不要沿用上一个模型的全部参数。
计费与配额以控制台为准。免费额度用尽后的计费方式、各模型的单价和限流策略都会调整，正式接入前请在百炼控制台查看当前说明。