JavaScript 调用 QQ 信息接口：头像直链和 QQ 空间链接展示

做用户资料补全、社交账号展示、头像回填或开发者工具箱时，经常会遇到一个轻量需求：输入一个 QQ 号，返回基础资料和头像地址。自己处理这类数据时，需要考虑号码校验、昵称编码、头像尺寸、QQ 空间链接等细节。
qq 接口把这些信息整理成了一个标准 GET API。开发时只需要传入 QQ 号，就能拿到 QQ 昵称、QQ 邮箱、QQ 空间 URL，以及 40、100、140、640 四种尺寸的头像直链。

官方页面：https://apizero.cn/marketplace/qq

接口能做什么

qq 接口的核心能力很直接：根据 QQ 号查询公开基础信息，并返回适合前端展示的头像地址。

它会返回：

QQ 号
QQ 昵称
QQ 邮箱
QQ 空间链接
多尺寸头像 URL
是否查询到该 QQ

这类结构很适合直接接到用户资料页、客服后台、账号查询工具、头像预览组件里。

请求方式

接口地址：

text 复制代码

GET https://v1.apizero.cn/api/qq

请求参数：

参数	类型	必填	说明
`qq`	string	是	5 到 11 位纯数字 QQ 号

请求头：

Header	说明
`Authorization`	API Key 鉴权头，可按项目接入方式配置

最简单的请求示例：

bash 复制代码

curl "https://v1.apizero.cn/api/qq?qq=88888888"

带鉴权头的请求示例：

bash 复制代码

curl "https://v1.apizero.cn/api/qq?qq=88888888" \
  -H "Authorization: Bearer YOUR_API_KEY"

返回字段

接口返回结构比较适合前端直接消费：

字段	类型	说明
`qq`	string	查询的 QQ 号
`name`	string	QQ 昵称
`mail`	string	QQ 邮箱地址
`qzone`	string	QQ 空间个人主页
`avatars`	object	多尺寸头像对象
`avatars.s40`	string	40×40 头像
`avatars.s100`	string	100×100 头像
`avatars.s140`	string	140×140 头像
`avatars.s640`	string	640×640 高清头像
`is_found`	boolean	是否查询到该 QQ

返回示例

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": "mpl8a642714dcb60"
}

如果页面上只需要头像，一般优先使用：

text 复制代码

data.avatars.s100

如果是资料详情页或高清头像预览，可以使用：

text 复制代码

data.avatars.s640

Python 调用示例

下面是一个最小可用的 Python 示例：

python 复制代码

import requests

url = "https://v1.apizero.cn/api/qq"
params = {
    "qq": "88888888"
}
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

resp = requests.get(url, params=params, headers=headers, timeout=10)
result = resp.json()

data = result["data"]

print("QQ:", data["qq"])
print("昵称:", data["name"])
print("邮箱:", data["mail"])
print("空间:", data["qzone"])
print("高清头像:", data["avatars"]["s640"])

如果要把接口接到后端服务里，可以封装成一个函数：

python 复制代码

import requests

def get_qq_profile(qq: str) -> dict:
    resp = requests.get(
        "https://v1.apizero.cn/api/qq",
        params={"qq": qq},
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        timeout=10,
    )
    payload = resp.json()
    return payload["data"]


profile = get_qq_profile("88888888")
avatar = profile["avatars"]["s100"]

这样业务层只需要关心 profile 对象，不用自己拼头像地址和空间地址。

JavaScript 调用示例

前端或 Node.js 中也可以直接请求：

javascript 复制代码

const params = new URLSearchParams({
  qq: "88888888",
});

const res = await fetch(
  `https://v1.apizero.cn/api/qq?${params.toString()}`,
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  }
);

const json = await res.json();
const profile = json.data;

console.log(profile.qq);
console.log(profile.name);
console.log(profile.mail);
console.log(profile.qzone);
console.log(profile.avatars.s640);

如果是浏览器页面展示，可以这样渲染头像：

html 复制代码

<div class="profile">
  <img id="avatar" alt="QQ avatar" />
  <div id="name"></div>
  <a id="qzone" target="_blank">QQ 空间</a>
</div>

<script>
  async function renderQQProfile(qq) {
    const params = new URLSearchParams({ qq });
    const res = await fetch(`https://v1.apizero.cn/api/qq?${params}`);
    const json = await res.json();
    const data = json.data;

    document.querySelector("#avatar").src = data.avatars.s100;
    document.querySelector("#name").textContent = data.name || data.qq;
    document.querySelector("#qzone").href = data.qzone;
  }

  renderQQProfile("88888888");
</script>

前端展示建议

头像尺寸可以按场景选择：

场景	推荐字段
表格小头像	`avatars.s40`
用户列表	`avatars.s100`
资料卡片	`avatars.s140`
详情页或预览	`avatars.s640`

如果昵称为空，可以用 QQ 号作为兜底展示：

javascript 复制代码

const displayName = data.name || data.qq;

邮箱字段是标准拼接格式：

javascript 复制代码

const mail = data.mail; // 88888888@qq.com

空间链接可以直接用于跳转：

javascript 复制代码

const qzoneUrl = data.qzone;

适用场景

用户资料补全

用户输入 QQ 号后，可以自动补全头像、邮箱和空间链接，减少用户手动填写成本。

客服后台

客服系统里经常需要展示用户社交账号信息。接入该接口后，可以用 QQ 号快速生成资料卡片。

开发者工具箱

很多工具站会提供 QQ 头像查询、QQ 邮箱生成、QQ 空间跳转等能力。qq 接口可以作为一个完整的资料查询模块。

评论和社区系统

在轻量社区或内部工具里，可以根据 QQ 号生成默认头像，提升资料展示效果。