如果你第一次接触 AI API，看到“Base URL、API Key、模型 ID、分组倍率”这些词可能会有些陌生。本教程面向已有账号的用户，带你完成登录、充值、选择模型、创建密钥、导入 CC Switch、配置常用客户端，并学会查看费用与排查错误。

文档信息

• 文档性质：QwQのapi 官方使用文档
• 适用读者：已经拥有 QwQのapi 账号，希望完成首次配置或排查常见问题的用户
• 文档版本：v1.2
• 最后更新：2026 年 7 月 29 日
• 适用范围：当前网页控制台、公开 API 和文中列出的客户端配置；不包含账号注册流程

模型、分组、价格、倍率、支付方式和功能可能调整。涉及费用和可用性的内容，请以登录后的控制台、模型广场、请求日志及状态监控的实时显示为准。

五分钟快速开始

如果账户已有余额，并且目标客户端已经安装，按下面步骤通常可以快速完成首次调用：

1. 登录 QwQのapi，确认账户有可用余额、兑换额度或试用权限。
2. 打开模型广场，复制目标模型的准确模型 ID，并记下支持它的分组。
3. 进入“API 密钥”，创建 Key，选择对应分组；首次使用建议设置较小的额度上限。
4. 使用 CC Switch 时，点击该 Key 右侧“使用 → CC Switch 导入 → 一键导入”；其他客户端按本文对应章节填写 Base URL、API Key 和模型 ID。
5. 发送一句简单提示词，例如“你好，请只回复连接成功”。
6. 打开请求日志，确认状态、模型、Token 和费用符合预期。

两个最容易填错的地址：OpenAI Compatible 使用 https://qwqzy.top/v1；Anthropic 原生接口使用 https://qwqzy.top，不要添加 /v1。

如果使用 OpenAI Compatible，可在替换 Key 和模型 ID 后直接测试：

curl https://qwqzy.top/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"请替换为模型广场中的模型ID","messages":[{"role":"user","content":"你好，请只回复连接成功"}]}'

这是 Bash 写法；Windows PowerShell 或 CMD 可使用单行命令。更多示例见开发者最小调用示例。

安全提醒：API Key 和 CC Switch 导入链接都属于敏感凭证，不要发送给他人，也不要粘贴到公开网页、群聊、工单正文或代码仓库。

文章目录

1. 文档信息与五分钟快速开始
2. 平台介绍、登录与控制台
3. 充值、兑换、模型和分组
4. 创建 API Key 与 CC Switch 一键导入
5. 聊天客户端、开发工具与代码调用
6. 日志、监控与常见问题
7. 首次使用检查清单
8. 官方支持与服务边界及术语表
9. 文档变更记录

一、QwQのapi 是什么？

QwQのapi 是一个多模型 AI API 网关。你可以用同一个站点账户管理余额和密钥，再通过不同分组访问 OpenAI、Anthropic、Grok 等模型。它适合：

• 想在 Chatbox、NextChat、OpenCat 等聊天客户端使用自定义模型的普通用户；
• 使用 CC Switch、Claude Code、Codex CLI、Cursor、Cline 或 Roo Code 的用户；
• 需要在自己的 Python、Node.js 项目中调用 AI API 的开发者。

最重要的两个地址：

• OpenAI 兼容接口：https://qwqzy.top/v1
• Anthropic 原生接口：https://qwqzy.top（末尾不要加 /v1）

二、登录

1. 打开 https://qwqzy.top/，点击“登录”。
2. 输入已有账号的邮箱和密码。
3. 阅读服务条款、使用政策、支持的国家和地区及服务特定条款，然后勾选同意。
4. 完成人机验证后点击“登录”。

三、认识控制台

登录后会进入“概览”。这里可以查看账户余额、今日用量、近 7 天与近 30 天费用、调用次数、Token 数、实时 RPM、实时并发以及计费状态。

左侧常用入口包括：

