适用场景
日常开发中，无论是搭建用户绑定、好友推荐、评论区展示，还是简单的信息校验，经常需要根据QQ号获取对应的基础资料。QQ信息API（/api/qq）提供了一个轻量级的查询入口：输入合法的QQ号码，即可拿到昵称、QQ邮箱、QQ空间链接，以及四组不同尺寸的头像直链（40px、100px、140px、640px）。前端可以直接将图片地址绑定到<img />标签，无需额外处理。
本文不讨论复杂的业务架构，而是聚焦“最小可运行示例”——任何开发者拿到API后，最先要做的就是打开终端，用一条最短的命令验证接口连通性。下面我们会从参数构造、鉴权、返回解析到异常处理，一步步跑通整个流程。
接口能力边界
请求方式
- 方法：GET
- 地址：
https://v1.apizero.cn/api/qq - QPS 限制：10次/秒（超过限制可能返回限流错误，请合理设计重试逻辑）
- 字符集：输出统一为 UTF-8；腾讯上游历史数据中存在 GBK 编码的中文昵称，接口会自动识别并转码
核心能力
- 严格号码校验：只接受5-11位纯数字的QQ号码，不符合此范围的参数会直接返回参数错误。这避免了上游接口因字符串截断而返回错误号码。
- 安全增强：返回的
qqkey 必须与请求的qq参数严格一致，否则视为未查询到。这是防御某些上游返回错误缓存的有效手段。 - 错误兼容：上游腾讯接口有时返回
_Callback({error:...})格式的错误，有时返回portraitCallBack(...)格式的正常数据。该接口会自动识别两种格式，提取有效信息。 - 头像多尺寸：
avatars对象中包含s40、s100、s140、s640四个字段，分别对应40、100、140、640像素的方形头像直链。注意：头像图片是腾讯 CDN 资源，加载速度通常较快，但少数冷门号码可能返回默认企鹅头像。
参数与鉴权
Query 参数
| 参数名 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|
qq | 是 | string | 5-11 位纯数字QQ号码。必须为数字字符串，不允许空格或非数字字符。 | 88888888 |
鉴权方式
该接口同时支持以下两种鉴权方式（任选其一即可）：
- Authorization 头：格式
Bearer sk_live_xxxxxxxxxxxxxx - X-API-Key 头：格式
sk_live_xxxxxxxxxxxxxx
两种方式等效。为了最小可运行示例，本文使用X-API-Key头（因为 curl 中更简洁）。如果你尚未申请 API Key，也可以尝试匿名请求（每日有一定配额，但具体额度以文档为准）。
⚠️ 注意：生产环境中请将 API Key 存放在环境变量或密钥管理服务中，切勿硬编码到代码仓库。
最小可运行 curl 示例
下面是最精简的可复制 curl 命令。假设你已经将 API Key 设为环境变量APIZERO_API_KEY，直接复制到终端即可执行：
curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/qq?qq=10001"如果你没有 API Key，也可以临时改用无鉴权请求（某些 endpoints 允许匿名，但这里建议用 Key 确保成功率）：
curl -sS \ -X GET \ "https://v1.apizero.cn/api/qq?qq=10001"执行后如果得到类似下面的 JSON，即表示接口连通成功：
{ "code": 0, "data": { "avatars": { "s100": "https://q1.qlogo.cn/g?b=qq&nk=10001&s=100", "s140": "https://q1.qlogo.cn/g?b=qq&nk=10001&s=140", "s40": "https://q1.qlogo.cn/g?b=qq&nk=10001&s=40", "s640": "https://q1.qlogo.cn/g?b=qq&nk=10001&s=640" }, "is_found": true, "mail": "10001@qq.com", "name": "QQ号码10001", "qq": "10001", "qzone": "https://user.qzone.qq.com/10001" }, "msg": "成功", "request_id": "abc123def456" }注意：10001是一个非常早期的 QQ 号码（实际上可能属于腾讯官方账号），输出的昵称会因数据源不同而不同。如果你的 API Key 正确但返回code != 0，请检查qq参数是否合法。
返回值解读
完整的响应结构字段含义如下：
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 业务状态码。0表示成功；非0表示错误（见错误码表）。 |
msg | string | 状态描述文本，成功时为“成功”，错误时为具体错误原因。 |
request_id | string | 请求唯一标识，可用于后续排查日志。 |
data | object | 成功时存在，包含查询结果。 |
data.qq | string | 查询的QQ号，与请求参数一致。 |
data.name | string | 昵称。可能为空字符串或默认名称。 |
data.mail | string | QQ邮箱地址，格式qq号@qq.com。 |
data.qzone | string | QQ空间链接，格式https://user.qzone.qq.com/qq号。 |
data.is_found | boolean | 是否找到真实用户信息。如果为false，name可能为默认值。 |
data.avatars | object | 头像直链集合，包含s40、s100、s140、s640四个字段。 |
关于is_found的说明
- 当
is_found = true时，表示腾讯上游确认了该号码存在且包含有效用户数据。 - 当
is_found = false时，表示该号码可能未被准备、被冻结或数据不可用，但接口仍会根据缓存返回一些基础信息（如默认昵称、默认头像）。生产环境中建议根据此字段判断是否展示用户信息。
头像直链的使用
avatars中的 URL 可以直接用于<img>标签，例如：
<img src="https://q1.qlogo.cn/g?b=qq&nk=10001&s=640" alt="头像" />需要注意的是，头像图片是腾讯 CDN 资源，不保证永久有效。建议定期刷新或提供 fallback 头像。另外，s参数值必须为 40、100、140、640 之一，其他数值可能导致 404 或重定向。
常见错误与处理
错误码列表
| code | msg 含义 | 排查方向 |
|---|---|---|
| 1001 | 参数错误：qq 必须为5-11位数字 | 检查qq参数是否纯数字且长度合法 |
| 1002 | 鉴权失败：无效的 API Key | 检查X-API-Key或Authorization头是否正确 |
| 1003 | 上游服务异常 | 等待一段时间后重试，或联系接口提供方 |
| 1004 | 请求频率超过限制 | 减小并发量或加入退避重试 |
| -1 | 系统内部错误 | 建议附带request_id反馈给技术支持 |
上游兼容性注意
由于接口会对上游的 GBK 编码进行转码，极少数情况下转码可能不完美，例如繁体中文或特殊符号可能出现乱码。建议在前端对name做一层简单的 unicode 净化。
cURL 常见问题
- Mac/Linux 下：curl 默认输出到终端，加
-sS可以静默且显示错误。 - Windows 下：推荐使用 Git Bash 或 WSL；使用 cmd 时注意变量引用方式：
%APIZERO_API_KEY%。 - 代理环境：如果使用代理，curl 可能无法直连，请添加
--noproxy '*'或配置正确的代理。
工程化注意事项
- 缓存策略：QQ 昵称和头像变更频率很低，可以缓存结果 1 小时以上，减少 API 调用。注意缓存 key 使用
qq号，并定期失效。 - 头像尺寸选择：列表页推荐使用
s40或s100（节省带宽），详情页使用s640（清晰度高）。 - 参数校验前置：在业务代码中先校验
qq是否为5-11位纯数字，避免无效请求浪费配额。 - 错误重试：遇到
1003上游异常或1004限流时，采用指数退避（如 1s、2s、4s 重试，最多3次）。 - 日志记录：每次请求记录
request_id、qq、code、耗时，便于排查线上问题。 - 保密 API Key：前端代码中绝对不要暴露 API Key，服务端调用时建议通过环境变量或配置中心读取。
- 匿名调用限制：如果你使用匿名请求（不带 Key），注意每日调用量有限，且 QPS 可能更低。正式项目请申请 Key 并妥善保管。
参考文档
- QQ信息 API 官方文档
- 原始接口文档 Markdown
 agent和组件)