千问大模型 API 保姆级教程：账号开通、密钥申领、代码调用一站式接入指南-阿里云开发者社区

很多开发者初次接触国产大模型接口时，常常会混淆产品名称，这里需要明确：原通义千问现已正式更名为千问大模型，底层API接口、模型能力全部保持延续迭代，原有业务代码无需大规模重构，仅需要确认模型参数名称即可。千问大模型的API全部依托百炼平台对外提供服务，并且完整兼容OpenAI SDK协议，对于已经做过OpenAI接口开发的开发者，几乎可以做到无缝迁移，仅修改接口地址与密钥即可完成适配。

本文面向零基础新手以及从其他服务迁移过来的研发人员，完整覆盖账号开通、API‑Key生成、多语言代码调用、流式输出、多轮会话、模型选型、报错排查、成本管控等完整环节，附带大量可直接复制运行的代码片段，帮助开发者快速完成第一次接口调用，同时建立生产环境开发规范。详情👉访问阿里云百炼大模型服务平台页面了解。

一、账号注册开通，获取API调用权限

1.1 账号注册与实名认证

调用千问大模型API的前置条件是完成账号注册以及实名认证，未完成实名认证的账号无法生成可用API‑Key。

访问官网，点击免费注册，使用手机号完成账号注册；
个人账号提交身份证信息完成实名认证；企业业务场景建议完成企业认证，可以解锁更高QPS配额与更多平台权益。

重要提示：实名认证是调用API的硬性门槛，没有经过认证，后续所有接口调用都会直接拒绝。

1.2 开通百炼平台服务

千问大模型全部API能力托管在百炼控制台，开通服务本身不会收取任何费用，后续消耗按照Token用量计费。

进入百炼控制台页面，登录刚刚注册完成的账号；
首次登录会弹出服务开通弹窗，点击立即开通；
阅读并勾选服务协议，确认开通。
详情👉访问阿里云百炼大模型服务平台页面了解。

如果登录控制台没有弹出开通弹窗，代表账号已经自动完成开通，可以直接进入密钥管理页面。

1.3 创建并且保存API‑Key

API‑Key是访问接口的身份凭证，拥有账号级别调用权限，这一步务必做好保存。

控制台右上角点击账号头像，找到「API‑KEY管理」；
点击创建新的API Key，填写备注，例如“测试环境”“生产业务”，方便后续区分不同业务密钥；
创建成功立刻复制完整密钥保存，页面关闭之后，平台不会再次展示完整密钥，只能看到掩码脱敏后的字符串，如果丢失只能够删除重建。

安全最佳实践：禁止把API‑Key硬编码写进源码，不要提交公开代码仓库，不要随意转发给其他人。生产环境优先使用环境变量、密钥管理组件存放密钥。一旦密钥泄露，立刻在控制台删除旧密钥，新建一组密钥继续使用。

二、本地开发环境准备

千问大模型兼容OpenAI SDK，Python、Node.js环境直接安装官方openai依赖包即可，不需要额外安装专用SDK。同时接口基于标准HTTP协议，Java、Go、C#等任意编程语言都可以通过HTTP请求完成调用。

Python环境配置

# 安装openai SDK
pip install openai
# 推荐使用虚拟环境隔离项目依赖
python -m venv qwen-dev-env
# macOS / Linux激活虚拟环境
source qwen-dev-env/bin/activate
# Windows cmd激活虚拟环境
qwen-dev-env\Scripts\activate

Node.js环境配置

# 安装openai npm包
npm install openai

环境变量设置（避免硬编码密钥）

Linux/macOS终端设置环境变量：

export DASHSCOPE_API_KEY="你的APIKEY字符串"

Windows PowerShell设置环境变量：

$env:DASHSCOPE_API_KEY="你的APIKEY字符串"

设置完成之后，代码就可以读取环境变量，密钥不会写在源代码文件内部，降低泄露风险。

三、第一次API调用，多语言完整示例

兼容模式统一接口地址：https://dashscope.aliyuncs.com/compatible-mode/v1，所有兼容OpenAI的请求都指向该地址。