• API 密钥：创建、禁用、查看和删除密钥；
• 模型广场：查找模型 ID、价格和可访问分组；
• 请求日志：检查每次请求的状态、耗时、Token 和费用；
• 使用量统计：查看一段时间内的消费趋势；
• 状态监控：查看分组可用率和首包延迟；
• 充值中心 / 兑换：补充余额、并发数或试用权限；
• 账户设置：设置余额不足提醒和安全选项。

四、充值与兑换

1. 在线充值

进入“充值中心”，选择预设金额或输入自定义金额，再选择支付方式并确认。本文采集截图时，页面显示最低充值金额为 ¥1，并提供支付宝；这些信息可能随平台调整，请始终以付款页当前显示的金额、汇率、支付方式和活动为准。

支付完成后余额通常自动到账。如果长时间未到账，请保留订单号和支付记录，通过站内“联系”入口寻求支持。

2. 使用兑换码

进入“兑换”，输入兑换码后提交。本文采集时的页面规则提示兑换码区分大小写，且通常每个码只能使用一次；兑换内容可能包括余额、并发数或试用权限，具体以兑换页面和兑换结果为准。建议直接复制粘贴，避免手输错误。

五、先选模型和分组

创建密钥前，建议先打开“模型广场”。你可以按平台筛选或搜索模型，并查看输入、输出、缓存写入、缓存读取参考价及可访问分组。

点击模型卡片可查看不同分组的倍率。理解计费时请记住：

• 模型广场优先显示渠道定价；渠道缺失时可能显示 GitHub 公共目录参考价；
• 密钥创建时选择的分组决定可用模型、稳定性和倍率；
• 实际扣费由模型单价、请求使用的分组倍率、Token/次数等计费方式和最终结算共同决定；
• 不要只看倍率，还要结合分组说明和状态监控判断稳定性。

六、创建 API Key

1. 进入“API 密钥”，点击“创建 API Key”。
2. 填写便于识别的名称，例如“CC Switch-Claude”或“Chatbox-日常”。
3. 选择与你要使用的平台对应的分组。分组选择错误时，即使模型名正确也可能不可用。
4. 新手建议设置一个较小的额度限制，防止客户端异常循环消耗余额。
5. 如有固定设备，可按需设置 IP 限制、速率限制和有效期。
6. Fast 模式、双发保护、首字等待时间和第二路策略属于高级调度选项，新手先保持默认。
7. 点击“创建”，立即安全保存完整密钥。

安全提醒：API Key 的权限类似密码。不要发到群聊、截图、GitHub 仓库或前端网页中；不要硬编码到公开代码。怀疑泄露时立即禁用或删除旧 Key，并创建新 Key。

七、CC Switch 一键导入（推荐）

如果你使用 CC Switch 管理 Claude Code、Codex CLI、Gemini CLI 等客户端，不需要手工拼写配置，站点已经提供一键导入。

导入前准备

• 从 CC Switch 可信的官方发布渠道下载安装，首次启动一次并允许系统完成协议注册；
• CC Switch 已注册 ccswitch:// 系统协议；判断方法是点击站内“一键导入”后，浏览器能弹出“打开 CC Switch”提示；
• 站内已创建并正确分组的 API Key。

具体步骤

1. 打开站点“API 密钥”页面。
2. 找到要使用的密钥，点击该密钥右侧的“使用”。

3. 在弹窗中进入默认的“CC Switch 导入”页签。
4. 确认页面显示的 API Base URL、API Key 和模型信息。
5. 按密钥分组选择对应客户端：Anthropic 分组用于 Claude Code；OpenAI 分组用于 Codex CLI；Gemini 分组用于 Gemini CLI；GLM 分组用于 Claude Code（GLM）。
6. 点击“一键导入”。浏览器询问是否打开外部应用时，选择允许打开 CC Switch。

7. 在 CC Switch 中检查供应商名称、Endpoint、API Key 和模型，确认后保存并切换到新供应商。
8. 回到终端启动对应客户端，发送一句简单问题验证。

