阿里云 API 教程：百炼大模型

阿里云百炼（Bailian）是阿里云的大模型服务平台，DashScope 是其 API 接入层。开发者通过 DashScope 可以调用千问系列、DeepSeek、Kimi、GLM、MiniMax 等多种大模型，将 AI 能力集成到自己的应用中。

DashScope 支持 OpenAI 兼容接口，这意味着原本调用 OpenAI GPT 系列的代码，只需修改 Base URL 和 API Key 两个参数，就能直接切换到阿里云百炼的模型，不需要重写业务逻辑。这对于已有 OpenAI 集成的项目来说，迁移成本极低。

阿里云百炼 API 是什么

DashScope 本质上是一个模型推理 API 网关，统一了阿里云平台上所有可调用模型的接入方式。用户只需要一个 API Key，就可以通过同一套接口访问千问商业版、千问开源版（Qwen3、QwQ）、以及平台上部署的第三方模型。

和直接使用 AI 产品网页端相比，API 接入的价值在于：可以将 AI 能力嵌入自己的产品，实现自动化调用、批量处理、以及和业务系统的深度集成。比如自动化内容生成、智能客服后端、代码辅助工具等场景，都需要通过 API 而不是网页端实现。

DashScope 与 OpenAI API 的接口格式高度兼容，chat/completions 端点、messages 格式、temperature、max_tokens 等参数命名都相同，降低了从 OpenAI 生态迁移过来的学习成本。

API Key 获取与管理

开通百炼并创建 API Key

使用阿里云主账号登录百炼大模型服务平台（bailian.console.aliyun.com），阅读协议后完成开通。首次开通会自动发放新人免费额度，有效期为开通后 90 天，可用于各模型的测试调用。

建议在开通后立即完成两项设置：开启免费额度用完即停，避免免费额度耗尽后自动进入付费模式产生预期外费用；设置消费限额，指定每月最高消费金额，防止因代码 bug 或异常循环调用造成账单暴增。

API Key 的获取路径：百炼控制台 → 密钥管理 → 创建 API Key。一个账号可以创建多个 API Key，建议按项目分别创建，便于独立追踪用量和控制权限。

地域选择与 Base URL 对应关系

百炼 API 有三个地域接入点，API Key 和 Base URL 必须严格对应同一地域，混用会直接触发 401 鉴权错误：

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

地域选择会影响调用延迟和可用模型范围。第三方模型（DeepSeek、Kimi、GLM、MiniMax 等）目前仅支持北京地域，调用这些模型必须使用北京地域的 Base URL 和对应 API Key，切换到新加坡或美国地域会报模型不可用。关于 OpenClaw 工具接入百炼时的地域配置方式，可以参考OpenClaw 阿里云部署教程：轻量服务器安装、百炼模型接入与计费方式。

API Key 的安全管理规范

API Key 一旦泄露，攻击者可以用你的账号调用模型，产生费用由账号所有者承担。以下是必须遵守的基本规范：

• 不把 API Key 硬写在代码里，尤其不能提交到 GitHub 或其他公开仓库
• 通过环境变量传递 Key：export DASHSCOPE_API_KEY=”your-api-key”，代码中用 os.getenv(“DASHSCOPE_API_KEY”) 读取
• 不同项目使用不同的 API Key，一旦某个项目的 Key 泄露，可以单独删除该 Key 而不影响其他项目
• 定期检查控制台的调用记录，发现异常用量立即禁用对应 Key 并重新创建

实际调用方式

用 curl 直接调用

curl 是最快的验证方式，不需要安装任何 SDK，适合快速确认 API Key 和配置是否正确：

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \

  -H “Authorization: Bearer $DASHSCOPE_API_KEY” \

  -H “Content-Type: application/json” \

  -d ‘{

    “model”: “qwen-plus”,

    “messages”: [

      {“role”: “system”, “content”: “你是一个专业的技术顾问”},

      {“role”: “user”, “content”: “用一句话介绍阿里云百炼”}

    ],

    “max_tokens”: 200,

    “temperature”: 0.7

  }’

返回的 JSON 中，choices[0].message.content 是模型回复的正文，usage 字段包含本次调用消耗的输入和输出 Token 数量，可以用来估算单次调用费用。

用 Python SDK 调用

百炼支持 OpenAI 兼容接口，可以直接使用 Python 的 openai 库，无需安装阿里云专用 SDK：

