阿里云百炼国际版免费额度：新用户每模型百万级体验

百炼国际版提供 OpenAI 兼容接口，因此任何支持自定义 base_url 的 OpenAI SDK 都可以直接对接，无需更换代码结构。

一、准备环境变量

先把上一步创建的 API Key 写入环境变量，避免硬编码在代码里：

export DASHSCOPE_API_KEY="你的国际站API Key"

二、接口地址与模型名

国际站的 base_url 形如 https://dashscope-intl.aliyuncs.com/compatible-mode/v1，对话补全的完整路径是在其后追加 /chat/completions。模型名常见的有 qwen-plus、qwen-turbo、qwen-max 等，可在控制台的模型列表页查看当前已开通的完整清单，以控制台实际显示为准。

三、用 curl 发一次请求

下面的命令可直接复制执行，注意引号必须保持英文直引号：

curl https://dashscope-intl.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": "用三句话介绍你自己"}
    ],
    "temperature": 0.7,
    "max_tokens": 512,
    "stream": false
  }'

四、用 Python SDK 调用

安装 openai 包后，把 base_url 指向国际站地址即可：

from openai import OpenAI
import os

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

resp = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "你好"}],
    temperature=0.7,
    max_tokens=512,
    stream=False,
)
print(resp.choices[0].message.content)

五、关键参数说明

• model：必填，模型名必须是控制台已开通的模型，写错会返回模型不存在的错误。
• messages：必填，按 system、user、assistant 角色组织的消息数组，system 用于设定人设与约束。
• temperature：采样随机性，取值 0 到 2 之间，写代码或抽取结构化数据时建议调低。
• max_tokens：限制本次回复的最大长度，设置过小会出现回答被截断。
• stream：设为 true 时以流式返回，适合做打字机效果，客户端需逐块解析。
• top_p：与 temperature 二选一调整即可，一般不建议同时大幅改动。

六、额度耗尽与限流的排查顺序

典型表现包括：返回 401 提示密钥无效、返回 403 提示无权限、返回 404 提示模型不存在、返回 429 提示请求过于频繁或配额不足。按下面顺序排查效率最高：

1. 先确认 base_url 用的是国际站地址，且控制台地域为新加坡，避免与国内站混用。
2. 检查 API Key 是否复制完整、是否已被删除或重置，环境变量名是否与代码一致。
3. 在控制台查看免费额度的剩余量与有效期，判断是额度用完还是到期作废。
4. 核对模型名是否在已开通列表中，新模型可能需要先在控制台开通。
5. 若返回 429，区分是短时并发限流还是当日配额上限：前者降低并发或加重试退避，后者需等到配额重置或充值。
6. 最后排查跨境网络，必要时用 HTTPS 代理或就近部署服务端，减少超时与连接中断。