如何使用 Qwen 3.7 API？

阿里巴巴 Qwen 团队在 2026 年 5 月中旬发布了 Qwen3.7-Max-Preview，开发者们随即提出了同一个问题：如何在代码中调用它？该模型是一款旗舰级推理系统，拥有 1M-token 的 context window（上下文窗口）和显式的 chain-of-thought（思维链）轨迹，非常适合作为 agent 后端、进行长文档分析以及代码生成。但名称中的 “preview” 意味着很多：访问受限、API 接口仍在调整中，且编写可用代码所需的细节散落在发布说明和平台文档各处。

Qwen3.7-Max-Preview 是阿里巴巴的旗舰级推理模型，于 2026 年 5 月 14 日发布预览版，具备 1M-token context window。在预览期间，最可靠的使用方式是 Qwen Chat (chat.qwen.ai)；生产环境的 API 访问通过阿里云百炼（Model Studio/DashScope）进行，使用 OpenAI 兼容的 endpoint。你需要设置 base URL，将 key 作为 Bearer token 传递，并调用 /chat/completions。由于 3.7 版本目前仅限预览，请在发布前查阅官方文档确认准确的 model ID 和 endpoint，并使用 Apifox 在可用性稳定期间测试和 mock 该接口。

如何立即访问 Qwen 3.7

Qwen 通过几个不同的平台发布模型，且并非所有平台都会同步上线。截至 2026 年 5 月底，以下是真实的访问现状：

Qwen Chat (chat.qwen.ai)： 体验 Qwen3.7-Max-Preview 最快的方式。使用免费的 Qwen 账号登录，在模型选择器中选择 qwen3.7-max-preview，并开启 Thinking Mode（思考模式）以查看推理轨迹。预览期间会有使用率限制（rate limits），但无需付费也无需配置。这是一个浏览器端产品，而非 API，因此适用于评估而非集成。

阿里云百炼 (Model Studio/DashScope)： 这是 Qwen 模型转化为真正 API 的地方。百炼通过 OpenAI 兼容的 endpoint 暴露 Qwen，因此任何已经对接 OpenAI SDK 的代码只需更换 base-URL 和 key 即可调用 Qwen。像 qwen3.6-max-preview 和 qwen-max 系列等较早的版本已经在此上线。当你阅读本文时，3.7 预览版可能尚未开放公共 API 入口；根据以往经验，Qwen 通常会在网页版预览开启几周后开放 API 访问。

OpenAI 兼容模式： 百炼上的所有近期 Qwen 模型都遵循相同的模式。你只需将标准的 OpenAI client 指向 DashScope 的 base URL，使用 Bearer token 进行身份验证，并调用 chat completions 路由。这种模式在不同版本间是稳定的，因此随着 3.7 model ID 的上线，下方的代码依然有效；你主要只需更改一个字符串。

由于模型标识符和 endpoint 在预览期间可能会发生变化，请以 Qwen 官方文档 和 百炼模型列表 作为最终依据。如果你在等待 API 访问权限期间寻找零成本方案，

访问方式一览

值得注意的一点是：开源权重的 Qwen 模型会发布到 Hugging Face，但 Max-Preview 级别是专有的，因此不要指望能下载到 qwen3.7-max-preview 的权重。

获取 Qwen 3.7 API Key

API 访问需要通过阿里云账号。步骤如下：

1. 创建阿里云账号并打开百炼控制台 (modelstudio.console.alibabacloud.com)。
2. 为你的账号和区域激活百炼服务。Key 是区分区域的，因此新加坡 endpoint 的 key 无法在北京 endpoint 使用。
3. 打开控制台的 API keys 部分并生成一个 key。它看起来像 sk- 后面跟着一串字符。
4. 复制 key 并像保存密码一样妥善保管。

请慎重选择区域，因为它决定了你的 base URL：

切勿在提交的代码中硬编码 key。请改用环境变量：

# macOS / Linux
export DASHSCOPE_API_KEY="sk-your-key-here"

# Windows PowerShell
setx DASHSCOPE_API_KEY "sk-your-key-here"

