# 微信视频号解析 API 文档

## 1. 接口概览

| 项目 | 内容 |
| --- | --- |
| 接口名称 | 微信视频号解析 |
| 接口 ID | 191 |
| 功能描述 | 微信视频号解析 |
| 请求路径 | `/wxsph` |
| API Base URL | `https://api.xiaotuo.net` |
| 调试调用路径 | `/api/v1/calls/invoke` |
| 鉴权方式 | hybrid（混合鉴权，支持 API Key 与 APP_ID + APP_SECRET 两种凭证形式） |
| 响应类型 | auto_upstream（以上游返回为准） |

> 完整调用地址由 `api_base_url` 与接口路径拼接得到，例如：`https://api.xiaotuo.net/wxsph`。调试时可使用 `/api/v1/calls/invoke` 路径发起调用。

---

## 2. 鉴权方式

本接口采用 **hybrid（混合）鉴权**，即同一接口可能接受以下两类凭证：

### 2.1 API Key 鉴权

- API Key 不能为空。
- API Key 需已存在、有效，且已绑定当前接口。
- 请求来源 IP 需通过白名单校验（若接口启用 IP 白名单）。
- 部分账号可能受额外约束：需完成个人实名认证、企业认证、绑定邮箱等。

### 2.2 APP_ID + APP_SECRET 鉴权

当接口采用 APP_ID + APP_SECRET 模式时：

- `APP_ID`（或 `USER_ID`）不能为空；
- `APP_SECRET` 不能为空；
- `APP_ID` 必须存在且状态可用；
- `APP_SECRET` 必须与 `APP_ID` 匹配。

> 说明：元数据未给出具体的请求头参数名或签名算法，请以平台控制台下发的凭证字段为准，请勿在前端或公开代码中泄露 `APP_SECRET`。

---

## 3. 请求参数

| 参数名 | 位置 | 类型 | 必填 | 默认值 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- | --- |
| `url` | query | string | 否 | `https://weixin.qq.com/sph/AnjnoyNdwp` | 分享链接、短链接或作品 ID 字符串 | `https://weixin.qq.com/sph/AnjnoyNdwp` |

**请求示例**

```
GET https://api.xiaotuo.net/wxsph?url=https://weixin.qq.com/sph/AnjnoyNdwp
```

---

## 4. 响应结构

响应类型为 `auto_upstream`，即返回结构透传上游结果。成功响应示例（节选字段说明）：

### 4.1 顶层字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | number | 业务状态码，成功时为 `200` |
| `msg` | string | 提示信息，成功时示例为 `解析成功` |
| `requestId` | string | 请求追踪 ID |
| `_bugpkCache` | object | 缓存信息对象 |
| `data` | object | 解析结果数据 |

### 4.2 `_bugpkCache` 缓存信息

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `cached` | boolean | 是否已缓存 |
| `cachedAt` | string | 缓存写入时间（RFC3339） |
| `expiresAt` | string | 缓存过期时间（RFC3339） |
| `hit` | boolean | 是否命中缓存 |
| `remainingSeconds` | number | 剩余有效秒数 |
| `status` | string | 缓存状态，示例 `STORED` |
| `ttlSeconds` | number | 缓存 TTL 秒数 |

### 4.3 `data` 解析结果

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `title` | string | 视频标题 / 文案 |
| `desc` | string | 视频描述 |
| `type` | string | 内容类型，示例 `video` |
| `cover` | string | 封面图 URL |
| `url` | string | 视频直链 URL |
| `quality` | string | 清晰度标识，示例 `1080p` |
| `author` | object | 作者信息，含 `name`（昵称）、`avatar`（头像 URL） |
| `extra` | object | 附加信息，含 `create_time`（时间戳）、`expire_time`（过期时间字符串） |
| `video_backup` | array | 备用视频源列表 |

### 4.4 `data.video_backup[]` 备用视频源

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `codec` | string | 编码格式，示例 `h264` / `h265` |
| `format` | string | 容器格式，示例 `mp4` |
| `gear_name` | string | 档位名称，示例 `高清` |
| `label` | string | 档位标签，示例 `1080p` |
| `quality` | string | 清晰度，示例 `1080p` |
| `quality_type` | number | 清晰度类型编号，示例 `8` |
| `url` | string | 视频直链 URL |

**成功响应示例**

```json
{
  "_bugpkCache": {
    "cached": true,
    "cachedAt": "2026-10-23T08:39:07.689293227Z",
    "expiresAt": "2026-10-23T08:49:07.689293227Z",
    "hit": false,
    "remainingSeconds": 600,
    "status": "STORED",
    "ttlSeconds": 600
  },
  "code": 200,
  "data": {
    "author": {
      "avatar": "https://wx.qlogo.cn/...",
      "name": "学术蒟蒻"
    },
    "cover": "https://finder.video.qq.com/...",
    "desc": "...",
    "extra": {
      "create_time": 1792635136,
      "expire_time": "2026-10-24 08:38:54"
    },
    "quality": "1080p",
    "title": "...",
    "type": "video",
    "url": "https://finder.video.qq.com/...",
    "video_backup": [
      {
        "codec": "h264",
        "format": "mp4",
        "gear_name": "高清",
        "label": "1080p",
        "quality": "1080p",
        "quality_type": 8,
        "url": "https://finder.video.qq.com/..."
      },
      {
        "codec": "h265",
        "format": "mp4",
        "gear_name": "高清",
        "label": "1080p",
        "quality": "1080p",
        "quality_type": 8,
        "url": "https://finder.video.qq.com/..."
      }
    ]
  },
  "msg": "解析成功",
  "requestId": "gw_0353001af343daae4551a7a12124d776"
}
```