Python基础对话调用示例

import os
from openai import OpenAI

# 初始化客户端，从环境变量读取密钥
client = OpenAI(
    api_key=os.environ.get("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

def simple_chat():
    resp = client.chat.completions.create(
        model="qwen-plus",
        messages=[
            {
   "role": "system", "content": "你是专业友好的AI助手，回答简洁清晰。"},
            {
   "role": "user", "content": "简单介绍千问大模型"}
        ]
    )
    content = resp.choices[0].message.content
    print("模型返回结果：")
    print(content)

if __name__ == "__main__":
    simple_chat()

Node.js完整调用示例

import OpenAI from 'openai';

const client = new OpenAI({
   
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
});

async function runChat() {
   
    const result = await client.chat.completions.create({
   
        model: "qwen-plus",
        messages: [
            {
   role:"system", content:"你是专业友好的AI助手，回答简洁清晰。"},
            {
   role:"user", content:"简单介绍千问大模型"}
        ]
    })
    console.log("模型返回结果：")
    console.log(result.choices[0].message.content)
}

runChat().catch(err=>console.error(err))

curl命令行直接调用，无需安装SDK

适合快速调试、脚本自动化测试场景，直接终端执行：

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":"你是专业友好的AI助手，回答简洁清晰。"},
{"role":"user","content":"简单介绍千问大模型"}
]
}'

调用成功之后，终端打印模型返回文本，代表第一次接口调用已经跑通。

四、模型版本选型参考

千问大模型提供多个不同定位的模型，不同版本推理能力、速度、Token单价差异明显，开发者需要结合业务场景选择对应的model参数，不要一味使用最高规格模型，避免不必要成本浪费。

模型名称	核心特点	推荐业务场景
Qwen3.8‑Max	旗舰版本，深度推理、复杂逻辑能力最强	法律合同解析、学术分析、复杂数学推演、大型代码重构
Qwen‑Plus	综合均衡，兼顾速度质量，支持多模态图文解析	绝大多数通用业务，普通对话、内容创作、图文识别，新手首选
Qwen‑Turbo	轻量高速，调用成本低廉	高并发客服问答、短文本摘要、标签提取、简单文案生成
Qwen‑Long	超大上下文窗口	超长文档、整本资料解析，万级以上文本输入场景

新手建议优先选择qwen‑plus，性能与成本平衡；当业务需要深度专业推理任务，切换qwen3.8‑max；高并发简单问答场景使用qwen‑turbo。

调用旗舰版本示例，仅修改model参数即可：

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

五、进阶开发用法

5.1 多轮对话实现

大模型本身不会保存会话记忆，所有历史对话消息必须全部传入messages数组，才能实现连贯多轮聊天，只传最新用户提问会出现上下文丢失、答非所问的问题。

Python多轮对话示例代码：

multi_messages = [
    {
   "role":"system","content":"你是Python编程导师，通俗易懂讲解知识点。"},
    {
   "role":"user","content":"什么是列表推导式？"},
    {
   "role":"assistant","content":"列表推导式是Python简洁生成列表的语法，替代简单for循环。"},
    {
   "role":"user","content":"写一个简单实操示例"}
]
resp = client.chat.completions.create(
    model="qwen-plus",
    messages=multi_messages
)
print(resp.choices[0].message.content)

业务开发中，需要自己在业务侧维护messages消息列表，每一轮对话追加user与assistant消息。

5.2 流式输出stream

流式输出适合网页聊天界面，实现打字机实时输出效果，设置stream=True开启，接口会分块返回生成内容，不需要等待完整回答全部生成完毕才返回结果。

Python流式输出完整代码：

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

5.3 多模态图文调用

Plus系列模型支持图片解析，可以传入图片URL完成OCR、图片内容理解，兼容OpenAI多模态消息格式：

resp = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {
   
            "role":"user",
            "content":[
                {
   "type":"text","text":"描述这张图片里面的内容"},
                {
   "type":"image_url","image_url":{
   "url":"https://xxx/test.jpg"}}
            ]
        }
    ]
)
print(resp.choices[0].message.content)

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