from openai import OpenAI

import os

client = OpenAI(

    api_key=os.getenv(“DASHSCOPE_API_KEY”),

    base_url=”https://dashscope.aliyuncs.com/compatible-mode/v1″

)

response = client.chat.completions.create(

    model=”qwen-plus”,

    messages=[

        {“role”: “system”, “content”: “你是一个专业的技术顾问”},

        {“role”: “user”, “content”: “用一句话介绍阿里云百炼”}

    ],

    max_tokens=200,

    temperature=0.7

)

print(response.choices[0].message.content)

print(f”Token 用量：输入 {response.usage.prompt_tokens}，输出 {response.usage.completion_tokens}”)

与调用 OpenAI GPT 的代码相比，只有 api_key 和 base_url 两个参数不同，其余结构完全一致。现有的 OpenAI 集成项目切换到百炼，改动量极小。

如果需要流式输出（逐步返回结果，适合聊天界面），在请求中加入 stream=True：

stream = client.chat.completions.create(

    model=”qwen-plus”,

    messages=[{“role”: “user”, “content”: “介绍一下阿里云百炼平台”}],

    stream=True

)

for chunk in stream:

    if chunk.choices[0].delta.content is not None:

        print(chunk.choices[0].delta.content, end=””, flush=True)

模型选择与常用参数说明

主流模型对比与选型

模型	特点	适合场景	价格级别
qwen-turbo	响应最快，价格最低	简单问答、高频批量调用、实时性要求高	最低
qwen-plus	速度与质量平衡，性价比高	日常对话、内容生成、通用任务	中等
qwen-max	能力最强，价格最高	复杂推理、长文本处理、高质量写作	最高
qwen-coder-plus	针对代码场景优化	代码生成、调试、解释、重构	中等
qwq-plus	深度推理，擅长逐步思考	数学题、逻辑推理、多步骤分析	中等偏高
deepseek-v3	第三方，综合能力强	通用任务，和千问互为补充（仅北京地域）	按量计费

以上为参考定位，实际价格以百炼控制台当期报价为准。

日常使用 qwen-plus 是最合理的起点，响应速度和输出质量在大多数场景下都足够，且成本可控。代码生成场景切换到 qwen-coder-plus，需要深度推理的任务考虑 qwq-plus 或 deepseek-v3。qwen-max 适合对质量要求极高、预算充裕的场景，不建议作为默认模型。

常用参数的判断逻辑

参数设置直接影响输出质量和成本，以下几个参数最常用：

• temperature（0–1）： 控制输出随机性，越低越确定；代码生成、结构化数据提取建议 0.1–0.3；创意写作、头脑风暴建议 0.7–0.9；默认 1.0 通常偏高，实际使用应根据场景调整
• max_tokens： 限制单次响应的最大 Token 数，建议根据预期输出长度设置合理上限，避免意外超长输出产生高额费用；简短回复设为 200–500，长文本生成可设为 2000–4000
• stream（true/false）： 是否启用流式输出，聊天界面场景建议启用，用户看到逐字出现的效果体验更好；批量处理场景不需要开启
• top_p： 另一种控制输出多样性的参数，通常和 temperature 二选一调整，不建议同时修改两个参数

计费方式与成本控制

Token 计费的基本逻辑

百炼按实际消耗的 Token 计费，输入 Token 和输出 Token 分开计价，且输出 Token 的单价通常高于输入 Token。不同模型的单价差异较大，qwen-turbo 是 qwen-max 价格的几分之一。

简单的用量参考：中文约 1000 个汉字对应 1500–2000 Token，英文约 750 个词对应 1000 Token。一次完整的对话调用（含上下文历史），随着对话轮数增加，输入 Token 会累积增长，成本也随之上升。生产环境中应注意控制对话历史的长度，避免无限积累上下文。

每次 API 调用结束后，响应中的 usage 字段会返回本次的输入和输出 Token 数，建议在日志中记录，便于后续成本分析。

Coding Plan 与按量付费的选择

计费模式	计费方式	月度上限	超出处理	适合场景
按量付费	按实际 Token 用量	无上限	继续计费	用量低或不稳定
Coding Plan	固定月费	最多 90,000 次请求	报错，不额外计费	高频使用，需要固定成本

Coding Plan 适合以下几种情况：

