diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..b0daf88 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,154 @@ +# 系统架构与解析生命周期设计 (Architecture) + +本文档详细阐述 **Media Parser** 的内部架构分层、请求处理生命周期、工厂模式插件化发现机制以及数据响应标准。 + +--- + +## 🏛️ 整体分层架构 + +项目遵循模块化、高内聚、低耦合的设计原则,自底向上分为以下四层: + +```mermaid +flowchart TD + Client["客户端 / Web体验页 / API调用者"] + + subgraph WebLayer["1. Web 接入层 (app.py & src/api/)"] + App["Flask App / 路由"] + ParseAPI["POST /api/parse"] + HealthAPI["GET /api/health"] + end + + subgraph CoreLayer["2. 调度与解析引擎 (Core Engine)"] + UrlParser["UrlParser (正则提取/平台识别)"] + WebFetcher["WebFetcher (302重定向追踪)"] + Factory["ParserFactory (动态发现与分发)"] + end + + subgraph ParserLayer["3. 平台解析器层 (src/parsers/)"] + BaseParser["BaseParser (基类/Session管理)"] + Douyin["DouyinParser"] + Kuaishou["KuaishouParser"] + XHS["XiaohongshuParser"] + Bili["BilibiliParser"] + Others["... 30+ 其它解析器"] + end + + subgraph UtilLayer["4. 工具与逆向支持 (utils/ & configs/)"] + Signer["BogusSigner (mini-racer JS执行)"] + Logger["LoggingConfig"] + CommonUtils["make_response 标准化响应"] + end + + Client --> App + App --> ParseAPI + ParseAPI --> UrlParser + ParseAPI --> WebFetcher + ParseAPI --> Factory + Factory --> BaseParser + BaseParser --> Douyin & Kuaishou & XHS & Bili & Others + Douyin --> Signer + ParseAPI --> CommonUtils +``` + +--- + +## 🔄 请求处理生命周期 (Lifecycle) + +当客户端向 `/api/parse` 发送一段包含分享文案的文本时,完整处理流如下: + +```mermaid +sequenceDiagram + autonumber + actor User as 客户端 (Client) + participant API as /api/parse + participant Fetcher as WebFetcher & UrlParser + participant Factory as ParserFactory + participant Parser as Platform Parser (如 DouyinParser) + participant Output as Response Formatter + + User->>API: POST {"text": "7.22 复制打开抖音... https://v.douyin.com/xxx/"} + API->>Fetcher: UrlParser.get_url(text) 提取原始链接 + API->>Fetcher: WebFetcher.fetch_redirect_url(url) 追踪302重定向 + Fetcher-->>API: 返回落地真实URL (Real URL) + API->>Fetcher: UrlParser.get_platform(real_url) 识别平台名称 + API->>Factory: ParserFactory.create_parser(platform, real_url) + Factory-->>API: 实例化对应平台解析器 + API->>Parser: 执行抓取 (_fetch_with_retry) + Note over Parser: 提取标题、视频直链、图集、LivePhoto、音频等 + Parser-->>API: 返回原始抓取字典 content_data + API->>Output: UrlParser.convert_to_https 统一转 HTTPS + API->>Output: make_response(200, '成功', data_dict) + Output-->>User: 返回标准 JSON 结构 +``` + +--- + +## 🧩 插件化解析器设计 (ParserFactory) + +为了便于扩展和多人协作,解析器采用 **装饰器自动注册 + 模块自动发现机制**: + +### 1. 自动发现 (`_discover`) +[src/parser_factory.py](file:///Users/leo/Projects/media-parser/src/parser_factory.py) 会在模块载入时利用 `pkgutil.iter_modules` 自动扫描并动态 `import` `src/parsers/` 下所有除 `base_parser` 以外的 Python 模块。 + +### 2. 声明式注册 (`@register_parser`) +新增任何平台解析器时,**无需修改任何工厂类核心代码**,只需继承 `BaseParser` 并加上装饰器: + +```python +from src.parser_factory import register_parser +from src.parsers.base_parser import BaseParser + +@register_parser("示例平台", "示例平台别名") +class ExampleParser(BaseParser): + def __init__(self, real_url): + super().__init__(real_url) + # 初始化与数据提取 + + def get_real_video_url(self): + return "https://..." +``` + +--- + +## 📦 统一响应格式标准 (Data Contract) + +所有解析接口均通过 `utils/common_utils.py` 中的 `make_response` 返回一致的 JSON 响应体。 + +### 成功响应示例 (`200 OK`) +```json +{ + "code": 200, + "msg": "成功", + "data": { + "platform": "抖音", + "video_id": "7616399587141737704", + "title": "视频文案标题", + "video_url": "https://aweme.snssdk.com/aweme/v1/play/...", + "cover_url": "https://p3-pc.douyinpic.com/...", + "author": { + "nickname": "创作者昵称", + "author_id": "unique_id_123", + "avatar": "https://p3.douyinpic.com/..." + }, + "audio_url": "https://sf6-cdn-tos.douyinstatic.com/...", + "image_list": [ + { + "url": "https://p3-pc.douyinpic.com/image1.jpeg", + "live_photo_url": "https://aweme.snssdk.com/aweme/v1/play/live_photo.mp4" + } + ], + "video_list": [] + }, + "success": true +} +``` + +### 错误响应示例 (`400 / 500`) +```json +{ + "code": 400, + "msg": "未找到有效的分享链接", + "data": null, + "success": false, + "error_code": "URL_NOT_FOUND" +} +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..29bd004 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,97 @@ +# Media Parser 项目技术文档与逆向百科 + +欢迎查阅 **Media Parser** 开发者文档与逆向工程知识库。 + +本项目是一个高性能、模块化、支持 **30+ 主流媒体与 AI 内容平台** 的无水印音视频、图文及 LivePhoto 结构化解析引擎。 + +--- + +## 📚 文档导航 + +* 🏗️ **[系统架构与生命周期 (Architecture)](architecture.md)**:了解请求处理链路、302 跳转跟踪与 ParserFactory 自动发现机制。 +* 🔍 **[通用逆向方法论 (Reverse Engineering Guide)](reverse-guide.md)**:掌握 SSR 数据提取、H5 接口伪装、JS 签名沙箱及抓包 SOP。 +* 🧪 **[测试与回归验证 (Testing Guide)](testing.md)**:学习 Pytest 单元测试、Mock 构造与真实样本(Live Samples)测试。 +* 📖 **平台实战指南 (Parser Guides)**: + * **短视频与轻社区**:[抖音](parsers/short-video/douyin.md) | [快手](parsers/short-video/kuaishou.md) | [皮皮虾](parsers/short-video/pipixia.md) | [皮皮搞笑](parsers/short-video/pipigaoxiao.md) | [最右](parsers/short-video/zuiyou.md) | [美拍](parsers/short-video/meipai.md) | [微视](parsers/short-video/weishi.md) | [绿洲](parsers/short-video/lvzhou.md) + * **图文与综合社区**:[小红书](parsers/community/xiaohongshu.md) | [微博](parsers/community/weibo.md) | [知乎](parsers/community/zhihu.md) | [闲鱼](parsers/community/xianyu.md) | [Soul](parsers/community/soul.md) + * **长视频与弹幕/创作**:[哔哩哔哩](parsers/video-streaming/bilibili.md) | [AcFun](parsers/video-streaming/acfun.md) | [新片场](parsers/video-streaming/xinpianchang.md) | [好看视频](parsers/video-streaming/haokan.md) | [西瓜视频](parsers/video-streaming/xigua.md) | [剪映](parsers/video-streaming/jianying.md) + * **AI 生成与大模型**:[豆包 AI](parsers/ai-generation/doubao.md) | [即梦 AI](parsers/ai-generation/jimeng.md) | [可灵 AI](parsers/ai-generation/kling.md) | [通义千问](parsers/ai-generation/qianwen.md) | [夸克 AI](parsers/ai-generation/quark-ai.md) | [小云雀 AI](parsers/ai-generation/xiaoyunque.md) + * **音频与垂直频道**:[汽水音乐](parsers/audio-others/qsmusic.md) | [全民K歌](parsers/audio-others/quanminkge.md) | [虎牙](parsers/audio-others/huya.md) | [梨视频](parsers/audio-others/lishipin.md) | [微信视频号](parsers/audio-others/wechat-channels.md) | [腾讯频道](parsers/audio-others/tencent-channel.md) + +--- + +## 📊 平台支持与测试状态矩阵 + +> **图例说明**: +> * ✅ **支持 / 已验证** | ⚠️ **条件依赖 (如需 Cookie)** | ❌ **不支持 / 无需配置** + +| 序号 | 平台名称 | 支持媒体类型 | 无水印直链 | 需配置 Cookie | 逆向提取模式 | 对应指南 | +| :--- | :--- | :--- | :---: | :---: | :--- | :--- | +| 1 | **抖音** | 视频 / 图文 / LivePhoto / 音频 | ✅ | ❌ | a_bogus 签名 + 动态 ttwid | [查看指南](parsers/short-video/douyin.md) | +| 2 | **小红书** | 图文 / LivePhoto / 视频 | ✅ | ⚠️ 部分需 Cookie | SSR HTML 注入数据提取 | [查看指南](parsers/community/xiaohongshu.md) | +| 3 | **快手** | 视频 / 图文 / 音频 | ✅ | ❌ (已内置游客凭证) | GraphQL / H5 双端多路由 Fallback | [查看指南](parsers/short-video/kuaishou.md) | +| 4 | **哔哩哔哩** | 视频 (MP4) / 音频分流 | ✅ | ❌ | 官方 View + PlayURL API | [查看指南](parsers/video-streaming/bilibili.md) | +| 5 | **豆包 AI** | AI 视频生成直链 | ✅ | ✅ `DOUBAO_COOKIE` | Web Session 维持 + 任务轮询 | [查看指南](parsers/ai-generation/doubao.md) | +| 6 | **即梦 AI** | AI 视频生成直链 | ✅ | ❌ | 移动分享端接口解析 | [查看指南](parsers/ai-generation/jimeng.md) | +| 7 | **可灵 AI** | AI 视频生成直链 | ✅ | ❌ | 快手可灵 H5 分享接口 | [查看指南](parsers/ai-generation/kling.md) | +| 8 | **通义千问** | AI 图文 / 图像生成 | ✅ | ⚠️ `YUANBAO_COOKIE` | AI Studio 移动分享端抓取 | [查看指南](parsers/ai-generation/qianwen.md) | +| 9 | **夸克 AI** | AI 图文 / 图像 | ✅ | ❌ | 夸克 H5 分享路由解析 | [查看指南](parsers/ai-generation/quark-ai.md) | +| 10 | **小云雀 AI** | AI 图文 / 图像 | ✅ | ❌ | 剪映小云雀分享端 | [查看指南](parsers/ai-generation/xiaoyunque.md) | +| 11 | **微博** | 视频 / 微博正文 / 多图 | ✅ | ❌ | 移动端 H5 接口 + Base62 解码 | [查看指南](parsers/community/weibo.md) | +| 12 | **知乎** | 视频 (Video Pin) / 想法 / 问答 | ✅ | ❌ | Web API 多路由正则提取 | [查看指南](parsers/community/zhihu.md) | +| 13 | **皮皮虾** | 视频 / 图文 | ✅ | ❌ | H5 接口数据解析 | [查看指南](parsers/short-video/pipixia.md) | +| 14 | **皮皮搞笑** | 视频 | ✅ | ❌ | H5 页面 JSON 提取 | [查看指南](parsers/short-video/pipigaoxiao.md) | +| 15 | **最右** | 视频 / 图集 | ✅ | ❌ | H5 接口键值映射提取 | [查看指南](parsers/short-video/zuiyou.md) | +| 16 | **AcFun** | 视频 (m3u8/MP4) | ✅ | ❌ | KSPlayer 播放器参数还原 | [查看指南](parsers/video-streaming/acfun.md) | +| 17 | **汽水音乐** | UGC 视频 / 背景原声 | ✅ | ❌ | 字节系分享 API | [查看指南](parsers/audio-others/qsmusic.md) | +| 18 | **全民K歌** | 视频 / 伴奏音频 | ✅ | ❌ | H5 播放页正则提取 | [查看指南](parsers/audio-others/quanminkge.md) | +| 19 | **虎牙** | 视频 / 录播 | ✅ | ❌ | 移动端短链解析 | [查看指南](parsers/audio-others/huya.md) | +| 20 | **微信视频号** | 视频 | ✅ | ❌ | 视频号短链解析 | [查看指南](parsers/audio-others/wechat-channels.md) | +| 21 | **腾讯视频/频道** | 视频 | ✅ | ❌ | 企鹅频道分享解析 | [查看指南](parsers/audio-others/tencent-channel.md) | +| 22 | **西瓜视频** | 视频 | ✅ | ❌ | 字节系引擎继承解析 | [查看指南](parsers/video-streaming/xigua.md) | +| 23 | **新片场** | 高清视频 | ✅ | ❌ | Next.js SSR 播放页提取 | [查看指南](parsers/video-streaming/xinpianchang.md) | +| 24 | **好看视频** | 百度短视频 | ✅ | ❌ | 百度视频落地页提取 | [查看指南](parsers/video-streaming/haokan.md) | +| 25 | **美拍** | 视频 | ✅ | ❌ | 网页 MP4 流还原 | [查看指南](parsers/short-video/meipai.md) | +| 26 | **微视** | 腾讯微视视频 | ✅ | ❌ | 微视开放接口 | [查看指南](parsers/short-video/weishi.md) | +| 27 | **绿洲** | 新浪绿洲图文 | ✅ | ❌ | 微博绿洲 H5 提取 | [查看指南](parsers/short-video/lvzhou.md) | +| 28 | **闲鱼** | 闲鱼图文贴 | ✅ | ❌ | 淘系分享页解析 | [查看指南](parsers/community/xianyu.md) | +| 29 | **Soul** | 视频 / 瞬间 | ✅ | ❌ | Web 话题页解析 | [查看指南](parsers/community/soul.md) | +| 30 | **剪映** | 剪映模板视频 | ✅ | ❌ | 字节剪映 API | [查看指南](parsers/video-streaming/jianying.md) | +| 31 | **梨视频** | 资讯短视频 | ✅ | ❌ | 动态防盗链时间戳解密 | [查看指南](parsers/audio-others/lishipin.md) | + +--- + +## ⚡ 快速开始 + +### 1. 安装依赖 +```bash +# 建议使用 Python 3.10+ +pip install -r requirements.txt +``` + +### 2. 环境变量配置 (可选) +复制 `.env.example` 为 `.env`: +```bash +cp .env.example .env +``` +如需解析受限的小红书笔记或大模型 AI 平台(如豆包),在 `.env` 中填入对应 Cookie: +```env +DOUBAO_COOKIE="your_doubao_cookie_here" +YUANBAO_COOKIE="your_yuanbao_cookie_here" +``` + +### 3. 运行服务 +```bash +# 开发环境启动 (端口 8051) +python app.py + +# 访问 Web 演示前台:http://127.0.0.1:8051/ +# 测试健康检查:http://127.0.0.1:8051/api/health +``` + +--- + +## ⚖️ 免责声明 (Disclaimer) + +本项目所有代码和文档仅用于**网络技术研究、接口逆向工程学习与防御性安全交流**。 +使用者请遵守各目标平台的《用户服务协议》与相关法律法规,不得用于任何形式的商业盈利抓取或恶意攻击行为。因使用本工具造成的任何直接或间接法律责任由使用者自行承担。 diff --git a/docs/parsers/ai-generation/doubao.md b/docs/parsers/ai-generation/doubao.md new file mode 100644 index 0000000..1cc25c9 --- /dev/null +++ b/docs/parsers/ai-generation/doubao.md @@ -0,0 +1,105 @@ +# 豆包 AI (Doubao) 逆向解析指南 + +本篇详细记录字节跳动旗下**豆包 AI** 对话分享(Thread)与独立视频生成分享(Video Sharing)的逆向解析方案、FPLAY 播放凭证解密与 Cookie 鉴权机制。 + +--- + +## 1. 平台特征与支持能力 + +* **平台标识**:`豆包` +* **支持媒体类型**: + * AI 生成 1080P 高清无水印视频 (MP4) + * AI 生成图文 / 提示词生图 (PNG/JPEG) + * 对话标题、Prompt 提示词与创作者信息 +* **常见链接形态**: + * 独立视频分享:`https://www.doubao.com/video-sharing?share_id=41356597786354690&video_id=v0d69cg10004d6978e2ljht0i4fdpp00` + * 对话历史/线程分享:`https://www.doubao.com/thread/w8293749281` +* **Cookie 依赖**: + * **图片解析**:**无需 Cookie**(公开元数据直接包含 `image_ori_raw` 高清原图)。 + * **视频无水印解析**:**必须配置 Cookie**(1080P 原始流被权限隔离,未登录仅能获取服务端硬压制水印的预览切片)。 + +--- + +## 2. 核心逆向流程 + +[DoubaoParser](file:///Users/leo/Projects/media-parser/src/parsers/doubao_parser.py) 内部实现了双分支解析引擎与优雅降级策略: + +```mermaid +flowchart TD + Start["输入豆包分享 URL"] --> Route{"判断 URL 路径"} + Route -->|"/thread/xxx"| ThreadFlow["1. 会话线程解析 (_parse_thread)"] + Route -->|"/video-sharing"| VideoFlow["2. 独立视频解析 (_parse_video_sharing)"] + + ThreadFlow --> ScriptPayload["提取 HTML 中 script 注入的 JSON 负载"] + ScriptPayload --> Creations["递归遍历提取 creation 实体 (视频/图像)"] + + VideoFlow --> AuthCheck{"是否配置了 DOUBAO_COOKIE?"} + AuthCheck -->|已配置| SamanthaAPI["调用 /samantha/media/get_play_info"] + SamanthaAPI --> AES["执行 FPLAY KDF 盐值派生 + AES-128-CBC 解密"] + AES --> HDVideo["获得 1080P 纯净无水印原画视频 (3960kbps)"] + + AuthCheck -->|未配置 (降级)| ShareAPI["调用 /creativity/share/get_video_share_info"] + ShareAPI --> StripParam["清理 URL 水印参数 (降级为带水印预览切片)"] +``` + +--- + +## 3. 核心 API 与加密解密技术细节 + +### 3.1 核心 API 汇总 +* **无水印高清媒体接口 (需鉴权)**: + `POST https://www.doubao.com/samantha/media/get_play_info` +* **公开视频分享接口 (未登录降级用)**: + `POST https://www.doubao.com/creativity/share/get_video_share_info` +* **模型资源接口**: + `POST https://www.doubao.com/alice/resource/get_video_model` + +### 3.2 FPLAY 播放流密钥派生 (KDF & AES 解密) +豆包的高清无水印视频源采用了字节跳动 **FPLAY 自定义加密流**。解析器内置了基于固定盐值的密钥派生与 AES-128-CBC 解密算法: +* **KDF Salt 盐值**: + `TdTC5rgxYgkOUrPHpnM7pByyRiuCmrWKGWs521cXdST0m69/COjWjSanLjfBqVovHwWlGJKu8pSXMrYqOKrdWA==` +* **解密逻辑**: + 1. 通过 SHA256 与 Salt 派生出 AES Key 与 IV; + 2. 利用 `Crypto.Cipher.AES` 对 `get_play_info` 下发的密文字符串进行解密并去除 PKCS7 Padding; + 3. 解密后即可还原出官方原始 1080P MP4 直链(经验证,文件 MD5 与平台原始生成视频完全一致)。 + +--- + +## 4. 经典踩坑与逆向攻防复盘 (Case Study: Issue #14) + +### 踩坑 1:URL 参数去水印的“假象” +* **初始误区**:在公开分享接口中,视频 URL 带有 `lr=video_gen_watermark_dyn`、`logo_type` 等参数。直觉上容易认为只要清洗掉这些 URL Query 参数就能去水印。 +* **攻防真相**:豆包服务端对于未登录/公开状态的请求,**在服务器端转码切片时就已经将水印物理硬编码压制进了视频画面**。清洗 URL 参数无法改变视频底层的像素内容。 +* **最终解法**:必须通过 `samantha/media/get_play_info` 鉴权接口提取 `original_media_info.main_url` 并完成 FPLAY 解密。 + +### 踩坑 2:图文与视频的鉴权隔离差异 +* **图片无水印**:豆包在公开分享 HTML 中直接完整下发了 `image_ori_raw` 与 `image_ori` 原图直链,无需任何登录态即可提取无水印原图。 +* **视频强鉴权**:未登录请求 `get_play_info` 会直接报 `login invalid`,因此视频无水印必须依赖登录态。 + +--- + +## 5. Cookie 配置最小指南 + +为避免用户复制过长且包含无关追踪标记的 Cookie,豆包仅需提取关键的身份凭据即可: + +1. 打开浏览器访问 [豆包网页版](https://www.doubao.com/) 并登录。 +2. 按 `F12` 打开开发者工具,在 **Application (应用程序) ➔ Cookies** 中找到核心认证字段:`sessionid_ss`。 +3. 在项目根目录的 `.env` 文件中配置(两者格式均支持): + ```env + # 精简格式 (推荐) + DOUBAO_COOKIE="sessionid_ss=你的sessionid_ss值" + + # 或者完整 Cookie 字符串 + DOUBAO_COOKIE="sessionid_ss=xxx; passport_csrf_token=yyy; ..." + ``` + +--- + +## 6. 测试与验证 + +* **单元测试**:[tests/test_doubao_parser.py](file:///Users/leo/Projects/media-parser/tests/test_doubao_parser.py) +* **执行测试**: + ```bash + pytest tests/test_doubao_parser.py + python tests/manual_verify_parsers.py --platform 豆包 + ``` diff --git a/docs/parsers/ai-generation/jimeng.md b/docs/parsers/ai-generation/jimeng.md new file mode 100644 index 0000000..c8b24ec --- /dev/null +++ b/docs/parsers/ai-generation/jimeng.md @@ -0,0 +1,82 @@ +# 即梦 AI (Jimeng) 逆向解析指南 + +本篇详细记录字节跳动剪映旗下 **即梦 AI (jimeng.jianying.com)** 视频与图像生成的解析方案及接口细节。 + +--- + +## 1. 平台特征与支持能力 + +* **平台标识**:`即梦AI` +* **支持媒体类型**: + * AI 生成高清视频 (MP4) + * AI 生成图集 (PNG/JPEG) + * 提示词文案 (Prompt) 与创作者昵称/头像 +* **常见链接形态**: + * 分享短链:`https://jimeng.jianying.com/s/rdloCrYi2wc/?t=8011` + * 移动详情长链:`https://jimeng.jianying.com/ai-tool/share/item/7631885529415568665` +* **Cookie 依赖**:公开分享链接**无需配置 Cookie**。 + +--- + +## 2. 核心逆向流程 + +```mermaid +sequenceDiagram + autonumber + participant Parser as JimengParser + participant H5 as 即梦短链服务 + participant API as mweb/v1/get_item_info + + Parser->>H5: 请求短链接 (跟踪 302 重定向) + H5-->>Parser: 获取包含 item_id 的最终长链接 + Parser->>Parser: 正则提取 item_id / share_id + Parser->>API: POST {"item_id": "xxx"} + API-->>Parser: 返回包含 video_model / image_list 的作品 JSON + Parser->>Parser: 提取无水印 MP4 直链与封面 +``` + +### 2.1 核心请求定义 +* **接口地址**: + `POST https://jimeng.jianying.com/mweb/v1/get_item_info` +* **请求头**: + ```python + headers = { + "Accept": "application/json, text/plain, */*", + "Content-Type": "application/json", + "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." + } + ``` +* **Payload 载荷**: + ```json + { + "item_id": "7631885529415568665" + } + ``` + +--- + +## 3. 字段提取规则 + +* **视频直链**:从 `item_info.video.play_addr.url_list[0]` 或 `item_info.video_model.video_list[0].main_url` 获取。 +* **生图图集**:从 `item_info.image_list` 提取高清渲染图。 +* **Prompt 标题**:从 `item_info.title` 或 `item_info.prompt` 中提取。 + +--- + +## 4. 常见踩坑与注意事项 + +1. **短链参数丢失**: + * 即梦短链(`/s/xxxx`)必须先发起一次带 `allow_redirects=True` 的 GET 请求,从重定向后的真实 URL 查询参数或路径中提取真正的 `item_id`。 +2. **多清晰度选择**: + * 接口返回的 `video_list` 可能包含预览低清流和渲染高清流,代码中已内置按分辨率倒序优先挑选最高清直链。 + +--- + +## 5. 测试与验证 + +* **单元测试**:[tests/test_jimeng_parser.py](file:///Users/leo/Projects/media-parser/tests/test_jimeng_parser.py) +* **执行测试**: + ```bash + pytest tests/test_jimeng_parser.py + python tests/manual_verify_parsers.py --platform 即梦AI + ``` diff --git a/docs/parsers/ai-generation/kling.md b/docs/parsers/ai-generation/kling.md new file mode 100644 index 0000000..080031e --- /dev/null +++ b/docs/parsers/ai-generation/kling.md @@ -0,0 +1,67 @@ +# 快手可灵 AI (Kling) 逆向解析指南 + +本篇详细记录快手旗下大模型 **可灵 AI (Kling AI)** 视频与创意作品分享的接口抓取机制与参数解析。 + +--- + +## 1. 平台特征与支持能力 + +* **平台标识**:`可灵AI` +* **支持媒体类型**: + * AI 生成高清视频 (MP4) + * 视频生成封面与 Prompt 描述 + * 创作者昵称与作品 ID +* **常见链接形态**: + * 分享落地页:`https://klingai-share.kuaishou.com/h5-app/share?work_id=305387532165182&creative_id=305387532165182&creative_type=WORK` +* **Cookie 依赖**:无需 Cookie,支持公开查询。 + +--- + +## 2. 核心逆向流程 + +### 2.1 创意作品参数提取 (`_extract_creative`) +从传入链接的 Query String 中提取两个核心参数: +* `creative_id` (或 `work_id`):作品唯一数字编号。 +* `creative_type`:作品类型(默认为 `WORK`)。 + +### 2.2 核心查询接口 +* **接口地址**: + `GET https://klingai-share.kuaishou.com/app/creatives/query` +* **Query 参数**: + * `creativeId={creative_id}` + * `creativeType={creative_type}` +* **必备请求头**: + * `User-Agent`:移动端 UA (如 iPhone Safari) + * `Referer`:`https://klingai-share.kuaishou.com/` + +--- + +## 3. 数据提取规则 + +在返回的 JSON 数据中: +* **视频无水印直链**: + 位于 `data.playUrl` 或 `data.works[0].resource.url`。 +* **封面图**: + 位于 `data.coverUrl` 或 `data.works[0].resource.coverUrl`。 +* **Prompt 标题**: + 位于 `data.prompt` 或 `data.title`。 + +--- + +## 4. 常见踩坑记录 (Gotchas) + +1. **Query 字段命名多变**: + * 部分版本分享出来的参数为 `work_id`,新版本为 `creative_id`。代码中采用 fallback 容错兼容逻辑。 +2. **纯纯数字 ID 兼容**: + * 解析器支持直接传入数字 ID 字符串,自动识别为 `creative_id` 并构造请求。 + +--- + +## 5. 测试与验证 + +* **单元测试**:[tests/test_kling_parser.py](file:///Users/leo/Projects/media-parser/tests/test_kling_parser.py) +* **执行测试**: + ```bash + pytest tests/test_kling_parser.py + python tests/manual_verify_parsers.py --platform 可灵AI + ``` diff --git a/docs/parsers/ai-generation/qianwen.md b/docs/parsers/ai-generation/qianwen.md new file mode 100644 index 0000000..2e8257c --- /dev/null +++ b/docs/parsers/ai-generation/qianwen.md @@ -0,0 +1,71 @@ +# 通义千问 (Qwen) 逆向解析指南 + +本篇详细记录阿里巴巴 **通义千问 (Qwen)** AI Studio 及移动分享作品的 `__INITIAL_PROPS__` SSR 数据提取方案。 + +--- + +## 1. 平台特征与支持能力 + +* **平台标识**:`通义千问` +* **支持媒体类型**: + * AI 创作图集 / 扩图 / 文生图 (PNG/JPEG) + * AI 生成视频 (MP4) + * 提示词 Prompt、标题与作者信息 +* **常见链接形态**: + * 移动分享长链:`https://activity.qianwen.com/r/ai-studio-mobile/qwen-external-share?shareId=ZeeOedXncnGlElkluRMA&authorId=OjTAcGHgZgye...` +* **Cookie 依赖**:公开外部分享**无需 Cookie**。 + +--- + +## 2. 核心逆向方案:`__INITIAL_PROPS__` 提取与反序列化 + +通义千问的分享落地页使用 React SSR,所有作品和图片 CDN 地址均直接挂载在 `window.__INITIAL_PROPS__` 全局脚本变量中。 + +### 2.1 提取与双重 URL 解码流程 +```python +# 1. 定位 script 中的 window.__INITIAL_PROPS__ +marker = "window.__INITIAL_PROPS__" +pos = html_text.find(marker) +sub = html_text[pos + len(marker):].lstrip(" =") +sub = sub[:sub.find("")].rstrip().rstrip(";") + +# 2. 解析 JSON +data = json.loads(sub) +raw_initial = data.get("initialData", {}) + +# 3. 处理 URL 编码与嵌套 JSON +if isinstance(raw_initial, str) and raw_initial.startswith("%"): + raw_initial = urllib.parse.unquote(raw_initial) + raw_initial = json.loads(raw_initial) +``` + +--- + +## 3. 字段提取规则 + +* **生成图像列表**: + * 从 `initial_data.images` 或 `initial_data.resultList` 遍历提取 CDN 高清图片地址。 +* **生图 Prompt**: + * 提取 `initial_data.prompt` 或 `initial_data.title`。 +* **作者信息**: + * 提取 `initial_data.author` 对象的昵称与头像。 + +--- + +## 4. 常见踩坑记录 (Gotchas) + +1. **`initialData` 双重编码**: + * 某些版本的前端模板将 `initialData` 先做了 `encodeURIComponent`,因此在 `json.loads` 之前必须进行 `urllib.parse.unquote`,否则直接反序列化会报错。 +2. **图文与视频多态结构**: + * 部分 AI 助手生成的是短视频,部分是 4 宫格图集,解析器中通过类型自适应兼容两种结构。 + +--- + +## 5. 测试与验证 + +* **单元测试**:[tests/test_qianwen_parser.py](file:///Users/leo/Projects/media-parser/tests/test_qianwen_parser.py) +* **执行测试**: + ```bash + pytest tests/test_qianwen_parser.py + python tests/manual_verify_parsers.py --platform 通义千问 + ``` diff --git a/docs/parsers/ai-generation/quark-ai.md b/docs/parsers/ai-generation/quark-ai.md new file mode 100644 index 0000000..b191d58 --- /dev/null +++ b/docs/parsers/ai-generation/quark-ai.md @@ -0,0 +1,43 @@ +# 夸克 AI (Quark AI) 逆向解析指南 + +本篇详细记录阿里巴巴旗下 **夸克 AI (Quark AI)** 分享作品的解析方案与复用继承架构。 + +--- + +## 1. 平台特征与支持能力 + +* **平台标识**:`夸克AI` +* **支持媒体类型**: + * AI 创作图集 (PNG/JPEG) + * AI 生成内容与提示词 +* **常见链接形态**: + * 分享落地页:`https://act.quark.cn/apps/sharepages/routes/share?biz_id=ai_chat_v2&share_id=3aeb87e5f7214ecbb54881903cd02a23` +* **Cookie 依赖**:无需 Cookie。 + +--- + +## 2. 架构设计:底层复用与平台隔离 + +阿里巴巴旗下夸克 AI 的分享页面底层与通义千问(Qwen)共享相同的 **AI Studio** 基础设施与前端渲染协议(均采用 `window.__INITIAL_PROPS__` 注入方式)。 + +为了减少重复代码并维持整洁的代码库,[QuarkAIParser](file:///Users/leo/Projects/media-parser/src/parsers/quark_ai_parser.py) 采用了 **继承复用** 模式: + +```python +from src.parser_factory import register_parser +from src.parsers.qianwen_parser import QianwenParser + +@register_parser("夸克AI") +class QuarkAIParser(QianwenParser): + """夸克 AI 与通义千问分享页使用相同的数据结构,完全复用核心解析逻辑。""" +``` + +--- + +## 3. 测试与验证 + +* **单元测试**:[tests/test_quark_ai_parser.py](file:///Users/leo/Projects/media-parser/tests/test_quark_ai_parser.py) +* **执行测试**: + ```bash + pytest tests/test_quark_ai_parser.py + python tests/manual_verify_parsers.py --platform 夸克AI + ``` diff --git a/docs/parsers/ai-generation/xiaoyunque.md b/docs/parsers/ai-generation/xiaoyunque.md new file mode 100644 index 0000000..6a93b39 --- /dev/null +++ b/docs/parsers/ai-generation/xiaoyunque.md @@ -0,0 +1,42 @@ +# 小云雀 AI (Xiaoyunque) 逆向解析指南 + +本篇详细记录字节跳动剪映旗下 **小云雀 AI (xiaoyunque.jianying.com)** 分享作品的接口抓取机制与参数解析。 + +--- + +## 1. 平台特征与支持能力 + +* **平台标识**:`小云雀AI` +* **支持媒体类型**: + * AI 创作图集 (PNG/JPEG) + * 提示词 Prompt、封面与作者信息 +* **常见链接形态**: + * 分享短链:`https://xiaoyunque.jianying.com/s/z_7nWGLGruM/` +* **Cookie 依赖**:公开短链**无需配置 Cookie**。 + +--- + +## 2. 核心逆向流程 + +### 2.1 短链解析与落地页跳转 +通过发起 GET 请求跟踪 302 跳转,从小云雀长链接中提取 Query 参数字典 `qdict`。 + +### 2.2 核心数据接口 +* **接口地址**: + `GET/POST https://xiaoyunque.jianying.com/luckycat/cn/jianying/campaign/v1/pippit/share/landing_page` +* **请求头**: + * `User-Agent`: 现代浏览器 UA + * `Accept`: `application/json, text/plain, */*` +* **提取数据**: + * 从返回的 `data.item_info` 或 `data.share_info` 中提取高清图集 URL 与封面。 + +--- + +## 3. 测试与验证 + +* **单元测试**:[tests/test_xiaoyunque_parser.py](file:///Users/leo/Projects/media-parser/tests/test_xiaoyunque_parser.py) +* **执行测试**: + ```bash + pytest tests/test_xiaoyunque_parser.py + python tests/manual_verify_parsers.py --platform 小云雀AI + ``` diff --git a/docs/parsers/audio-others/huya.md b/docs/parsers/audio-others/huya.md new file mode 100644 index 0000000..5790761 --- /dev/null +++ b/docs/parsers/audio-others/huya.md @@ -0,0 +1,28 @@ +# 虎牙 (Huya) 逆向解析指南 + +本篇详细记录 **虎牙直播 / 虎牙短视频** 录播与视频切片的抓取方案。 + +--- + +## 1. 平台特征与支持能力 + +* **平台标识**:`虎牙` +* **支持媒体类型**:高清视频 (MP4/HLS) / 封面图 / 视频标题 +* **常见链接形态**: + * 短链接:`https://hy.fan/v3cwMK` +* **Cookie 依赖**:无需 Cookie。 + +--- + +## 2. 核心逆向流程 + +1. **302 跳转提取视频 ID**:跟随短链跳转至虎牙视频真实落地页。 +2. **提取视频播放流**: + * 从落地页 HTML 中提取 `