pyVideoTrans API接口开发实战
项目地址: https://gitcode.com/gh_mirrors/py/pyvideotrans 本文深入探讨了pyVideoTrans视频翻译配音工具的RESTful API架构设计与实现，涵盖了API设计原则、核心接口实现、任务队列管理、状态监控机制以及安全性与性能优化策略。文章详细介绍了语音识别、字幕翻译和语音合成三大核心功能的接口设计，以及多级任务队列架构和实时状态监控的实现方式，为开发者提供了完整的API集成方案。
RESTful API架构设计与实现
pyVideoTrans作为一款功能强大的视频翻译配音工具，其API接口采用了现代化的RESTful架构设计，为开发者提供了稳定、高效、易用的接口服务。本节将深入探讨其API架构设计理念、核心实现机制以及最佳实践。
API架构设计原则
pyVideoTrans的API设计遵循了RESTful架构的核心原则，确保接口的规范性、可扩展性和易用性：
1. 资源导向设计
API将视频处理的核心功能抽象为独立的资源实体：
2. 统一的响应格式
所有API接口采用标准化的JSON响应格式，确保客户端能够统一处理：
{
"code": 0, // 状态码：0-成功，非0-失败
"msg": "ok", // 状态消息
"task_id": "uuid" // 任务唯一标识
}
3. 异步任务处理机制
考虑到视频处理任务的耗时特性，API采用了异步任务处理模式：
核心API接口实现
1. Flask应用初始化
API服务基于Flask框架构建，提供了灵活的配置和扩展能力：
from flask import Flask, request, jsonify
from waitress import serve
# 应用初始化
app = Flask(__name__, static_folder=TARGET_DIR)
# 配置信息
HOST = "127.0.0.1"
PORT = 9011
config.exec_mode = 'api'
2. 任务队列管理
API采用先进先出（FIFO）的任务队列机制，确保任务处理的顺序性：
# 全局任务队列
config.dubb_queue = [] # 配音任务队列
config.trans_queue = [] # 翻译任务队列
config.prepare_queue = [] # 识别任务队列
# 任务状态管理
end_status_list = ['error', 'succeed', 'end', 'stop']
logs_status_list = ['logs']
3. 统一的参数验证机制
每个API接口都实现了严格的参数验证，确保输入数据的合法性：
def validate_tts_params(data):
"""验证TTS接口参数"""
required_params = ['name', 'tts_type', 'voice_role', 'target_language_code']
for param in required_params:
if not data.get(param):
return False, f"Missing required parameter: {param}"
# 文件存在性检查
name = data['name'].strip()
if not name.endswith('.srt') and '\n' not in name:
if not Path(name).exists():
return False, f"File {name} does not exist"
return True, "Validation passed"
接口详细设计与实现
1. 配音合成接口 (/tts)
该接口负责将字幕文件转换为语音文件，支持多种TTS引擎：
| 参数名 | 类型 | 必选 | 描述 | 示例值 |
|---|---|---|---|---|
| name | string | 是 | 字幕文件路径或内容 | "path/to/subtitle.srt" |
| tts_type | int | 是 | TTS引擎类型(0-11) | 0 (Edge-TTS) |
| voice_role | string | 是 | 配音角色 | "zh-CN-YunjianNeural" |
| target_language_code | string | 是 | 目标语言代码 | "zh-cn" |
@app.route('/tts', methods=['POST'])
def tts():
data = request.json
# 参数验证和处理
name = data.get('name', '').strip()
if not name:
return jsonify({"code": 1, "msg": "参数name不能为空"})
# 创建任务配置
cfg = {
"name": name,
"voice_role": data.get("voice_role"),
"target_language_code": data.get('target_language_code'),
"tts_type": int(data.get('tts_type', 0)),
# ... 其他参数
}
# 添加到任务队列
obj = tools.format_video(name, None)
trk = DubbingSrt(cfg)
config.dubb_queue.append(trk)
return jsonify({'code': 0, 'task_id': obj['uuid']})
2. 字幕翻译接口 (/translate_srt)
实现多语言字幕翻译功能，支持15种翻译引擎：
3. 语音识别接口 (/recogn)
将音视频文件转换为字幕文件，支持多种识别模式：
@app.route('/recogn', methods=['POST'])
def recogn():
data = request.json
name = data.get('name', '').strip()
if not Path(name).is_file():
return jsonify({"code": 1, "msg": f"文件 {name} 不存在"})
cfg = {
"recogn_type": int(data.get('recogn_type', 0)),
"split_type": data.get('split_type', 'all'),
"model_name": data.get('model_name', 'tiny'),
"is_cuda": bool(data.get('is_cuda', False)),
"detect_language": data.get('detect_language', '')
}
# 语言支持验证
is_allow = recognition.is_allow_lang(
langcode=cfg['detect_language'],
recogn_type=cfg['recogn_type']
)
错误处理与状态管理
1. 统一错误码体系
API定义了清晰的错误码分类体系：
| 错误码 | 含义 | 描述 |
|---|---|---|
| 0 | 成功 | 任务提交成功 |
| 1 | 参数错误 | 缺少必要参数或参数格式错误 |
| 2 | 文件错误 | 文件不存在或无法访问 |
| 3 | 队列满 | 任务队列已满 |
| 4 | 语言不支持 | 目标语言不被支持 |
| 5 | API配置错误 | 第三方服务配置缺失 |
2. 任务状态追踪
每个任务都有完整的生命周期状态管理：
性能优化策略
1. 资源隔离与并发控制
# 为每个任务创建独立的处理环境
obj['target_dir'] = TARGET_DIR + f'/{obj["uuid"]}'
obj['cache_folder'] = config.TEMP_DIR + f'/{obj["uuid"]}'
Path(obj['target_dir']).mkdir(parents=True, exist_ok=True)
2. 内存管理优化
采用流式处理和分块处理机制，避免大文件内存溢出：
def process_large_file(file_path, chunk_size=1024*1024):
"""分块处理大文件"""
with open(file_path, 'rb') as f:
while chunk := f.read(chunk_size):
yield process_chunk(chunk)
3. 缓存策略
实现智能缓存机制，避免重复处理：
def get_cache_key(task_config):
"""生成缓存键"""
return hashlib.md5(
f"{task_config['name']}_{task_config['tts_type']}_{task_config['voice_role']}".encode()
).hexdigest()
安全性与可靠性
1. 输入验证与过滤
def sanitize_filename(filename):
"""文件名安全处理"""
# 移除路径遍历攻击
filename = os.path.basename(filename)
# 移除危险字符
return re.sub(r'[^\w\.-]', '_', filename)
2. 超时与重试机制
def execute_with_timeout(command, timeout=300):
"""带超时的命令执行"""
try:
result = subprocess.run(
command,
timeout=timeout,
capture_output=True,
text=True
)
return result.returncode == 0, result.stdout
except subprocess.TimeoutExpired:
return False, "Timeout exceeded"
扩展性与维护性
1. 模块化设计
API采用模块化架构，便于功能扩展和维护：
2. 配置管理
支持动态配置加载和热更新：
def load_config():
"""加载API配置"""
config_path = Path(ROOT_DIR) / 'api_config.json'
if config_path.exists():
with open(config_path, 'r', encoding='utf-8') as f:
return json.load(f)
return DEFAULT_CONFIG
通过以上架构设计和实现，pyVideoTrans的RESTful API提供了一个稳定、高效、易扩展的视频处理服务接口，为开发者集成视频翻译配音功能提供了强有力的技术支持。
语音识别/翻译/合成接口详解
pyVideoTrans 提供了完整的 API 接口体系，支持语音识别、字幕翻译和语音合成三大核心功能。这些接口基于 Flask 框架构建，采用 RESTful 设计风格，为开发者提供了灵活的视频翻译和配音集成方案。
接口架构概览
pyVideoTrans API 采用模块化设计，每个功能模块都有独立的接口端点：
语音识别接口 (/recogn)
语音识别接口支持多种识别引擎，能够将音视频文件转换为字幕文本。
核心参数说明
| 参数名 | 类型 | 必选 | 说明 | 示例值 |
|---|---|---|---|---|
| name | string | 是 | 音视频文件绝对路径 | "/path/to/video.mp4" |
| recogn_type | int | 是 | 识别引擎类型 | 0 (faster-whisper) |
| model_name | string | 是 | 模型名称 | "tiny", "base", "small" |
| detect_language | string | 是 | 检测语言代码 | "zh", "en", "ja" |
| split_type | string | 否 | 分割类型 | "all" (整体), "avg" (均等) |
| is_cuda | boolean | 否 | CUDA 加速 | true, false |
支持的识别引擎
# 识别引擎类型枚举
RECOGN_ENGINES = {
0: "faster-whisper", # 本地快速 Whisper 模型
1: "openai-whisper", # OpenAI Whisper 本地模型
2: "Google识别API", # Google 云端识别
3: "zh_recogn", # 中文专用识别
4: "豆包模型识别", # 字节跳动豆包模型
5: "自定义识别API", # 自定义 API 接口
6: "智能AI识别API" # 智能AI云端 API
}
请求示例
import requests
import json
def recognize_audio():
"""语音识别接口调用示例"""
url = "http://127.0.0.1:9011/recogn"
payload = {
"name": "/path/to/audio.wav",
"recogn_type": 0,
"model_name": "base",
"detect_language": "zh",
"split_type": "all",
"is_cuda": False
}
response = requests.post(url, json=payload)
result = response.json()
if result["code"] == 0:
print(f"任务ID: {result['task_id']}")
# 后续可通过 task_status 接口查询进度
else:
print(f"错误: {result['msg']}")
字幕翻译接口 (/translate_srt)
字幕翻译接口支持多种翻译引擎，能够将字幕文件从一种语言翻译到另一种语言。
核心参数说明
| 参数名 | 类型 | 必选 | 说明 | 示例值 |
|---|---|---|---|---|
| name | string | 是 | SRT 文件路径或内容 | "/path/to/subtitle.srt" |
| translate_type | int | 是 | 翻译引擎类型 | 0 (Google翻译) |
| target_language | string | 是 | 目标语言代码 | "en", "zh-cn", "ja" |
| source_code | string | 否 | 源语言代码 | "zh", "en", "ja" |
支持的翻译引擎
# 翻译引擎类型枚举（部分）
TRANSLATE_ENGINES = {
0: "Google翻译",
1: "百度翻译",
2: "腾讯翻译",
3: "阿里翻译",
4: "Azure翻译",
5: "智能AI翻译",
6: "Claude翻译",
7: "DeepL翻译",
8: "DeepLx翻译",
9: "Gemini翻译",
# ... 更多引擎
}
多语言支持
pyVideoTrans 支持丰富的语言代码，包括：
| 语言 | 代码 | 语言 | 代码 |
|---|---|---|---|
| 简体中文 | zh-cn | 英语 | en |
| 繁体中文 | zh-tw | 法语 | fr |
| 日语 | ja | 德语 | de |
| 韩语 | ko | 西班牙语 | es |
| 俄语 | ru | 意大利语 | it |
请求示例
def translate_subtitle():
"""字幕翻译接口调用示例"""
url = "http://127.0.0.1:9011/translate_srt"
payload = {
"name": "/path/to/chinese.srt",
"translate_type": 0,
"target_language": "en",
"source_code": "zh"
}
response = requests.post(url, json=payload)
result = response.json()
if result["code"] == 0:
print(f"翻译任务ID: {result['task_id']}")
else:
print(f"翻译错误: {result['msg']}")
语音合成接口 (/tts)
语音合成接口支持多种 TTS 引擎，能够将文本转换为自然语音。
核心参数说明
| 参数名 | 类型 | 必选 | 说明 | 示例值 |
|---|---|---|---|---|
| name | string | 是 | SRT 文件路径或内容 | "/path/to/subtitle.srt" |
| tts_type | int | 是 | TTS 引擎类型 | 0 (Edge-TTS) |
| voice_role | string | 是 | 语音角色 | "zh-CN-YunjianNeural" |
| target_language_code | string | 是 | 目标语言代码 | "zh-cn" |
| voice_rate | string | 否 | 语速调整 | "+10%", "-5%" |
| volume | string | 否 | 音量调整 | "+5%", "-3%" |
| pitch | string | 否 | 音调调整 | "+10Hz", "-5Hz" |
| out_ext | string | 否 | 输出格式 | "mp3", "wav" |
| voice_autorate | boolean | 否 | 自动语速 | true, false |
支持的 TTS 引擎
# TTS 引擎类型枚举
TTS_ENGINES = {
0: "Edge-TTS", # Microsoft Edge 语音合成
1: "CosyVoice", # 网易 CosyVoice
2: "ChatTTS", # 聊天 TTS
3: "302.AI", # 302.AI 语音合成
4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