• 每天固定调用次数，需要预测和控制月度 AI 费用
• 接入 AI 助手工具（如 OpenClaw）做日常编程辅助，调用频率稳定
• 希望彻底规避账单超预期的风险，超出额度后宁可报错也不继续计费

按量付费适合调用量极低的测试场景，或者月均调用量超过 90,000 次的高频生产场景（此时 Coding Plan 的次数上限反而是瓶颈，按量付费更划算）。

常见报错与排查

401 Unauthorized（鉴权失败）

401 是最常见的报错，通常由以下原因导致：

• API Key 复制时混入了空格或换行符，重新从控制台复制并检查是否完整
• API Key 和 Base URL 地域不对应，北京的 Key 不能配新加坡的 URL，反之亦然
• API Key 已被手动删除或设为禁用状态，在控制台密钥管理页面确认当前状态
• 调用第三方模型（DeepSeek、Kimi 等）时使用了非北京地域的 Base URL

模型名称不存在或不可用

• 模型名称严格区分大小写，qwen-plus 不能写成 Qwen-Plus 或 QWEN-PLUS
• Coding Plan 仅支持特定模型列表，调用不在列表中的模型会返回模型不可用，需要切换到按量付费或选择受支持的模型
• 第三方模型需要在百炼控制台单独开通对应厂商的服务权限，未开通时调用会报模型不可用

超出配额或余额不足

• 新人免费额度用完后，如果账户余额为零或未开通付费模式，API 调用会报余额不足错误
• Coding Plan 每月额度（90,000 次）用完后，当月所有调用都会报错，直到下月额度自动重置
• 处理方法：在百炼控制台充值账户余额，确认消费限额设置不为零，或等待 Coding Plan 下月额度重置

阿里云百炼账号开通与充值

使用百炼 API 需要有效的阿里云账号。阿里云国际版账号可以在官网直接注册，但涉及跨境支付时，部分用户在绑卡或充值环节会遇到障碍。对于需要 USDT、支付宝或对公转账充值的团队，可以通过阿里云国际代理协助完成账号开通和充值续费，支持多种灵活支付方式，免去信用卡限制。长期使用百炼 API 的项目，稳定的充值渠道和账单管理同样重要。

阿里云代理

阿里云百炼（Bailian）是阿里云的大模型服务平台，DashScope 是其 API 接入层。开发者通过 DashScope 可以调用千问系列、DeepSeek、Kimi、GLM、MiniMax 等多种大模型，将 AI 能力集成到自己的应用中。

DashScope 支持 OpenAI 兼容接口，这意味着原本调用 OpenAI GPT 系列的代码，只需修改 Base URL 和 API Key 两个参数，就能直接切换到阿里云百炼的模型，不需要重写业务逻辑。这对于已有 OpenAI 集成的项目来说，迁移成本极低。

阿里云百炼 API 是什么

DashScope 本质上是一个模型推理 API 网关，统一了阿里云平台上所有可调用模型的接入方式。用户只需要一个 API Key，就可以通过同一套接口访问千问商业版、千问开源版（Qwen3、QwQ）、以及平台上部署的第三方模型。

和直接使用 AI 产品网页端相比，API 接入的价值在于：可以将 AI 能力嵌入自己的产品，实现自动化调用、批量处理、以及和业务系统的深度集成。比如自动化内容生成、智能客服后端、代码辅助工具等场景，都需要通过 API 而不是网页端实现。

DashScope 与 OpenAI API 的接口格式高度兼容，chat/completions 端点、messages 格式、temperature、max_tokens 等参数命名都相同，降低了从 OpenAI 生态迁移过来的学习成本。

API Key 获取与管理

开通百炼并创建 API Key

使用阿里云主账号登录百炼大模型服务平台（bailian.console.aliyun.com），阅读协议后完成开通。首次开通会自动发放新人免费额度，有效期为开通后 90 天，可用于各模型的测试调用。

建议在开通后立即完成两项设置：开启免费额度用完即停，避免免费额度耗尽后自动进入付费模式产生预期外费用；设置消费限额，指定每月最高消费金额，防止因代码 bug 或异常循环调用造成账单暴增。

API Key 的获取路径：百炼控制台 → 密钥管理 → 创建 API Key。一个账号可以创建多个 API Key，建议按项目分别创建，便于独立追踪用量和控制权限。

地域选择与 Base URL 对应关系