> 说明：`url`、`cover`、`avatar` 等直链通常带有有效期，请尽快使用；`data.extra.expire_time` 可辅助判断。

---

## 5. 错误码

| 错误码 | HTTP 状态 | 说明 |
| --- | --- | --- |
| 100 | 401 | API Key 不能为空：请求未携带 API Key，接口拒绝调用 |
| 101 | 401 | API Key 无效：API Key 不存在、已失效，或未绑定当前接口 |
| 102 | 403 | IP 不在白名单：当前请求来源 IP 未通过白名单校验 |
| 103 | 403 | 需要实名认证：当前接口要求用户先完成个人实名认证 |
| 104 | 403 | 需要企业认证：当前接口要求用户先完成企业认证 |
| 105 | 403 | 接口不可用：接口未开放、未审核通过或已停用 |
| 106 | 403 | 余额不足：按次计费接口余额不足，暂时无法调用 |
| 107 | 403 | 订阅已到期：订阅模式接口已过期或尚未开始 |
| 108 | 403 | 套餐余量不足：套餐包次数已用完，请先续费或购买 |
| 109 | 403 | 账号已禁用：当前用户账号已被禁用，无法继续调用接口 |
| 110 | 403 | IP 已被禁止：命中系统 IP 黑白名单拦截（IP 黑名网段封禁） |
| 113 | 403 | 需要绑定邮箱：系统已开启“绑定邮箱后才可外部调用”，当前账号未绑定邮箱 |
| 114 | 429 | 子 API Key 日限额已满：当前子 API Key 配置了每日请求上限且本自然日已用尽；请明日再试、调高限额或改用其他密钥 |
| 130 | 401 | APP_ID 不能为空：当前接口为 APP_ID + APP_SECRET 鉴权，必须传 APP_ID（或 USER_ID） |
| 131 | 401 | APP_SECRET 不能为空：当前接口为 APP_ID + APP_SECRET 鉴权，必须传 APP_SECRET |
| 132 | 401 | APP_ID 不存在或已禁用：APP_ID 无效，或凭证状态不可用 |
| 133 | 401 | APP_SECRET 错误：APP_SECRET 与 APP_ID 不匹配 |
| 10004 | 404 | 接口不存在：请求的接口路径不存在或未配置 |
| 20001 | 502 | 上游请求失败：调用上游服务时发生错误 |
| 20002 | 504 | 上游请求超时：调用上游服务超时 |
| 20003 | 502 | 上游返回异常状态：上游服务返回 4xx / 5xx 状态码 |

**错误响应示例**

```json
{
  "error": "upstream returned error status"
}
```

---

## 6. 计费与限流

- **价格**：`price` 字段为 `0`。
- **计费类型**：元数据中 `billing_type` 与 `action_billing` 均为空，未声明具体计费模式；上游错误码中提及“按次计费接口余额不足（106）”与“套餐包次数已用完（108）”“订阅模式接口已过期（107）”，说明平台侧可能按接口配置采用按次 / 套餐 / 订阅等模式，请以控制台展示为准。
- **限流**：`rate_limit` 字段为 `null`，元数据未声明统一限流阈值。
- **日限额**：若使用子 API Key，可能受“每日请求上限”约束（错误码 114，HTTP 429）。

---

## 7. 调用建议

1. 优先使用 `requestId` 排查问题，向平台反馈时一并提供。
2. 对 `data.url` 与 `data.video_backup[].url` 做降级处理：主链不可用时切换备用源。
3. 缓存机制已在上游侧生效（见 `_bugpkCache`），对同一目标短时间重复请求可减少上游压力。
4. 若返回 20003 / 20001 / 20002，属于上游异常，建议做有限次重试与退避。

完整调用地址由 api_base_url 与接口路径拼接得到，例如：https://api.xiaotuo.net/wxsph。调试时可使用 /api/v1/calls/invoke 路径发起调用。

微信视频号解析 API 文档

人工智能

微信视频号解析API接口，支持分享链接、短链接或作品ID，返回视频标题、封面、直链及备用视频源。采用混合鉴权（APIKey或APP_ID+APP_SECRET），具备缓存机制，提供1080p高清视频解析，附完整错误码说明与调用建议。

代码解释

容器

让每一个 Agent，都跑在云上

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

微信视频号解析 API 文档-腾讯云开发者社区-腾讯云

微信视频号解析 API 文档

微信视频号解析 API 文档

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