你的代码在运行时读取 DASHSCOPE_API_KEY。这可以确保 secret 不会进入代码库，并允许你在不改动代码的情况下更换 key。无论调用什么模型，这都是一个好习惯；你在我们的 Gemini 3.5 API 指南中也会看到同样的模式。

你的第一个请求：Python、curl 和 JavaScript

Qwen 的百炼 endpoint 兼容 OpenAI，因此你有两个选择：使用指向 DashScope base URL 的官方 OpenAI SDK，或者直接进行原始 HTTP 调用。下面分别展示这两种方式。

在看代码前请注意：model ID qwen3.7-max-preview 是 Qwen Chat 为预览模型使用的标识符。API 预期的准确字符串在预览期间可能会有所不同，当你尝试时，像 qwen3.6-max-preview 这样的旧版本可能已经上线。请在百炼模型列表中确认当前的 model ID，然后将其填入 model 字段。请求的结构不会改变。

使用 OpenAI SDK 的 Python 示例

使用 pip install openai 安装 SDK，然后发送请求：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    # 使用你账号所在区域的 base URL
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

response = client.chat.completions.create(
    # 在百炼模型列表中确认当前的 model ID
    model="qwen3.7-max-preview",
    messages=[
        {"role": "system", "content": "You are a precise coding assistant."},
        {"role": "user", "content": "Write a Python function that reverses a linked list."},
    ],
)

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

这是一个完整的请求。messages 数组遵循标准的 role 模式：system 消息设定行为，随后是 user 提问。响应结果包含在 choices[0].message.content 中。

curl 示例

用于从终端快速检查，或在编写应用代码前确认 key 是否有效：

curl 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen3.7-max-preview",
    "messages": [
      {"role": "user", "content": "Explain idempotency in REST APIs in two sentences."}
    ]
  }'

如果 key 和 model ID 有效，你将收到包含 completion 结果的 JSON 响应。否则，错误主体会告诉你需要修复的地方；下文将详细介绍错误处理。

JavaScript / Node.js 示例

同样的 OpenAI SDK 也适用于 Node。使用 npm install openai 安装：

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "qwen3.7-max-preview",
  messages: [
    { role: "user", content: "List three trade-offs of GraphQL versus REST." },
  ],
});

console.log(response.choices[0].message.content);

三种语言，同一种请求结构；这就是 OpenAI 兼容 API 的优势。

流式响应 (Streaming)

对于任何面向用户的应用，你都不希望在显示输出前等待完整的 completion。流式传输会在 token 生成时立即发送。将 stream 设置为 true 并遍历 chunks。

stream = client.chat.completions.create(
    model="qwen3.7-max-preview",
    messages=[
        {"role": "user", "content": "Summarize the CAP theorem."},
    ],
    stream=True,
)

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

在 Node 中，流式响应是一个异步迭代器：