百炼 API 有三个地域接入点，API Key 和 Base URL 必须严格对应同一地域，混用会直接触发 401 鉴权错误：

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

地域选择会影响调用延迟和可用模型范围。第三方模型（DeepSeek、Kimi、GLM、MiniMax 等）目前仅支持北京地域，调用这些模型必须使用北京地域的 Base URL 和对应 API Key，切换到新加坡或美国地域会报模型不可用。关于 OpenClaw 工具接入百炼时的地域配置方式，可以参考 OpenClaw 阿里云部署教程 。

OpenClaw 阿里云部署教程：轻量服务器安装、百炼模型接入与计费方式

API Key 的安全管理规范

API Key 一旦泄露，攻击者可以用你的账号调用模型，产生费用由账号所有者承担。以下是必须遵守的基本规范：

• 不把 API Key 硬写在代码里，尤其不能提交到 GitHub 或其他公开仓库
• 通过环境变量传递 Key：export DASHSCOPE_API_KEY=”your-api-key”，代码中用 os.getenv(“DASHSCOPE_API_KEY”) 读取
• 不同项目使用不同的 API Key，一旦某个项目的 Key 泄露，可以单独删除该 Key 而不影响其他项目
• 定期检查控制台的调用记录，发现异常用量立即禁用对应 Key 并重新创建

实际调用方式

用 curl 直接调用

curl 是最快的验证方式，不需要安装任何 SDK，适合快速确认 API Key 和配置是否正确：

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \

  -H “Authorization: Bearer $DASHSCOPE_API_KEY” \

  -H “Content-Type: application/json” \

  -d ‘{

    “model”: “qwen-plus”,

    “messages”: [

      {“role”: “system”, “content”: “你是一个专业的技术顾问”},

      {“role”: “user”, “content”: “用一句话介绍阿里云百炼”}

    ],

    “max_tokens”: 200,

    “temperature”: 0.7

  }’

返回的 JSON 中，choices[0].message.content 是模型回复的正文，usage 字段包含本次调用消耗的输入和输出 Token 数量，可以用来估算单次调用费用。

用 Python SDK 调用

百炼支持 OpenAI 兼容接口，可以直接使用 Python 的 openai 库，无需安装阿里云专用 SDK：

from openai import OpenAI

import os

client = OpenAI(

    api_key=os.getenv(“DASHSCOPE_API_KEY”),

    base_url=”https://dashscope.aliyuncs.com/compatible-mode/v1″

)

response = client.chat.completions.create(

    model=”qwen-plus”,

    messages=[

        {“role”: “system”, “content”: “你是一个专业的技术顾问”},

        {“role”: “user”, “content”: “用一句话介绍阿里云百炼”}

    ],

    max_tokens=200,

    temperature=0.7

)

print(response.choices[0].message.content)

print(f”Token 用量：输入 {response.usage.prompt_tokens}，输出 {response.usage.completion_tokens}”)

与调用 OpenAI GPT 的代码相比，只有 api_key 和 base_url 两个参数不同，其余结构完全一致。现有的 OpenAI 集成项目切换到百炼，改动量极小。

如果需要流式输出（逐步返回结果，适合聊天界面），在请求中加入 stream=True：

stream = client.chat.completions.create(

    model=”qwen-plus”,

    messages=[{“role”: “user”, “content”: “介绍一下阿里云百炼平台”}],

    stream=True

)

for chunk in stream:

    if chunk.choices[0].delta.content is not None:

        print(chunk.choices[0].delta.content, end=””, flush=True)

模型选择与常用参数说明

主流模型对比与选型

模型	特点	适合场景	价格级别
qwen-turbo	响应最快，价格最低	简单问答、高频批量调用、实时性要求高	最低
qwen-plus	速度与质量平衡，性价比高	日常对话、内容生成、通用任务	中等
qwen-max	能力最强，价格最高	复杂推理、长文本处理、高质量写作	最高
qwen-coder-plus	针对代码场景优化	代码生成、调试、解释、重构	中等
qwq-plus	深度推理，擅长逐步思考	数学题、逻辑推理、多步骤分析	中等偏高
deepseek-v3	第三方，综合能力强	通用任务，和千问互为补充（仅北京地域）	按量计费

以上为参考定位，实际价格以百炼控制台当期报价为准。

