通义千问（千问大模型）API调用完整教程：从注册到第一次成功调用

很多用户搜索「通义千问」，这里先说明一下：通义千问现已更名为千问大模型，但API能力和使用方式完全一致，且持续迭代升级。本文将以最新的千问大模型（Qwen3.8-Max等版本）为例，带你从零开始完成第一次API调用。

无论你是刚接触大模型API的新手，还是从其他平台迁移过来的开发者，这篇教程都能帮你快速跑通整个流程。全文包含注册开通、获取API Key、代码调用、常见报错处理四个步骤，跟着操作即可成功。

一、注册与开通：获取API使用资格

1.1 注册阿里云账号

1. 访问阿里云官网https://www.aliyun.com/，点击「免费注册」
2. 使用手机号完成注册
3. 完成实名认证（个人用户需身份证认证，企业用户建议完成企业认证以获取更多权益）

注意：实名认证是调用API的前提条件，未认证账号无法获取API Key。

1.2 开通百炼平台

千问大模型（原通义千问）的API通过阿里云百炼平台提供。开通步骤如下：

1. 访问百炼控制台https://bailian.console.aliyun.com/
2. 使用阿里云账号登录
3. 首次进入会提示开通百炼服务，点击「立即开通」
4. 阅读并同意服务协议，确认开通

开通百炼平台本身是免费的，API调用按Token消耗量计费。

1.3 获取API Key

1. 在百炼控制台右上角点击账号头像，进入「API-KEY管理」
2. 点击「创建新的API Key」
3. 为API Key设置一个备注名称（如「测试环境」）
4. 创建成功后，立即复制保存API Key（页面关闭后将无法再次查看完整Key）

安全提醒：API Key具有账号级别的操作权限，请勿将其提交到公开代码仓库或分享给他人。建议在代码中使用环境变量存储API Key。

二、环境准备：安装SDK

千问大模型的API完全兼容OpenAI SDK格式，这意味着如果你之前用过OpenAI，几乎可以无缝切换。

2.1 Python环境

# 安装OpenAI SDK
pip install openai
# 建议使用虚拟环境
python -m venv qwen-env
source qwen-env/bin/activate  # macOS/Linux
qwen-env\Scripts\activate     # Windows

2.2 Node.js环境

# 安装OpenAI SDK
npm install openai

2.3 其他语言

千问大模型API基于HTTP协议，任何支持HTTP请求的编程语言都可以调用。官方文档提供了Python、Java、Node.js、Go、C#等语言的SDK示例。

如果你正在从OpenAI迁移到千问大模型，详细的迁移指南请参考OpenAI迁移指南https://help.aliyun.com/zh/model-studio/openai-migration。

三、第一次API调用

3.1 Python完整代码示例

以下是一个可以直接运行的Python示例，调用千问大模型进行对话：

import os
from openai import OpenAI
# 建议使用环境变量存储API Key
# export DASHSCOPE_API_KEY="your-api-key"
client = OpenAI(
    api_key=os.environ.get("DASHSCOPE_API_KEY", "your-api-key"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)
# 第一次调用：简单对话
response = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "你是一个友好的AI助手。"},
        {"role": "user", "content": "你好，请简单介绍一下你自己。"}
    ]
)
print("千问大模型回复：", response.choices[0].message.content)

3.2 Node.js完整代码示例

import OpenAI from 'openai';
const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY || 'your-api-key',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
});
async function main() {
    const response = await client.chat.completions.create({
        model: 'qwen-plus',
        messages: [
            { role: 'system', content: '你是一个友好的AI助手。' },
            { role: 'user', content: '你好，请简单介绍一下你自己。' }
        ]
    });
    console.log('千问大模型回复：', response.choices[0].message.content);
}
main();

3.3 使用cURL直接调用

如果你不想安装SDK，也可以直接用cURL测试API：

curl -X POST "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-plus",
    "messages": [
      {"role": "system", "content": "你是一个友好的AI助手。"},
      {"role": "user", "content": "你好！"}
    ]
  }'

3.4 运行结果

如果调用成功，你将看到类似以下的输出：

千问大模型回复：你好！我是千问大模型，由阿里云开发的AI语言模型。我可以帮你回答问题、撰写文案、编写代码、分析数据等。有什么我可以帮你的吗？

恭喜你，第一次API调用成功！

四、选择模型版本

千问大模型（原通义千问）目前提供多个版本，适用于不同场景：

关于各版本的详细对比，请参考百炼大模型对比选型指南https://help.aliyun.com/zh/model-studio/model-comparison。

新手建议：首次调用推荐使用Qwen-Plus，它在性能和成本之间取得了最佳平衡。如果你的场景涉及复杂推理或专业分析，可以切换到Qwen3.8-Max。

五、进阶用法

5.1 多轮对话

