微信视频号解析 API 实战：一次调用拿到标题、封面、原画直链与多清晰度备选

视频号是个"封闭生态"：分享链接指向微信自己的页面，常规请求拿不到视频元数据，自己逆向协议又要维护签名和.cookie，一改版就失效。这个接口把这件事收敛成一次 HTTP 调用——传入视频号分享链接或口令，同步返回标题、描述、封面、视频直链、作者与互动数据，还附带多清晰度备用地址列表。

✅ 接口亮点

一、适用场景

按落地频率排序，第三列是主要依赖字段，对着自己的需求看：

两条使用建议：

1. 互动数据做差值，不做绝对值。 视频号的 play_count 常返回 0（平台不公开播放数），这是正常现象；同一条链接隔天各解析一次取差值，才反映真实增长。
2. video_backup 是给下载容错用的。 主直链 video_url 有时效，解析后建议立即转存；如果转存失败，按 video_backup 里其他清晰度档位重试一遍，别直接判死。

边界也要先说清：接口仅提供链接元数据解析，不存储、不分发原始内容；解析结果归原作者及原平台所有，适合内容审核、数据分析、备份归档这类合理场景，不要拿去做去水印下载站或公开传播他人作品。

二、接入基础信息

请求参数只有两个：

Key 不要写进代码或提交到 Git，放环境变量：

export XIAOAPIS_API_KEY="你的key"

三、第一次调用：两条 curl

GET 版（最快验证）：

curl "https://xiaoapis.com/api/video/weixin?key=$XIAOAPIS_API_KEY&url=视频号分享链接"

POST + JSON 版（日常推荐）：

curl -X POST "https://xiaoapis.com/api/video/weixin?key=$XIAOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "6.66 复制打开【微信】观看【示例作者的video】 https://channels.weixin.qq.com/xxxxxxxx"}'

日常用 POST 的理由和大多数解析接口一样：口令里带中文、表情，放 JSON 请求体比拼 query string 少一层编码坑。

四、返回结构：四个值得注意的细节

成功返回的顶层是 code / msg / data，业务数据全在 data 里。完整结构：

{
   
  "code": 200,
  "msg": "解析成功",
  "data": {
   
    "platform": "weixin_channels",
    "type": "video",
    "title": "示例标题",
    "desc": "示例描述",
    "video_url": "https://.../video.mp4",
    "cover_url": "https://.../cover.jpg",
    "quality": "原画",
    "author": {
   
      "name": "作者昵称",
      "id": "xxx",
      "avatar": "https://.../avatar.jpg"
    },
    "author_name": "作者昵称",
    "author_id": "xxx",
    "author_avatar": "https://.../avatar.jpg",
    "video_backup": [
      {
   
        "label": "H.264 原画",
        "quality": "原画",
        "url": "https://.../video.mp4",
        "format": "mp4",
        "codec": "h264"
      }
    ],
    "stats": {
   
      "like_count": 365,
      "comment_count": 26,
      "share_count": 1490,
      "play_count": 0
    },
    "request_url": "https://..."
  }
}

四个动手前要知道的细节：

1. platform 固定是 weixin_channels，type 是 video。 这是视频号专用接口，返回结构是收敛过的，不用像通用解析接口那样处理图集、实况等多形态——判断逻辑可以写得很简单。
2. 作者字段双写。 顶层 author_name / author_id / author_avatar 和 author 对象内容一致。建议代码从顶层取，author 对象留作兼容；两边都判空再兜底，别只押一边。
3. video_backup 是备选清晰度列表，每项带 label（如"H.264 原画"）、quality、format、codec。需要指定编码格式（比如只收 h264）或避开高规格编码时，按 codec 筛这列表，而不是盲用主直链。
4. play_count 是 0 是正常的。 视频号不公开播放数，返回 0 不代表没播放；做报表时把这一列置灰或标注"平台未公开"，别当异常告警。

五、Python 单文件工具

可以直接当命令行工具用，也是集成到项目里的底子：

#!/usr/bin/env python3
"""wxparse.py — 微信视频号解析小工具。

用法:
    export XIAOAPIS_API_KEY="你的key"
    python3 wxparse.py "6.66 复制打开【微信】观看… https://channels.weixin.qq.com/xxxx"
    python3 wxparse.py https://channels.weixin.qq.com/xxxxxxxx
"""
import os
import sys

import requests

ENDPOINT = "https://xiaoapis.com/api/video/weixin"


class ParseError(RuntimeError):
    """业务失败：参数错误 / 链接无法解析 / 点数不足，重试无意义。"""


class NetworkError(RuntimeError):
    """网络类失败：值得退避重试。"""


def parse(url_or_text: str, *, timeout: float = 30.0) -> dict:
    """解析一条视频号链接，返回 data 字典。口令整段传入即可。"""
    key = os.environ.get("XIAOAPIS_API_KEY")
    if not key:
        raise ParseError("未设置 XIAOAPIS_API_KEY 环境变量")

    try:
        resp = requests.post(
            ENDPOINT,
            json={
   "key": key, "url": url_or_text},
            timeout=timeout,
        )
    except requests.RequestException as exc:
        raise NetworkError(f"请求失败: {exc}") from exc

    try:
        body = resp.json()
    except ValueError:
        raise NetworkError(f"HTTP {resp.status_code}，返回非 JSON: {resp.text[:200]}")

    if body.get("code") != 200:
        raise ParseError(f"[{body.get('code')}] {body.get('msg')}")
    return body["data"]