日常使用 qwen-plus 是最合理的起点，响应速度和输出质量在大多数场景下都足够，且成本可控。代码生成场景切换到 qwen-coder-plus，需要深度推理的任务考虑 qwq-plus 或 deepseek-v3。qwen-max 适合对质量要求极高、预算充裕的场景，不建议作为默认模型。

常用参数的判断逻辑

参数设置直接影响输出质量和成本，以下几个参数最常用：

• temperature（0–1）： 控制输出随机性，越低越确定；代码生成、结构化数据提取建议 0.1–0.3；创意写作、头脑风暴建议 0.7–0.9；默认 1.0 通常偏高，实际使用应根据场景调整
• max_tokens： 限制单次响应的最大 Token 数，建议根据预期输出长度设置合理上限，避免意外超长输出产生高额费用；简短回复设为 200–500，长文本生成可设为 2000–4000
• stream（true/false）： 是否启用流式输出，聊天界面场景建议启用，用户看到逐字出现的效果体验更好；批量处理场景不需要开启
• top_p： 另一种控制输出多样性的参数，通常和 temperature 二选一调整，不建议同时修改两个参数

计费方式与成本控制

Token 计费的基本逻辑

百炼按实际消耗的 Token 计费，输入 Token 和输出 Token 分开计价，且输出 Token 的单价通常高于输入 Token。不同模型的单价差异较大，qwen-turbo 是 qwen-max 价格的几分之一。

简单的用量参考：中文约 1000 个汉字对应 1500–2000 Token，英文约 750 个词对应 1000 Token。一次完整的对话调用（含上下文历史），随着对话轮数增加，输入 Token 会累积增长，成本也随之上升。生产环境中应注意控制对话历史的长度，避免无限积累上下文。

每次 API 调用结束后，响应中的 usage 字段会返回本次的输入和输出 Token 数，建议在日志中记录，便于后续成本分析。

Coding Plan 与按量付费的选择

计费模式	计费方式	月度上限	超出处理	适合场景
按量付费	按实际 Token 用量	无上限	继续计费	用量低或不稳定
Coding Plan	固定月费	最多 90,000 次请求	报错，不额外计费	高频使用，需要固定成本

Coding Plan 适合以下几种情况：

• 每天固定调用次数，需要预测和控制月度 AI 费用
• 接入 AI 助手工具（如 OpenClaw）做日常编程辅助，调用频率稳定
• 希望彻底规避账单超预期的风险，超出额度后宁可报错也不继续计费

按量付费适合调用量极低的测试场景，或者月均调用量超过 90,000 次的高频生产场景（此时 Coding Plan 的次数上限反而是瓶颈，按量付费更划算）。

常见报错与排查

401 Unauthorized（鉴权失败）

401 是最常见的报错，通常由以下原因导致：

• API Key 复制时混入了空格或换行符，重新从控制台复制并检查是否完整
• API Key 和 Base URL 地域不对应，北京的 Key 不能配新加坡的 URL，反之亦然
• API Key 已被手动删除或设为禁用状态，在控制台密钥管理页面确认当前状态
• 调用第三方模型（DeepSeek、Kimi 等）时使用了非北京地域的 Base URL

模型名称不存在或不可用

• 模型名称严格区分大小写，qwen-plus 不能写成 Qwen-Plus 或 QWEN-PLUS
• Coding Plan 仅支持特定模型列表，调用不在列表中的模型会返回模型不可用，需要切换到按量付费或选择受支持的模型
• 第三方模型需要在百炼控制台单独开通对应厂商的服务权限，未开通时调用会报模型不可用

超出配额或余额不足

• 新人免费额度用完后，如果账户余额为零或未开通付费模式，API 调用会报余额不足错误
• Coding Plan 每月额度（90,000 次）用完后，当月所有调用都会报错，直到下月额度自动重置
• 处理方法：在百炼控制台充值账户余额，确认消费限额设置不为零，或等待 Coding Plan 下月额度重置

阿里云百炼账号开通与充值

使用百炼 API 需要有效的阿里云账号。阿里云国际版账号可以在官网直接注册，但涉及跨境支付时，部分用户在绑卡或充值环节会遇到障碍。对于需要 USDT、支付宝或对公转账充值的团队，可以通过阿里云国际代理协助完成账号开通和充值续费，支持多种灵活支付方式，免去信用卡限制。长期使用百炼 API 的项目，稳定的充值渠道和账单管理同样重要。

阿里云代理