导入链接会携带供应商名称、Endpoint、API Key、用量脚本和自动刷新间隔等信息。OpenAI 分组会使用带 /v1 的 Endpoint；Anthropic 分组使用不带 /v1 的地址。密钥页面旁边还提供“复制链接”，适合浏览器没有直接唤起 CC Switch 时手动粘贴。该链接包含 API Key，不要发送给他人，也不要粘贴到群聊、网盘或公开网页；使用后可及时清理剪贴板。

CC Switch 导入失败怎么办？

• 提示“请先分配分组”：编辑或重新创建密钥，为它选择对应平台分组。
• 点击无反应：确认 CC Switch 已从可信官方发布渠道安装并启动过，且系统已注册 ccswitch://。也可点击“复制链接”，将完整的 ccswitch:// 链接粘贴到浏览器地址栏并打开，再允许浏览器唤起 CC Switch。
• 导入后 401：Key 可能复制不完整、被禁用、过期或额度耗尽。
• 模型不存在：前往模型广场复制该分组真正支持的模型 ID。
• 接口路径错误：OpenAI/Codex 应使用 https://qwqzy.top/v1；Anthropic/Claude Code 使用 https://qwqzy.top。

八、配置普通聊天客户端

Chatbox、NextChat、OpenCat 等应用的字段名称略有区别，但思路一致：

1. 提供商选择“OpenAI”或“OpenAI Compatible”；
2. API Key 填写刚创建的 sk-...；
3. Base URL 填写 https://qwqzy.top/v1。如果客户端会自动补 /v1，则按客户端提示填写 https://qwqzy.top，避免重复成 /v1/v1；
4. 模型填写从模型广场复制的准确模型 ID；
5. 保存后新建会话，发送“你好，请只回复连接成功”测试。

九、Cursor、Claude Code、Cline / Roo Code

Cursor

1. 打开 Settings → Models；
2. 在 OpenAI API Key 中填入本站 Key；
3. 启用 Override OpenAI Base URL，填入 https://qwqzy.top/v1；
4. 添加模型广场中当前可用的模型 ID；
5. 使用自定义 Base URL 时，Cursor 官方 Web Search 可能受影响，遇到问题可先关闭联网搜索再测试。

Claude Code

如果不使用 CC Switch，可在 shell 环境中设置：

export ANTHROPIC_BASE_URL=https://qwqzy.top
export ANTHROPIC_API_KEY=sk-your-key

保存到 ~/.zshrc 或 ~/.bashrc 后，重新加载配置并运行 claude。Windows 用户可通过系统环境变量或 CC Switch 配置。注意 Anthropic 地址末尾没有 /v1。

Cline / Roo Code

• 使用 OpenAI Compatible：Base URL 为 https://qwqzy.top/v1；
• 使用 Anthropic（更适合 Prompt Cache）：Base URL 为 https://qwqzy.top，不要加 /v1；
• Model ID 必须与密钥分组支持的模型完全一致。

Prompt Cache 未生效时，优先检查 Provider 是否选为 Anthropic，以及 Base URL 是否误加了 /v1。

十、开发者最小调用示例

curl

curl https://qwqzy.top/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"请替换为模型广场中的模型ID","messages":[{"role":"user","content":"你好"}]}'

Python

先安装依赖：pip install openai

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://qwqzy.top/v1",
)

response = client.chat.completions.create(
    model="请替换为模型广场中的模型ID",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

Node.js

先在项目中安装依赖：npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.QWQ_API_KEY,
  baseURL: "https://qwqzy.top/v1",
});

const result = await client.chat.completions.create({
  model: "请替换为模型广场中的模型ID",
  messages: [{ role: "user", content: "你好" }],
});
console.log(result.choices[0].message.content);

上面的 curl 使用 Bash 的反斜杠换行语法。Windows PowerShell 可改成单行命令或使用反引号换行；CMD 可改用单行或脱字符。生产环境请把 Key 放入环境变量或密钥管理服务，不要提交到 Git。

十一、查看日志、费用与状态