开发调试阶段，经常会遇到接口返回异常，下面整理高频报错，帮助快速定位问题：

InvalidApiKey

报错含义：API密钥无效。
排查：检查复制密钥是否存在多余空格换行；确认账号完成实名认证；如果密钥已经失效，控制台删除旧密钥，重新创建新API‑Key。

ModelNotFound

报错含义：找不到指定模型。
排查：核对model参数字符串拼写，区分大小写，确认模型名称和官方文档一致；前往百炼控制台模型广场确认该模型服务已经开通。

RateLimitReached

报错含义：请求QPS超过账号限额。
排查：业务端增加请求间隔，降低并发；企业业务可以在控制台提交申请，调高账号QPS上限。

其他少见报错，可查阅平台官方FAQ文档，根据返回的错误码定位根因。

七、计费模式与成本控制技巧

平台提供两种计费模式：按量付费、Token Plan订阅套餐，两种模式适合不同业务规模。

按量付费：按照实际输入输出Token消耗扣费，适合项目测试、小规模流量业务，新用户会赠送免费体验额度，额度耗尽之后自动扣费。
Token Plan预付费订阅：按月订阅，享受价格折扣，适合业务流量稳定、长期调用的场景，统一使用Credits抵扣各类模型调用消耗。

降低Token开销实操技巧

精简system提示词，去掉冗余无效描述，减少输入Token消耗；
合理设置max_tokens，限制模型最大输出长度，避免无意义超长返回；
分层调度：简单短任务切换Turbo轻量模型，复杂推理才使用Max旗舰版本；
开启会话缓存，重复上下文内容缓存复用，能够大幅降低重复输入Token计费；
设置账单消费告警，监控用量，及时发现异常暴涨调用。

八、高频开发疑问解答

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

属于同一套产品，只是品牌名称更新，接口、模型能力全部延续迭代，原有业务代码不需要大规模改动。

API是否完全兼容OpenAI SDK？

完全兼容，仅仅修改base_url和api_key两个参数，绝大多数原有OpenAI业务代码可以直接迁移过来。

API密钥泄露该如何处理？

立刻进入控制台API‑KEY管理页面删除泄露密钥，生成全新密钥；业务代码全部改为读取环境变量，杜绝硬编码密钥。

是否支持流式输出？

支持，请求参数设置stream=True即可开启流式增量返回，适合聊天产品前端实时渲染。

是否支持图片识别？

Plus系列多模态模型支持图片输入，使用多模态消息格式传入图片url，即可完成图片解析。

九、生产环境落地建议

开发环境、测试环境、生产环境分开使用不同API‑Key，一旦某一个环境密钥泄露，不会影响全部业务；
不要在客户端直接存放API‑Key，密钥只允许存放后端服务，前端请求必须经过后端中转；
做好异常捕获，接口调用增加超时、重试逻辑，处理限流、服务临时抖动；
上线前先用免费额度充分测试，确认效果，评估Token消耗，再正式上线业务；
监控账单用量，配置消费告警，防止循环调用、脚本bug造成意外高额消耗。

总结

千问大模型依托百炼平台提供兼容OpenAI标准的API接口，降低了开发者接入国产大模型的门槛。整个接入链路分为账号实名认证开通服务、生成API‑Key、本地环境配置、接口调试、业务迭代优化几个阶段。普通对话、多轮会话、流式输出、图文多模态都有成熟的代码实现，开发者可以直接复用示例代码快速验证业务想法。选型层面，优先qwen‑plus覆盖绝大多数业务；复杂深度推理选择qwen3.8‑max；高并发轻量化任务使用qwen‑turbo。

同时密钥安全、Token成本管控、异常容错是生产环境不可忽视的关键点，密钥禁止硬编码，区分多套密钥，搭配分层模型调度、缓存复用，在满足业务效果前提下，把调用成本控制在合理区间。不管是个人开发者做原型验证，还是企业构建AI业务系统，这套接入流程都可以作为基础开发参考。

千问大模型 API 保姆级教程：账号开通、密钥申领、代码调用一站式接入指南