一、注册与获取API Key

如果你做支付宝小程序或钉钉小程序，阿里云系的产品天然适配。通义千问API稳定、价格适中，是国内小程序开发者的好用选择。

步骤1：注册阿里云账号

访问 阿里云官网，点击右上角「免费注册」。支持手机号、邮箱、支付宝等多种方式注册。已有阿里云账号可直接登录。

步骤2：开通模型服务灵积（DashScope）

登录阿里云后，进入 模型服务灵积（DashScope） 控制台。首次使用需要单击「开通服务」，根据提示完成实名认证即可。开通后即可使用通义千问的各项模型能力。

步骤3：创建API Key

在DashScope控制台左侧菜单找到「API-KEY管理」→ 点击「创建API-KEY」。给Key起个名字（比如"开发测试"或"生产环境"），点击确定后Key会显示一次。

⚠️ 非常重要：API Key 只会在创建时显示一次，关闭页面后就看不到了。务必立即复制保存到安全的地方（比如密码管理器或.env文件）。如果不小心关了，只能删除重新创建。Key的格式类似 sk-xxxxxxxxxxxxxxxx。

步骤4：查看免费额度

通义千问新用户注册后，每月自动获得 100万 tokens 免费额度（包含输入和输出），有效期一个月，次月自动续赠。在DashScope控制台的「计量管理」或「用量统计」页面可以查看剩余额度。

💡 提示：通义千问API完全兼容OpenAI的接口格式，所以你可以直接使用 openai Python包或Node.js包来调用，只需将 base_url 改为 https://dashscope.aliyuncs.com/compatible-mode/v1 即可。推荐使用 qwen-plus 模型，性能和速度均衡。

二、用curl测试（最快验证方式）

不管你是用什么语言开发，先用curl跑通一遍，确认API Key有效、网络通畅。

bash 
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的API_KEY" \
  -d '{
    "model": "qwen-plus",
    "messages": [
      {"role": "system", "content": "你是一个有用的助手"},
      {"role": "user", "content": "用一句话解释什么是AI"}
    ]
  }'

如果返回类似下面的结果，说明调通了：

json 
{
  "id": "chatcmpl-abc123",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "AI（人工智能）是让计算机模拟人类智能行为的技术，包括学习、推理、感知和决策等能力。"
    }
  }],
  "usage": {
    "prompt_tokens": 30,
    "completion_tokens": 25,
    "total_tokens": 55
  }
}
⚠️ 注意： 如果 curl 报错，先确认 API Key 是否正确。常见错误：复制时多了空格、Key 已过期、或把接口地址写成了旧版DashScope地址。务必使用 https://dashscope.aliyuncs.com/compatible-mode/v1 这个兼容地址，而不是旧版的 dashscope.aliyuncs.com/api/v1。

三、用Python调用

Python是调用AI API最常用的语言。通义千问兼容OpenAI的SDK，所以可以直接用 openai 包，只需改两个参数：api_key 和 base_url。

安装依赖

bash 
pip install openai

基础对话

python 
from openai import OpenAI

# 初始化客户端（关键：改 base_url 和 api_key）
client = OpenAI(
    api_key="sk-你的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": "用Python写一个快速排序算法"}
    ]
)

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

流式输出（打字机效果）

流式输出可以让AI一边生成一边显示，用户体验更好：

python 
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的API_KEY",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

stream = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "讲一个程序员笑话"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

四、用Node.js调用

安装依赖

bash 
npm install openai

基础对话

javascript 
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-你的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: '你是一个有用的助手' },
      { role: 'user', content: 'Node.js如何读取文件？' }
    ]
  });
  console.log(response.choices[0].message.content);
}
main();

五、常用功能代码示例

1. AI自动写文章

python 
def generate_article(topic, style="专业"):
    """根据主题生成文章"""
    response = client.chat.completions.create(
        model="qwen-plus",
        messages=[{
            "role": "user",
            "content": f"请以{style}的风格，写一篇关于「{topic}」的800字文章。要求：有标题、有分段、有数据支撑。"
        }]
    )
    return response.choices[0].message.content

2. 智能客服自动回复