调用后进入“请求日志”，可查看 Key、模型、渠道、类型、状态、尝试次数、TTFB、TPS、总用时、输入/输出 Token、缓存读写、费用、倍率、调用路径和 User-Agent。

如果突然变慢或出现 5xx，可打开状态监控，查看相关分组最近的可用率、首包延迟和请求成功率。低价分组不一定始终最稳定，必要时可换用更稳定的分组。需要人工帮助时，可登录控制台后使用顶部“联系”入口。

十二、常见问题

401 Unauthorized

检查 Key 是否完整、前后是否有空格、是否被禁用或过期。余额或密钥额度耗尽时，具体状态码可能因接口而异，不应只根据 401 判断；请同时查看响应正文和站内请求日志。

404 或模型不存在

检查模型 ID 是否逐字一致，并确认密钥所选分组支持该模型。不要照搬过时教程里的模型名，应从当前模型广场复制。

余额充足但仍无法调用

检查密钥自身的额度限制、有效期、IP 限制、速率限制和分组；余额充足不代表每个 Key 都一定可用。

出现 429

通常表示并发或速率受限。降低并发、稍后重试，或检查账户并发数与密钥速率设置。不要用无限重试循环。

出现 503

可能是当前分组号池或上游暂时不可用。先看状态监控和分组说明，稍后重试或更换稳定分组。

Base URL 应不应该带 /v1？

OpenAI Compatible 通常带 /v1；Anthropic 原生不带。还要留意客户端是否会自动补路径，避免重复。

费用和预想不同

在请求日志中核对模型、Token、缓存、倍率和计费模式。模型广场展示可能是渠道价或 GitHub 公价参考，最终以实际请求结算为准。

十三、首次使用检查清单

• 已登录，并阅读、同意平台条款；
• 账户有可用余额、兑换额度或试用权限；
• 已在模型广场确认模型 ID、价格和可访问分组；
• API Key 选择了正确分组，并设置合理额度上限；
• OpenAI Base URL 使用 https://qwqzy.top/v1；
• Anthropic Base URL 使用 https://qwqzy.top；
• CC Switch 用户通过“使用 → CC Switch 导入 → 一键导入”完成配置；
• 已用一句简单提示词测试；
• 已在请求日志确认状态、模型和费用；
• 已安全保存 Key，未将其公开或提交到代码仓库。

完成以上步骤后，你就已经掌握 QwQのapi 的完整基础流程。模型、分组、价格和功能会继续更新，使用前建议再次查看模型广场、官方教程和状态监控。

十四、官方支持与服务边界

遇到问题时先做什么

1. 查看“请求日志”中的状态码、响应信息、模型、分组、尝试次数和调用时间。
2. 查看状态监控，确认目标分组是否有可用率或延迟异常。
3. 核对 Key 的状态、额度、有效期、IP 限制和速率限制。
4. 仍无法解决时，登录控制台，通过页面顶部“联系”入口寻求人工支持。

联系支持时请提供

• 问题发生的准确时间和时区；
• 使用的客户端、接口类型、模型 ID 和分组名称；
• HTTP 状态码、响应正文和请求日志中的可公开字段；
• 可复现步骤，以及经过脱敏的截图；
• 充值或账务问题可提供订单号、支付时间和金额，但应遮挡无关支付隐私。

不要提供：完整 API Key、账号密码、登录 Cookie、CC Switch 导入链接、支付密码或其他私密凭证。若怀疑 Key 已泄露，请立即在“API 密钥”页面禁用或删除并重新创建。

服务边界

• 模型、渠道、分组、价格、倍率和可用性会动态变化，历史截图和本文示例不构成长期价格或容量承诺。
• 第三方客户端可能因自身升级而改变字段或行为。平台可协助定位 API 连接问题，但第三方界面和功能应同时参考其当前版本说明。
• 充值、退款、账户与其他服务事项以站点当前条款、付款页面和人工支持的最终确认为准；本文不替代相关条款。
• 故障排查应优先依据实时响应、请求日志和状态监控，不要仅凭单一状态码判断原因。

十五、术语表