def pick_video(data: dict) -> list[dict]:
    """主直链 + 备选清晰度，统一成 [{url, label, codec, format}]。

    主直链放第一个；video_backup 里与主直链重复的项去掉。
    """
    items: list[dict] = []
    main = (data.get("video_url") or "").strip()
    if main:
        items.append({
   
            "url": main,
            "label": f"主直链（{data.get('quality') or '未知画质'}）",
            "codec": "",
            "format": "",
        })
    for b in data.get("video_backup") or []:
        url = (b.get("url") or "").strip()
        if url and url != main:
            items.append({
   
                "url": url,
                "label": b.get("label") or b.get("quality") or "备选",
                "codec": b.get("codec") or "",
                "format": b.get("format") or "",
            })
    return items


def show(data: dict) -> None:
    author = (data.get("author") or {
   })
    name = data.get("author_name") or author.get("name") or "(未知)"
    stats = data.get("stats") or {
   }
    print(f"标题: {data.get('title') or '(无)'}")
    print(f"描述: {data.get('desc') or '(无)'}")
    print(f"作者: {name}（ID: {data.get('author_id') or author.get('id') or '未知'}）")
    print(f"互动: 赞 {stats.get('like_count', 0)} / 评 {stats.get('comment_count', 0)}"
          f" / 转 {stats.get('share_count', 0)}"
          f" / 播 {stats.get('play_count', '未公开')}")
    print(f"封面: {data.get('cover_url') or '(无)'}")
    for i, v in enumerate(pick_video(data), 1):
        extra = " ".join(filter(None, [v["codec"], v["format"]]))
        print(f"[{i}] {v['label']} {extra}: {v['url']}")


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(__doc__)
        sys.exit(1)
    try:
        show(parse(sys.argv[1]))
    except ParseError as exc:
        print(f"解析失败: {exc}", file=sys.stderr)
        sys.exit(2)
    except NetworkError as exc:
        print(f"网络异常: {exc}", file=sys.stderr)
        sys.exit(3)

三个设计点：

• pick_video 把主直链和备选档统一成一张列表，主直链排第一、去重。下载器只需遍历列表，第一档失败自动落到第二档，不用写两套逻辑。
• 作者取数走"顶层优先、对象兜底"，两种写法都判空，接口哪个字段将来调整都不至于直接崩。
• 退出码三分类（0 成功 / 2 业务失败 / 3 网络异常），进 cron 或流水线时上游按退出码决定重试策略。

六、计费与限流

点数单价以控制台实时显示为准。按此上限，单账号日解析上限就是 1 万条，QPS 打满是 10 条/秒——批量任务建议把实际并发压在 5 次/秒以内，留出抖动余量，也避免瞬时流量触发限流。

注意：每日 10000 次是接口层面的上限，点数余额是另一道闸——余额不足时同样会失败，只是返回 400。两条线都要监控。

七、错误码速查

监控建议：对 msg 做关键字分类（"点数" / "链接" / "认证"）再告警，否则凌晨的告警群全是"400"三个字符，什么都看不出来。

八、什么时候用这个接口，什么时候不用

它是视频号专用接口，适合：来源确定是视频号、需要 video_backup 备选清晰度、只要视频形态的场景。

如果你的输入是混合来源——抖音、小红书、B站、微博、YouTube 等杂链一起进来——那就该用通用解析接口在入口做分发：视频号链接走本接口，其他平台走通用接口，各自取数后落到同一张表。通用接口的支持平台清单以其文档为准，这里不展开。

判断来源不需要写复杂逻辑：视频号链接的域名特征是 channels.weixin.qq.com，口令里也带"视频号"或"channels.weixin"字样，一个正则就能路由。

九、FAQ

Q1：口令整段直接传行吗？

行。接口自动提取其中的 http(s) 地址，不用自己写正则，兼容 content、link 参数名。

Q2：能拿到播放量吗？

拿不到完整值。视频号不公开播放数，play_count 返回 0 是常态；点赞、评论、转发三项是有的。

Q3：视频直链能长期保存吗？

不能。直链有时效，解析后立即下载转存自己的对象存储，业务库存自己的地址。转存失败时用 video_backup 的备选档再试。

Q4：图集或实况怎么处理？

本接口面向视频形态，返回 type: video。图文类内容不在本接口范围内。

Q5：失败扣点吗？

不扣。只有 200 扣 2 点；400、500 都不计费。按"2 点/次"算，一千次成功解析的成本是固定的，预算很好做。

Q6：和通用视频解析接口怎么选？

来源只有视频号 → 用本接口，字段更聚焦、带备选清晰度；多平台混合来源 → 入口做域名路由，视频号走本接口、其余走通用接口。

十、上线前检查清单

1. Key 走环境变量或密钥管理服务，代码与日志无明文；
2. 批量任务限速 ≤5 次/秒，留出限流余量；
3. 解析即转存，库里不存平台直链；
4. 监控成功率与余额阈值，按 msg 分类告警；
5. play_count=0 不设告警，报表标注"平台未公开"；
6. 来源与版权信息在用户可见界面展示，合规条款对照文档原文。

参考

• 微信视频号解析 API 文档
• Markdown 版（供 LLM / Agent 读取）
• 销豹 API 接口目录