XiaoApi 开放中台接入指引
XiaoApi 是面向 AI 智能体应用、社媒大数据研发与企业内容运营的高性能全域新媒体数据开放中台。
业务方无需为不同平台分别对接各异的爬虫协议或维护复杂的反爬代理池，只需通过统一网关 POST /open/query 即可按需调度 6 大平台 68+ 款实时数据能力。
统一调用拓扑链路 (Single Gateway Pipeline)
访问凭证与 X-API-KEY
所有对外接口均采用基于密钥的鉴权机制。在请求中必须提供已授权的访问 KEY。
推荐方式：HTTP Request Header
在每个 HTTP 请求的请求头中附带 X-API-KEY：
X-API-KEY: xa_live_89f91a24d0bc7e38
调试辅助：URL Query Parameter
在浏览器或简易调试工具中，可临时作为 URL 参数传递：
https://xiaoapi.com/open/query?access_key=xa_live_89f91a24d0bc7e38
⚠️ 生产环境请务必使用 Request Header，避免密钥被浏览器历史或代理日志明文记录。
HTTP 状态码约定与自愈契约
系统严格遵循标准 HTTP 响应码体系，每个错误响应均返回语义化自愈原因，便于客户端自动做退避重试或降级处理。
| 状态码 | 原因描述 | 调用端推荐应对策略 | 配额扣减 |
|---|---|---|---|
| 200 OK | 请求成功并返回数据 | 正常消费响应，可从 meta.from_cache 判断缓存命中 | 扣减 1 次 |
| 400 Bad Request | 缺少必填参数 / JSON 格式错 | 请核对请求参数名称，必填校验不通过时绝不白扣配额 | 不扣配额 |
| 401 Unauthorized | 缺少或无效的 X-API-KEY | 请检查控制台中签发的 KEY 状态或重新生成访问令牌 | 不扣配额 |
| 403 Forbidden | KEY 停用 / 过期 / 接口未授权 | 前往管理控制台检查该 KEY 的允许接口白名单（allow_iids） | 不扣配额 |
| 429 Rate Limit | 触发分钟频控或每日额度耗尽 | 建议采用指数退避算法暂停调用，或联系技术支持提升配额 | 不扣配额 |
| 502 Bad Gateway | 上游节点故障且无可降级缓存 | 系统正在自动剔除失效节点并切换信道，可于 3 秒后重试 | 不扣配额 |
SingleFlight 并发去重与多级缓存防雪崩
面对突发高并发请求与爆款事件，XiaoApi 网关内置 SingleFlight 机制与双层缓存，确保系统不击穿、上游不超频、调用方毫秒级响应。
当同时有 100 个请求查询同一作者或同一条热榜时，Swoole 协程锁自动合并并发请求，只向底层回源 1 次，其余 99 个请求静默等待共享结果。彻底避免上游配额瞬时浪费。
即使上游第三方平台遭遇突发风控或网络波动，XiaoApi 自动启动保底容灾策略，优先返回最近历史固化数据并标记 meta.stale: true，确保业务下游永不因短暂故障宕机中断。
Model Context Protocol (MCP) 原生接入
XiaoApi 原生支持 Anthropic 主导的 Model Context Protocol 协议。无需编写接口封装代码，即可把全域 6 大平台数据感知能力挂载为 Claude Desktop、Cursor、Dify、Coze 的智能体工具箱。
{
"mcpServers": {
"xiaoapi-datahub": {
"command": "npx",
"args": ["-y", "@xiaoapi/mcp-server"],
"env": {
"XIAOAPI_KEY": "xa_live_89f91a24d0bc7e38",
"XIAOAPI_DEFAULT_PLATFORMS": "gzh,xhs,douyin,bili"
}
}
}
}
全域所有平台、分类、榜单与详情的唯一对外统一查询入口。支持精确指定接口标识（iid）或按平台+分类（platform + category）智能调度首选库。
Request Headers 请求头
| Header | 类型 | 必填 | 说明 |
|---|---|---|---|
| X-API-KEY | string | 是 | 访问授权凭据，在管理控制台「对外开放」中签发生成 |
| Content-Type | string | 是 | 固定为 application/json |
Request Body 请求体参数 (JSON)
| 字段名 | 类型 | 必填 | 说明与示例 |
|---|---|---|---|
| iid | string | 二选一 | 具体接口唯一标识，如 gzh.account_info.wide.accountInfo。与 platform+category 二选一提供 |
| platform | string | 二选一 | 目标平台标识：gzh (公众号) / xhs (小红书) / douyin (抖音) / bili (B站) |
| category | string | 二选一 | 功能分类：account_info, work_detail, account_works, rank 等 |
| params | object | 是 | 目标接口对应的业务参数键值对对象（如微信号、文章ID、关键词等） |
| ignore_cache | integer | 否 | 是否强制跳过缓存直接回源采集（传 1 表示强制刷新，默认 0 走智能缓存） |
Response 响应体契约 (JSON)
{
"code": 200,
"data": {
/* 业务数据主体 (账号信息 / 作品详情 / 榜单数组) */
},
"meta": {
"iid": "gzh.account_info.wide.accountInfo",
"from_cache": true, // true: 本次直接命中二级 Redis 缓存(耗时 <2ms)
"stale": false, // true: 当上游不可用时自动降级返回的陈旧保底数据
"body_omitted": false, // 超大响应体保护
"as_of": "2026-10-09 12:00:00", // 数据采集固化时间
"reason": "cache_hit_redis",
"usage": {
"daily_used": 142, // 今日已消耗请求次数
"daily_limit": 10000, // 今日总配额上限
"rate_limit_per_min": 60 // 每分钟并发频次限制
}
}
}
返回当前密钥允许调用的接口全量清单、入参字段要求及说明文档，供业务端动态构建表单或模型自主探索调用。
{
"code": 200,
"data": [
{
"iid": "gzh.rank.ten_w_reading",
"name": "公众号10W+文章推荐",
"platform": "gzh",
"category": "rank",
"library": "none",
"params": [
{ "name": "type", "type": "string", "required": true, "desc": "类型" },
{ "name": "startDate", "type": "string", "required": true, "desc": "开始日期 2026-10-09" },
{ "name": "endDate", "type": "string", "required": true, "desc": "结束日期 2026-10-09" }
]
}
]
}
微信公众号平台能力 (WeChat Official Accounts)
公众号 10w+ 当日爆款文章推荐
实时扫描全网微信公众号阅读数突破 10w+ 的头部热门图文，输出标题、发布作者、发布时间与阅读热度指标。
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| type | string | 必填 | 文章分类类型 | 1 |
| startDate | string | 必填 | 统计开始日期 | 2026-10-09 |
| endDate | string | 必填 | 统计结束日期 | 2026-10-09 |
公众号阅读增长榜单
监测短周期内阅读数出现爆发性增长的公众号文章，快速捕捉黑马传播热点与突发社会议题。
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| rankDate | string | 必填 | 榜单日期 | 2026-10-09 |
公众号原创爆款文章推荐
过滤搬运与转载，纯净呈现具有微信官方原创认证标志的高质量深度好文。
获取公众号账号信息 (广域库)
根据微信号（account）、原始ID（wxId）或 bizInfo 三选一查询公众号基础画像、头像、二维码与主体认证信息。
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| account | string | 三选一 | 微信号 | duhaoshu |
| wxId | string | 三选一 | 公众号 gh_ 原始ID | gh_5c7e8b7f586b |
| bizInfo | string | 三选一 | 微信 __biz 采集ID | MjM5MDMyMzg2MA== |
获取公众号账号作品列表
分页拉取该公众号历史发布的推文列表，包含图文位置（头条/次条）、标题、摘要、封面与初始点赞数。
根据作品uuid获取公众号作品详情
传入中台作品全局唯一 uuid，返回包含阅读量、在看数、点赞数与正文干净文本的结构化详情。
根据微信图文链接实时解析正文
传入任何公开的 mp.weixin.qq.com/s/... 文章 URL，毫秒级解析标题、正文 HTML/Markdown 与高清插图列表。
小红书数据接口能力 (Xiaohongshu Notes & Bloggers)
小红书黑马低粉爆文榜
专注挖掘粉丝数 <5000 却拿下万赞以上爆款互动笔记，排除博主自身粉丝基础干扰，帮助创作者精准提炼最具穿透力的内容选题与首屏视觉钩子。
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| category | string | 必填 | 垂类赛道 | 美妆护肤 |
| rankDate | string | 必填 | 榜单日期 | 2026-10-09 |
小红书每日爆款笔记榜单
实时汇总各垂类赛道当日最高收藏与点赞增量的热门笔记。
小红书七日长尾爆款笔记榜
跟踪长达 7 天持续获得推荐流曝光的常青优质笔记，提炼长效复利内容特征。
获取小红书博主账号信息 (优质库)
查询博主粉丝数、获赞与收藏总数、官方认证身份、蒲公英商务标签与主页简介。
查询小红书账号作品列表
分页拉取该小红书博主发布的图文与视频笔记，包含封面图、笔记标题、发布时间与点赞藏数。
获取小红书作品内容详情 (优质库)
传入笔记 ID 或笔记分享链接，返回高清无水印轮播大图直链、正文文本、评论量与收藏量。
抖音短视频数据能力 (Douyin Short Videos)
抖音每日热门作品榜
实时同步抖音平台各垂直分类热榜热点视频，提供点赞、评论、分享、收藏量结构化清洗数据与封面直链。
抖音每日点赞飙升榜
捕捉点赞增长速率最快的黑马短视频，分析爆款背景音效（BGM）与热门梗点。
抖音七日点赞飙升榜
聚合一周内持续发酵的热门现象级爆款视频。
获取抖音达人账号信息 (优质库)
输入达人 sec_uid 或抖音号，输出认证黄V身份、粉丝量、获赞总量、所属 MCN 机构与星图等级。
获取抖音账号作品列表 (优质库)
分页查询达人发布的短视频列表与历史作品表现。
获取抖音作品内容详情与无水印视频流
返回视频标题、时长、背景音乐名、高清无水印播放地址与动图封面直链。
搜索关键词获取抖音视频作品
按照用户指定搜索词匹配最近发布的短视频。
哔哩哔哩数据接口能力 (Bilibili Videos & Creators)
搜索关键词获取哔哩哔哩作品 (优质库)
传入搜索词精准检索 B 站视频投稿，包含 BV号、UP 主昵称、播放量、弹幕量与投币收藏比。
获取哔哩哔哩 UP 主账号信息
传入 UP 主 mid，返回粉丝数、大会员等级、百大UP主标志、获赞数与累计播放量。
获取哔哩哔哩账号作品列表
分页拉取该 UP 主的所有历史投稿视频与分P结构。
获取哔哩哔哩作品内容详情
传入 BV 号或视频链接，解析简介、分区分类、硬币数、分享量与高清封面。
提取哔哩哔哩音频流直链
从视频中提取原声高码率音频直链，适用于 AI 音频模型训练与播客转写。
视频号与全球平台能力 (Channels & YouTube)
搜索关键词获取视频号作品 (广域库)
检索微信生态内公域分发的视频号内容。
获取视频号作品内容详情
传入视频唯一 ID，查询点赞、转发、评论与博主基本资料。
YouTube 搜索视频
全球视频检索，包含播放量、频道名、视频时长（Duration）与发布时间。
YouTube 视频字幕与文案提取
提取中英多语言带时间戳字幕文案，为大模型总结与长视频问答提供文本支持。