<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# QQ 信息

> 通过 QQ 号查询昵称、QQ 邮箱、QQ 空间链接，并生成 4 种尺寸的头像直链 URL（s40/s100/s140/s640）。

• 严格 5-11 位数字校验（防上游字符串截断引起的号码错位）
• 安全增强：上游返回的 QQ key 必须与请求严格一致，否则视为未查询到
• 错误兼容：自动识别上游错误响应（_Callback({error:...})）和正常响应（portraitCallBack(...)）
• 编码兜底：腾讯接口历史输出 GBK 含中文昵称时自动转 UTF-8
• 多尺寸头像：avatars 对象内含 s40/s100/s140/s640 四种尺寸 URL，前端 `<img src={data.avatars.s640}>` 直接用

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `qq` |
| 接口名称 | QQ 信息 |
| 接口地址 | `https://v1.apizero.cn/api/qq` |
| 请求方法 | `GET` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 10 req/s |
| 每日免费额度 | 300 次（已认证用户） |
| 匿名每日额度 | 50 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 50 次、QPS 3；登录用户每日 300 次、QPS 10（全部免费）。命中缓存（6 小时）不计入上游配额。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `qq` | `string` | 是 | 5-11 位 QQ 号码（纯数字） | `88888888` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时可省略（每日 50 次免费） | `Bearer sk_live_xxxxxxxxxxxxxx` |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/qq?qq=88888888&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `qq` | `string` | 查询的 QQ 号（原样回传） | — |
| `name` | `string` | QQ 昵称；用户未设置或腾讯未开放时为空字符串 | — |
| `mail` | `string` | QQ 邮箱地址（qq + @qq.com 拼接，未验证开通状态） | — |
| `qzone` | `string` | QQ 空间个人主页 URL | — |
| `avatars` | `object` | 多尺寸头像直链对象 | — |
| `avatars.s40` | `string` | 40×40 头像直链 URL（小图标） | — |
| `avatars.s100` | `string` | 100×100 头像直链 URL（列表用） | — |
| `avatars.s140` | `string` | 140×140 头像直链 URL（中等） | — |
| `avatars.s640` | `string` | 640×640 头像直链 URL（高清，原图） | — |
| `is_found` | `boolean` | 是否查询到该 QQ：true=找到 / false=号码不存在或已注销 | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "qq": "88888888",
        "name": "腾讯客服",
        "mail": "88888888@qq.com",
        "qzone": "https:\/\/user.qzone.qq.com\/88888888",
        "avatars": {
            "s40": "https:\/\/q1.qlogo.cn\/g?b=qq&nk=88888888&s=40",
            "s100": "https:\/\/q1.qlogo.cn\/g?b=qq&nk=88888888&s=100",
            "s140": "https:\/\/q1.qlogo.cn\/g?b=qq&nk=88888888&s=140",
            "s640": "https:\/\/q1.qlogo.cn\/g?b=qq&nk=88888888&s=640"
        },
        "is_found": true
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误：qq 缺失或格式无效（应为 5-11 位纯数字） |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5020` | `—` | 上游 HTTP 失败 |
| `5021` | `—` | 上游响应格式异常或 jsonp 解析失败 |

## 9. 变更日志

- **1.0.0** (2026-05-06)
  - 首次上线，对接腾讯 cgi_get_portrait.fcg 公开接口
  - QQ 号严格 5-11 位数字校验，防上游字符串截断引起的号码错位
  - 安全增强：上游返回 key 必须与请求 QQ 严格一致，否则返回 is_found=false
  - jsonp 响应正则解析（兼容 portraitCallBack/_Callback 两种前缀），不再硬编码 substr
  - GBK/GB18030 编码兜底，自动转 UTF-8，避免中文昵称乱码
  - 响应字段标准化：avatars 嵌套对象（s40/s100/s140/s640），前端直接 .s640 取高清图
  - 不存在或已注销的 QQ 返回 is_found=false（缓存 10 分钟），其他成功结果缓存 6 小时
  - 去除源码 type=img 二进制透传模式（QQ 头像 URL 本身公开，前端直接 <img src=avatars.s640> 即可）

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/qq`

Source: `https://apizero.cn/aidocs/qq/raw.md`
Last updated: 2026-05-11T16:14:07+08:00