res-downloader API文档：开发者集成指南

1. 概述

res-downloader是一款集网络资源嗅探与高速下载功能于一体的工具，支持微信视频号、抖音、快手等平台资源的无水印下载。本文档详细介绍其API接口，帮助开发者快速集成到第三方应用中。

1.1 核心功能

功能模块	描述	关键API
资源下载	支持多平台视频/音频下载	POST /api/download
微信文件解密	解密微信加密文件	POST /api/wxFileDecode
配置管理	获取/修改应用配置	GET /api/config, POST /api/config
系统代理控制	开关系统代理	POST /api/openSystemProxy

1.2 API架构

flowchart LR
    Client[第三方应用] -->|HTTP/JSON| APIServer[内置API服务器]
    APIServer --> Config[配置模块]
    APIServer --> Downloader[下载模块]
    APIServer --> System[系统模块]
    Downloader --> Resource[资源解析]
    Downloader --> Decrypt[解密服务]

2. 快速开始

2.1 环境准备

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/re/res-downloader.git
cd res-downloader

# 启动服务
go run main.go

服务默认监听http://127.0.0.1:8899，可通过配置文件修改端口。

2.2 基础请求示例

获取应用配置

GET /api/config
Accept: application/json

响应示例

{
  "Code": 1,
  "Message": "ok",
  "Data": {
    "Host": "127.0.0.1",
    "Port": "8899",
    "SaveDirectory": "/Users/username/Downloads",
    "TaskNumber": 8
  }
}

3. API参考

3.1 配置管理

3.1.1 获取配置

• URL: /api/config
• 方法: GET
• 响应参数:

  字段名	类型	描述
  Host	string	API服务器地址
  Port	string	服务端口
  SaveDirectory	string	默认下载目录
  Quality	int	视频质量(0=自动,1=高清)

3.1.2 更新配置

• URL: /api/config
• 方法: POST
• 请求体:

{
  "SaveDirectory": "/new/download/path",
  "TaskNumber": 16
}

• 响应: {"Code":1,"Message":"ok","Data":null}

3.2 资源下载

3.2.1 提交下载任务

• URL: /api/download
• 方法: POST
• 请求体:

{
  "MediaInfo": {
    "Url": "https://example.com/video.mp4",
    "Description": "示例视频",
    "Suffix": ".mp4",
    "OtherData": {"wx_file_formats": "1080p#720p#480p"}
  },
  "DecodeStr": "base64_encoded_key"
}

• 响应: {"Code":1,"Message":"ok","Data":null}

3.2.2 微信文件解密

• URL: /api/wxFileDecode
• 方法: POST
• 请求体:

{
  "MediaInfo": {
    "Url": "wx_file://xxx",
    "Suffix": ".mp4"
  },
  "Filename": "encrypted.dat",
  "DecodeStr": "base64_encoded_key"
}

• 响应:

{
  "Code":1,
  "Message":"ok",
  "Data":{
    "save_path":"/downloads/decrypted.mp4"
  }
}

3.3 系统控制

3.3.1 代理管理

API端点	方法	描述	请求体
/api/openSystemProxy	POST	启用系统代理	{}
/api/unsetSystemProxy	POST	禁用系统代理	{}
/api/isProxy	GET	查询代理状态	-

示例响应:

{
  "Code":1,
  "Message":"ok",
  "Data":{"value":true}
}

4. 数据模型

4.1 MediaInfo结构体

type MediaInfo struct {
    Url         string            `json:"Url"`         // 资源URL
    Description string            `json:"Description"` // 资源描述
    Suffix      string            `json:"Suffix"`      // 文件后缀
    SavePath    string            `json:"SavePath"`    // 保存路径
    OtherData   map[string]string `json:"OtherData"`   // 平台特定参数
}

4.2 响应格式

所有API统一使用ResponseData格式:

type ResponseData struct {
    Code    int         `json:"Code"`    // 1=成功,0=失败
    Message string      `json:"Message"` // 状态描述
    Data    interface{} `json:"Data"`    // 业务数据
}

5. 事件通知

通过WebSocket接收实时事件:

const ws = new WebSocket('ws://127.0.0.1:8899/ws')
ws.onmessage = (event) => {
    const data = JSON.parse(event.data)
    if (data.type === 'downloadProgress') {
        console.log(`进度: ${data.data.Message}`)
    }
}

事件类型:

• downloadProgress: 下载进度更新
• proxyStatusChange: 代理状态变更
• configUpdated: 配置更新通知

6. 错误处理

错误码	描述	解决方案
400	参数错误	检查请求体格式
403	证书未安装	调用/api/install安装证书
500	下载引擎异常	检查网络连接或资源URL

错误响应示例:

{
  "Code":0,
  "Message":"无效的URL格式",
  "Data":null
}

7. 集成示例

7.1 Python下载示例

import requests

API_URL = "http://127.0.0.1:8899/api"

def download_resource(url, decode_str):
    payload = {
        "MediaInfo": {
            "Url": url,
            "Suffix": ".mp4",
            "OtherData": {}
        },
        "DecodeStr": decode_str
    }
    response = requests.post(f"{API_URL}/download", json=payload)
    return response.json()

# 使用示例
result = download_resource("https://example.com/video", "base64_key")
print(result)

7.2 Node.js进度监听

const WebSocket = require('ws');
const ws = new WebSocket('ws://127.0.0.1:8899/ws');

ws.on('message', (data) => {
    const event = JSON.parse(data);
    if (event.type === 'downloadProgress') {
        const { Id, Status, Message } = event.data;
        console.log(`任务${Id}: ${Status} - ${Message}`);
    }
});

8. 高级配置

8.1 多线程下载

通过调整配置文件中的TaskNumber参数优化下载性能:

{
  "TaskNumber": 16,  // 线程数，建议设为CPU核心数的2倍
  "DownNumber": 5    // 同时下载任务数
}

8.2 自定义代理

{
  "UpstreamProxy": "http://proxy.example.com:8080",
  "DownloadProxy": true  // 启用代理下载
}

9. 常见问题

Q: 如何处理微信文件解密失败?
A: 确保DecodeStr使用正确的Base64编码密钥，且源文件未损坏。可通过/api/openFileDialog接口验证文件路径。

Q: 为什么下载的视频没有声音?
A: 部分平台采用分离音视频流传输，需确保OtherData中包含完整的格式信息。

10. 附录

10.1 MIME类型映射

MIME类型	资源类型	后缀
video/mp4	video	.mp4
audio/mpeg	audio	.mp3
image/jpeg	image	.jpg

10.2 开发资源

• 项目仓库: https://gitcode.com/GitHub_Trending/re/res-downloader
• 问题反馈: 通过仓库Issue提交
• 更新日志: 每个版本的API变更记录在CHANGELOG.md

---

© 2023 res-downloader开发团队
最后更新: 2025-09-07