API 接口文档 - 视频下载加速服务

📖 概述

本文档提供视频下载加速服务的 API 接口说明。服务支持三种下载方式：

本地下载：将视频下载到服务器本地，返回可访问的 URL
腾讯云 COS：下载后上传到腾讯云对象存储，支持自定义域名
阿里云 OSS：下载后上传到阿里云对象存储，支持自定义域名

🔗 基础信息

项目	说明
协议	HTTP/HTTPS
请求方式	POST
数据格式	JSON
编码	UTF-8

📝 请求头

Content-Type: application/json

💾 接口一：下载到本地服务器

POST /api/video/download-local

接口说明

将指定的视频链接下载到服务器本地，并返回可访问的 URL 地址。适合临时存储或内部使用场景。

请求参数

参数名	类型	必填	说明
videoUrl	string	是	视频文件的完整URL地址

请求示例

curl -X POST http://localhost:7001/api/video/download-local \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://videos.openai.com/az/files/xxx.mp4"
  }'

成功响应

{
  "success": true,
  "message": "下载成功",
  "data": {
    "url": "http://localhost:7001/public/videos/video_1703645878000.mp4",
    "filename": "video_1703645878000.mp4",
    "size": 10485760
  }
}

响应字段说明

字段	类型	说明
success	boolean	请求是否成功
message	string	返回消息
data.url	string	视频访问地址
data.filename	string	视频文件名
data.size	number	文件大小（字节）

失败响应

{
  "success": false,
  "message": "下载失败: 网络连接超时"
}

☁️ 接口二：下载并上传到腾讯云 COS

POST /api/video/download-cos

接口说明

将视频下载到服务器后，自动上传到腾讯云对象存储（COS），并返回 COS 访问地址。支持自定义域名配置。

请求参数

参数名	类型	必填	说明
videoUrl	string	是	视频文件的完整URL地址

请求示例

curl -X POST http://localhost:7001/api/video/download-cos \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://videos.openai.com/az/files/xxx.mp4"
  }'

成功响应

{
  "success": true,
  "message": "上传到 COS 成功",
  "data": {
    "url": "https://your-custom-domain.com/videos/video_1703645878000.mp4",
    "filename": "video_1703645878000.mp4",
    "size": 10485760
  }
}

响应字段说明

字段	类型	说明
success	boolean	请求是否成功
message	string	返回消息
data.url	string	COS 访问地址（使用自定义域名）
data.filename	string	视频文件名
data.size	number	文件大小（字节）

⚠️ 注意事项

需要在配置文件中正确配置腾讯云 COS 的密钥信息
确保 COS 存储桶已开启公共读权限或配置了正确的访问策略
上传成功后会自动删除本地临时文件

📤 接口三：下载并上传到阿里云 OSS

POST /api/video/download-oss

接口说明

将视频下载到服务器后，自动上传到阿里云对象存储（OSS），并返回 OSS 访问地址。支持自定义域名配置。

请求参数

参数名	类型	必填	说明
videoUrl	string	是	视频文件的完整URL地址

请求示例

curl -X POST http://localhost:7001/api/video/download-oss \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://videos.openai.com/az/files/xxx.mp4"
  }'

成功响应

{
  "success": true,
  "message": "上传到 OSS 成功",
  "data": {
    "url": "https://your-custom-domain.com/videos/video_1703645878000.mp4",
    "filename": "video_1703645878000.mp4",
    "size": 10485760
  }
}

响应字段说明

字段	类型	说明
success	boolean	请求是否成功
message	string	返回消息
data.url	string	OSS 访问地址（使用自定义域名或默认域名）
data.filename	string	视频文件名
data.size	number	文件大小（字节）

⚠️ 注意事项

需要在配置文件中正确配置阿里云 OSS 的密钥信息
确保 OSS 存储桶已开启公共读权限或配置了正确的访问策略
上传成功后会自动删除本地临时文件

❌ 错误码说明

常见错误信息

错误信息	说明	解决方案
视频链接不能为空	未提供 videoUrl 参数	检查请求体中是否包含 videoUrl 字段
下载失败: 网络连接超时	源视频链接无法访问或网络异常	检查视频链接是否有效，或稍后重试
上传失败: 密钥配置错误	云服务密钥配置不正确	检查 config 文件中的密钥配置
上传失败: 存储桶不存在	配置的存储桶名称错误	检查存储桶名称和地域配置

HTTP 状态码

状态码	说明
200	请求成功（业务逻辑成功或失败通过 success 字段判断）
400	请求参数错误
500	服务器内部错误

💡 完整示例

JavaScript / Node.js

// 使用 fetch API
const downloadVideo = async () => {
  try {
    const response = await fetch('http://localhost:7001/api/video/download-local', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        videoUrl: 'https://videos.openai.com/az/files/xxx.mp4',
      }),
    });

    const data = await response.json();
    
    if (data.success) {
      console.log('下载成功:', data.data.url);
    } else {
      console.error('下载失败:', data.message);
    }
  } catch (error) {
    console.error('请求失败:', error);
  }
};

downloadVideo();

Python

import requests
import json

def download_video():
    url = 'http://localhost:7001/api/video/download-local'
    headers = {'Content-Type': 'application/json'}
    data = {
        'videoUrl': 'https://videos.openai.com/az/files/xxx.mp4'
    }
    
    try:
        response = requests.post(url, headers=headers, data=json.dumps(data))
        result = response.json()
        
        if result['success']:
            print(f"下载成功: {result['data']['url']}")
        else:
            print(f"下载失败: {result['message']}")
    except Exception as e:
        print(f"请求失败: {str(e)}")

download_video()

PHP

<?php
$url = 'http://localhost:7001/api/video/download-local';
$data = array(
    'videoUrl' => 'https://videos.openai.com/az/files/xxx.mp4'
);

$options = array(
    'http' => array(
        'header'  => "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);

if ($response['success']) {
    echo "下载成功: " . $response['data']['url'];
} else {
    echo "下载失败: " . $response['message'];
}
?>

📚 API 接口文档

📑 快速导航

📖 概述

🔗 基础信息

📝 请求头

💾 接口一：下载到本地服务器

接口说明

请求参数

请求示例

成功响应

响应字段说明

失败响应

☁️ 接口二：下载并上传到腾讯云 COS

接口说明

请求参数

请求示例

成功响应

响应字段说明

📤 接口三：下载并上传到阿里云 OSS

接口说明

请求参数

请求示例

成功响应

响应字段说明

❌ 错误码说明

常见错误信息

HTTP 状态码

💡 完整示例

JavaScript / Node.js

Python

PHP