千问大模型支持多轮对话，只需将历史消息一并传入：

messages = [
    {"role": "system", "content": "你是一个专业的Python编程导师。"},
    {"role": "user", "content": "什么是列表推导式？"},
    {"role": "assistant", "content": "列表推导式是Python中...（回答内容）"},
    {"role": "user", "content": "能给个实际例子吗？"}
]

5.2 流式输出

对于需要实时展示生成过程的场景，可以使用流式输出：

response = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "写一首关于春天的诗"}],
    stream=True
)
for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

5.3 调用Qwen3.8-Max

如果你想体验千问大模型最强的版本，只需将model参数改为qwen3.8-max：

response = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "分析量子计算的发展前景"}]
)

详细的Qwen3.8-Max调用方法请参考百炼调用Qwen3.8-Max API教程https://help.aliyun.com/zh/model-studio/qwen-api-tutorial。

六、常见报错与解决方案

在API调用过程中，你可能会遇到一些常见错误。以下是排查指南：

6.1 InvalidApiKey

原因：API Key错误或已失效。

解决：检查API Key是否正确复制，是否有多余的空格。如果确认Key正确但依然报错，可以在百炼控制台重新创建API Key。

6.2 ModelNotFound

原因：模型名称拼写错误或该模型未开通。

解决：确认模型名称正确（如qwen-plus、qwen3.8-max），并在百炼控制台的模型广场确认该模型已开通。

6.3 RateLimitReached

原因：请求频率超过了限制。

解决：降低请求频率，或在百炼控制台申请提升QPS限额。

更多报错及解决方案请参考千问大模型API调用报错FAQhttps://help.aliyun.com/zh/model-studio/api-error-faq。

七、成本控制建议

7.1 按量付费 vs Token Plan

• 按量付费：按实际Token消耗计费，适合初期测试和小规模使用
• Token Plan：预付费方案，享受折扣优惠，适合稳定用量的业务

详细的购买建议请参考阿里云百炼Token Plan购买指南https://help.aliyun.com/zh/model-studio/token-plan。

7.2 降低Token消耗的技巧

• 精简system prompt，避免不必要的上下文
• 合理设置max_tokens参数，避免生成过长内容
• 对于简单任务使用Qwen-Turbo，降低成本
• 缓存重复查询的结果，减少重复调用

常见问题

通义千问和千问大模型是同一个产品吗？

是的。通义千问是品牌旧名称，现已更名为千问大模型。API接口、模型能力完全一致，且持续迭代升级。你在代码中使用的模型名称（如qwen-plus、qwen3.8-max）不受影响。

通义千问API在哪里调用？

千问大模型API通过阿里云百炼平台提供。访问百炼控制台（bailian.console.aliyun.com），注册并开通服务后即可获取API Key进行调用。

调用通义千问API需要花钱吗？

API调用按Token消耗量计费，不同模型版本价格不同。新用户通常有免费额度可以体验。建议先使用免费额度进行测试，确认效果后再购买Token Plan。

通义千问API兼容OpenAI吗？

完全兼容。千问大模型API支持OpenAI SDK格式，你只需将base_url改为https://dashscope.aliyuncs.com/compatible-mode/v1，替换API Key即可，大部分代码无需修改。

API Key泄露了怎么办？

立即在百炼控制台的「API-KEY管理」中删除泄露的Key，并创建新的API Key。建议在代码中使用环境变量或密钥管理服务存储API Key，避免硬编码。

通义千问API有调用次数限制吗？

有默认的QPS（每秒请求数）限制，具体限额因账号等级和模型版本而异。如果你的业务需要更高的并发量，可以在百炼控制台申请提升限额。

为什么我的API调用报错了？

常见报错包括：InvalidApiKey（Key错误）、ModelNotFound（模型名称错误）、RateLimitReached（频率超限）等。详细的排查步骤请参考千问大模型API调用报错FAQhttps://help.aliyun.com/zh/model-studio/api-error-faq。

通义千问API支持流式输出吗？

支持。在请求参数中设置stream=True即可启用流式输出，模型会逐步返回生成内容，适合需要实时展示的应用场景。

从其他平台迁移到千问大模型难吗？

不难。如果你使用OpenAI SDK，只需修改base_url和api_key两个参数。如果从其他国内平台迁移，可能需要调整代码结构，但核心逻辑相通。详细迁移步骤请参考OpenAI迁移指南https://help.aliyun.com/zh/model-studio/openai-migration。

通义千问能处理图片吗？

可以。千问大模型的多模态版本支持图片输入，可以理解和分析图片内容。具体的使用方法请参考多模态模型教程https://help.aliyun.com/zh/model-studio/multimodal-tutorial。如需搭建包含多模态能力的智能体，可参考百炼创建智能体Agent教程https://help.aliyun.com/zh/model-studio/agent-tutorial。