通义千问免费网页版入口：注册即用办公向额度

通义千问的接口由阿里云百炼提供，兼容 OpenAI 协议，base_url 形态为 https://dashscope.aliyuncs.com/compatible-mode/v1，把 OpenAI SDK 的 base_url 指向它，就能复用现有代码。

常用模型名

常见可选模型包括 qwen-plus、qwen-turbo、qwen-max、qwen-long 等，具体可用的模型列表、上下文长度与计费方式以百炼控制台的模型列表为准，也可以调用模型列表接口动态获取，不要凭经验硬编码模型名。

把密钥放进环境变量

先设置环境变量，避免密钥出现在代码里：

export DASHSCOPE_API_KEY="你的APIKey"

用 curl 发起一次对话补全

下面的请求把模型名写成 qwen-plus，messages 里放一条 system 与一条 user：

curl 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": "用三句话说明什么是大模型 API"}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

关键参数说明：model 指定模型名；messages 是对话数组，system 用来设定角色与约束，user 放本次问题，assistant 放历史回复；temperature 控制随机性，越低越稳定；max_tokens 限制回复长度，会直接影响耗时与计费；需要逐字返回时，在请求体里加上 "stream": true，响应会变成逐块推送的事件流，需要按块拼接。

用 Python 调用

先安装官方兼容的 OpenAI SDK：

pip install openai

再从环境变量读取密钥发起请求：

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

resp = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "你是一个简洁的中文助手"},
        {"role": "user", "content": "用三句话说明什么是大模型 API"},
    ],
    temperature=0.7,
    max_tokens=512,
)

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

额度耗尽与限流的典型表现

• 返回 429，错误码为 Throttling 一类：触发了速率或并发限制，需要降低并发、加入指数退避重试。
• 返回 429 且提示额度不足或账户欠费：免费额度已用完或已过有效期，到控制台查看用量与账单明细。
• 返回 401：密钥错误、已删除或环境变量未生效，重新生成密钥并确认进程能读到。
• 返回 404 或提示模型不存在：模型名拼写有误，或该模型尚未在控制台开通。
• 返回 400：参数不合法，重点检查 messages 的结构与 max_tokens、temperature 的取值范围。

排查顺序建议：先看 HTTP 状态码与返回体中的错误码、错误信息，再核对 API Key 与 base_url 是否配套，然后确认模型名与控制台开通状态，最后检查额度、账单与限流规则。写业务代码时请保留原始错误信息并记录日志，方便定位是限流还是额度问题。