python 
def customer_service(user_message, history=[]):
    """智能客服，带上下文记忆"""
    messages = [{"role": "system", "content": "你是一个专业的电商客服，回答简洁有礼貌。"}]
    # 添加上下文历史
    for h in history[-5:]:  # 只保留最近5轮
        messages.append(h)
    messages.append({"role": "user", "content": user_message})
    
    response = client.chat.completions.create(
        model="qwen-plus",
        messages=messages
    )
    return response.choices[0].message.content

3. 批量翻译

python 
def batch_translate(texts, target_lang="英语"):
    """批量翻译文本"""
    batch_text = "\n---\n".join(texts)
    response = client.chat.completions.create(
        model="qwen-plus",
        messages=[{
            "role": "user",
            "content": f"将以下文本逐条翻译成{target_lang}，保持原格式用---分隔：\n\n{batch_text}"
        }]
    )
    return response.choices[0].message.content.split("\n---\n")

六、常见错误及解决

错误代码 原因 解决方案
401 Unauthorized API Key 错误、未开通服务或已过期 检查 Key 是否完整复制；确认已在DashScope开通服务；检查Key是否过期
403 Forbidden 未完成实名认证或模型未授权 前往阿里云完成实名认证；确认已开通对应模型的访问权限
429 Too Many Requests 请求频率超过免费额度限制 降低请求频率，添加 sleep 间隔；或充值付费获得更高QPS
400 Invalid URL / 404 接口地址写错 确认使用 https://dashscope.aliyuncs.com/compatible-mode/v1 而非旧版地址
400 context length exceeded 对话历史太长，超过模型上下文限制 截断历史消息，只保留最近几轮对话
timeout / 请求超时 网络连接不稳定 检查网络环境，加长 timeout 时间，或使用阿里云内网地址（如果部署在阿里云上）
💡 最佳实践：在生产环境中，建议添加重试机制（retry）。Python可以用 tenacity 库，每次失败后等待2秒再重试，最多重试3次。对于部署在阿里云ECS上的应用，建议使用内网访问地址，延迟更低且免流量费。

七、价格与免费额度

项目 价格
月免费额度 100万 tokens（输入+输出合计），每月自动续赠
qwen-turbo 输入 ¥0.3 / 百万 tokens
qwen-turbo 输出 ¥0.6 / 百万 tokens
qwen-plus 输入 ¥0.8 / 百万 tokens
qwen-plus 输出 ¥2.0 / 百万 tokens
估算：一篇2000字文章 约 ¥0.01（一分钱）
估算：100万次客服对话 约 ¥500-800

模型推荐：

  • qwen-plus：推荐首选，性能均衡，适合大多数场景（写作、翻译、客服、代码生成）
  • qwen-turbo：速度更快、价格更低，适合简单对话、分类、提取等轻量任务

对比其他国产模型，通义千问的优势在于：阿里云背书稳定性好、兼容OpenAI SDK切换成本低、每月固定100万免费额度不用抢。适合已有阿里云账号、需要稳定企业级API服务的用户。

八、实际项目应用场景 & 代接服务

API调通了，然后呢？以下是我们用通义千问API做过并验证过的落地场景：

场景一：AI客服机器人

客户在网站/小程序提问，AI自动回复。我们用通义千问+钉钉机器人做过，运行稳定。适合电商、教育、服务类商家。

  • 接入方式：前端 → 你的后端 → DashScope API
  • 成本估算：1000次对话 ≈ ¥1（多数在免费额度内）
  • 我们能帮做：¥500 整套部署

场景二：自动写日报/周报

对接钉钉机器人或企业微信，每天自动生成工作日报。员工只需输入关键词，AI基于通义千问生成完整报告，节省大量重复劳动。

场景三：AI合同/文档生成

通义千问对中文法律文书有较好的理解能力，适合做AI合同生成、简历优化、方案撰写等文档智能应用。qwen-plus模型128K上下文窗口可以处理超长文档。

场景四：AI代码审查与辅助开发

把你的代码发给通义千问，它帮你检查Bug、优化性能、补充注释。通义千问在代码任务上表现出色，尤其适合审查Java、Python、JavaScript项目。