const stream = await client.chat.completions.create({
  model: "qwen3.7-max-preview",
  messages: [{ role: "user", content: "Summarize the CAP theorem." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

流式传输对于推理模型比普通聊天模型更重要。Qwen 3.7 在给出最终答案前可能会花费不少时间进行 chain of thought，因此如果没有流式传输，用户只能盯着空白屏幕。通过流式传输，你可以展示思考轨迹、打字指示器或正在生成的答案。

推理与思考参数

Qwen3.7-Max-Preview 是一款推理模型。它可以在给出最终答案前，在 <think> 块内生成显式的思维链。这种轨迹提升了它在数学和复杂的跨步骤问题上的表现，并有助于调试：你可以看到模型的逻辑在哪里出现了偏差。

在通过百炼提供的近期 Qwen 模型上，思考行为通过 enable_thinking 标志控制。请根据当前的 API 参考文档确认 3.7 预览版的具体机制和参数名称，因为推理控制在不同 Qwen 版本间可能有所变化。从概念上讲，请求如下所示：

response = client.chat.completions.create(
    model="qwen3.7-max-preview",
    messages=[
        {"role": "user", "content": "A train leaves at 2pm averaging 60mph. "
                                    "A second leaves at 3pm at 75mph on the same route. "
                                    "When does the second catch the first?"},
    ],
    # 推理控制因 Qwen 版本而异；在使用前请确认
    # 百炼 API 参考文档中的当前参数。
    extra_body={"enable_thinking": True},
)

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

几点实用建议：

• 思考会消耗 token 和时间。 推理轨迹也是生成的文本。它会计入输出 token 并增加延迟。对于简单的查询或格式化任务，请关闭思考功能。
• 针对难题开启它。 多步数学题、具有复杂边界情况的代码、规划和分析是思维链发挥价值的地方。
• 决定是否展示轨迹。 一些应用会展示 <think> 内容，让用户看到模型的思考过程；另一些则会将其剥离，仅显示最终答案。两种方式都是可行的。

如果你正在权衡推理质量和成本与其他前沿模型的优劣，我们的 Qwen 3.7 vs GPT-5.5 vs Opus 4.7 对比详细列出了各项权衡。推理模型在 agent 循环中会快速消耗 token；如果这是你的应用场景，我们关于如何降低 agent token 成本的文章中的技术将直接适用。

错误处理与频率限制 (Rate Limits)

请求可能会因可预见的原因失败。请妥善处理这些错误，以便你的应用能够优雅降级。

预览版模型比稳定版更容易抛出 403 和 404 错误，因为访问受限且标识符经常变动。如果你遇到这些错误，问题通常出在访问权限或模型字符串上，而非你的代码。

百炼上的频率限制是按账号设置的（每秒查询数 QPS 或每分钟查询数），具体数值取决于你的账号等级和模型；请查看控制台而非假设一个固定值。处理模式是通用的：捕获 429，等待，然后以递增的延迟重试。

import time
from openai import OpenAI, RateLimitError, APIStatusError

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

def ask_qwen(prompt, max_retries=4):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="qwen3.7-max-preview",
                messages=[{"role": "user", "content": prompt}],
            )
            return response.choices[0].message.content
        except RateLimitError:
            wait = 2 ** attempt          # 1s, 2s, 4s, 8s
            print(f"Rate limited. Retrying in {wait}s...")
            time.sleep(wait)
        except APIStatusError as e:
            # 400/401/403/404 不值得重试；直接抛出
            print(f"API error {e.status_code}: {e.message}")
            raise
    raise RuntimeError("Failed after retries")

对 429 和 5xx 使用指数退避，对 4xx 快速失败。这种策略可以防止你在重试无法解决的错误上浪费 API 调用。

使用 Apifox 测试和 Mock Qwen API

这正是预览版 API 让人头疼的地方，也是优秀工具发挥作用的地方。当访问受限、model ID 不断变动且频率限制严格时，你肯定不想通过运行整个应用并阅读日志来测试。你希望发送一个请求，准确看到返回内容，并能保存下来再次运行。Apifox 正是为此类循环而设计的。

在开发时 Mock 端点。 对于受限预览版来说，这是重头戏。Apifox 的 mock server 可以根据 API schema 返回真实的响应，无需 key 也没有频率限制。因此，你的前端或 agent 可以在一个始终即时响应的替代 Qwen endpoint 上进行开发，即使真实的预览访问被限制、宕机或尚未对你的账号开放。当生产 API 准备就绪时，只需将 base URL 从 mock 地址切换到 DashScope，你的代码无需任何改动。欲了解更多关于 schema-first 工作流的信息，请参阅我们的 spec-first 模式演示。

这种模式适用于任何模型 API。无论你调用的是 Qwen、Gemini 还是 ERNIE 5.1 API，Apifox 中的测试和 mock 循环都同样有效；预览版模型让 mock 步骤变得更有价值，因为真实的 endpoint 往往是你技术栈中最不可靠的部分。

结论

一旦理清了路径，调用 Qwen 3.7 其实非常简单。真正的阻力在于预览版的访问限制，而非 API 本身。

不要再猜测 Qwen 会返回什么，直接亲眼见证。立即下载 Apifox 来设计 Qwen 接口、发送真实的测试请求、保存可复用的场景，并在开发过程中 mock API，它可以免费开始使用，能将不稳定的预览版转化为你可以放心开发的可靠资源。