API 参考 · v1

批量查询 Twitter 账号状态

传入一批用户名,逐个返回头像、注册时间、帖子数、关注数、粉丝数、认证状态。需要哪些字段,在请求里勾选即可,少查少耗。

Base URL https://你的域名

登录分级

未登录用户只能通过网页工具查询单个账号;批量查询需要登录后生成 API 密钥,用 Authorization: Bearer <key> 调用本接口。

认证 · 获取密钥

登录后在「控制台 → API 密钥」生成一个密钥(明文只显示一次)。所有 API 请求通过 Authorization 头携带该密钥。

Authorization 头

# 所有请求都带上 Bearer 密钥
curl https://你的域名/api/v1/twitter/query \
  -H "Authorization: Bearer mg_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

密钥即权限

密钥只在服务端使用,切勿写进前端或公开仓库。可在控制台随时吊销。

批量查询

POST/api/v1/twitter/query

查询一批 Twitter 用户名,一次返回全部结果。用户名自动去 @ 前缀、去重、跳过非法格式;结果顺序与传入顺序一致。

参数	类型	说明
usernames 必填	string[]	用户名数组,每项 1–15 位字母/数字/下划线。单次最多 `2000` 个。
fields 可选	string[]	要返回的字段,从字段表中选。不传默认返回全部基础字段。

POST /api/v1/twitter/query

curl -X POST https://你的域名/api/v1/twitter/query \
  -H "Authorization: Bearer mg_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["elonmusk", "@jack", "nonexistent_user_12345"],
    "fields": ["avatar", "name", "createdAt", "posts", "followers"]
  }'

const res = await fetch("https://你的域名/api/v1/twitter/query", {
  method: "POST",
  headers: {
    "Authorization": "Bearer mg_live_xxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    usernames: ["elonmusk", "@jack"],
    fields: ["avatar", "createdAt", "followers"]
  })
});
const { results } = await res.json();

200 OK

{
  "total": 3,
  "count": 3,
  "fields": ["avatar", "createdAt", "followers"],
  "results": [
    {
      "username": "elonmusk",
      "ok": true,
      "data": {
        "avatar": "https://pbs.twimg.com/profile_images/…jpg",
        "name": "Elon Musk",
        "createdAt": "2009-06-02",
        "posts": 39872,
        "followers": 201538745
      }
    },
    {
      "username": "jack",
      "ok": true,
      "data": {
        "avatar": "https://pbs.twimg.com/profile_images/…jpg",
        "createdAt": "2006-07-15",
        "followers": 6531002
      }
    },
    {
      "username": "nonexistent_user_12345",
      "ok": false,
      "error": "账号不存在或无法查询"
    }
  ]
}

注意:请求中未勾选的字段不会出现在返回的 data 中;username 与 ok 恒返回,ok=false 时附带 error 说明失败原因。

返回字段

字段	类型	说明
avatar	string\|null	头像图片 URL,可直接用于 `<img>` 或下载。
name	string	显示昵称。
createdAt	string	注册时间,统一格式 `YYYY-MM-DD`。
posts	number	帖子数(全部推文数)。
following	number	关注数。
followers	number	粉丝数。
verified	boolean	是否认证(蓝标或企业标)。

速率限制

限制项	数值	说明
单次批量上限	2000 个	单次请求最多 2000 个用户名。
未登录	1 个	网页工具未登录仅可查询单个账号;API 必须带密钥。
请求频率	120 次/分钟	同一密钥每分钟最多 120 次 API 调用。
结果缓存	5 分钟	同一账号、同一字段组合 5 分钟内重复查询命中缓存,不重复消耗查询次数。

服务器会根据负载动态调节并发,繁忙时请求会在队列中稍作等待。

错误码

状态码	含义	处理建议
400	invalid_request	请求参数不合法(空用户名 / 超过 2000 个 / 格式错误)。
401	unauthorized	缺少或错误的 API 密钥。
403	invalid_request	批量查询需要登录(未登录请求多于 1 个账号),返回体带 `needLogin: true`。
429	rate_limited	请求频率超限,稍后重试。
500	server_error	服务器内部错误,查看错误消息重试。
503	not_configured	服务器尚未配置 Twitter API,联系管理员。

错误响应统一为 {"error": {"code": "…", "message": "…"}}。单个账号的失败不会让整批请求失败 —— 失败的账号在 results 中以 ok: false 返回并附 error 原因。