VideoLingo API文档详解：RESTful接口使用指南
项目地址: https://gitcode.com/GitHub_Trending/vi/VideoLingo 概述
VideoLingo是一个专业的视频字幕处理平台，提供Netflix级的字幕切割、翻译、对齐和配音功能。本文档详细介绍了VideoLingo的RESTful API接口，帮助开发者通过编程方式集成视频处理能力。
快速开始
基础URL
https://api.videolingo.io/v1
认证方式
所有API请求都需要在Header中包含API密钥：
Authorization: Bearer YOUR_API_KEY
响应格式
所有API响应都采用JSON格式，包含以下字段：
| 字段名 | 类型 | 描述 |
|---|---|---|
code | integer | 状态码（200表示成功） |
message | string | 状态消息 |
data | object | 响应数据 |
timestamp | string | 时间戳 |
核心API接口
1. 视频上传接口
POST /videos/upload
Content-Type: multipart/form-data
请求参数：
file(required): 视频文件source_language(optional): 源语言代码（默认：en）target_language(optional): 目标语言代码（默认：zh-CN）
响应示例：
{
"code": 200,
"message": "Video uploaded successfully",
"data": {
"video_id": "vid_1234567890",
"filename": "demo.mp4",
"duration": 120.5,
"resolution": "1920x1080"
},
"timestamp": "2024-01-15T10:30:00Z"
}
2. 字幕处理接口
POST /videos/{video_id}/subtitles/process
请求体：
{
"process_type": "full", // full, translation_only, alignment_only
"whisper_model": "large-v3",
"demucs_separation": true,
"max_subtitle_length": 75,
"custom_terminology": {
"AI": "人工智能",
"ML": "机器学习"
}
}
处理状态流程图：
3. 配音处理接口
POST /videos/{video_id}/dubbing/process
请求体：
{
"tts_method": "azure_tts",
"voice_config": {
"voice": "zh-CN-YunfengNeural",
"speed": 1.0,
"pitch": 0
},
"audio_quality": "high"
}
支持的TTS方法对比：
| 方法 | 质量 | 延迟 | 成本 | 适用场景 |
|---|---|---|---|---|
azure_tts | ⭐⭐⭐⭐⭐ | 中等 | 中等 | 商业应用 |
openai_tts | ⭐⭐⭐⭐ | 低 | 高 | 高质量需求 |
edge_tts | ⭐⭐⭐ | 低 | 免费 | 测试和演示 |
fish_tts | ⭐⭐⭐⭐ | 中等 | 低 | 中文优化 |
voice_replication | ⭐⭐⭐⭐⭐ | 高 | 高 | 声音复刻 |
4. 任务状态查询接口
GET /tasks/{task_id}
响应示例：
{
"code": 200,
"message": "Task status retrieved",
"data": {
"task_id": "task_123456",
"video_id": "vid_1234567890",
"type": "subtitle_processing",
"status": "processing",
"progress": 65,
"current_step": "translation",
"estimated_time_remaining": "00:05:30",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:35:30Z"
},
"timestamp": "2024-01-15T10:35:30Z"
}
5. 结果下载接口
GET /videos/{video_id}/results
查询参数：
type:subtitle（字幕文件）、dubbed_video（配音视频）、original_subtitles（原始字幕）
响应示例：
{
"code": 200,
"message": "Results retrieved",
"data": {
"subtitle_files": [
{
"language": "zh-CN",
"format": "srt",
"download_url": "https://api.videolingo.io/download/sub_123.srt",
"size": "15.2KB"
}
],
"processed_videos": [
{
"type": "dubbed",
"format": "mp4",
"resolution": "1920x1080",
"download_url": "https://api.videolingo.io/download/vid_123_dubbed.mp4",
"size": "125.7MB"
}
]
},
"timestamp": "2024-01-15T10:40:00Z"
}
高级功能API
批量处理接口
POST /batch/process
Content-Type: application/json
请求体：
{
"tasks": [
{
"video_url": "https://example.com/video1.mp4",
"source_language": "en",
"target_language": "zh-CN",
"process_subtitles": true,
"process_dubbing": false
},
{
"video_url": "https://example.com/video2.mp4",
"source_language": "ja",
"target_language": "en",
"process_subtitles": true,
"process_dubbing": true,
"tts_config": {
"method": "azure_tts",
"voice": "en-US-JennyNeural"
}
}
],
"callback_url": "https://your-app.com/webhook/videolingo"
}
自定义术语管理
POST /terminology
Content-Type: application/json
请求体：
{
"domain": "technology",
"terms": {
"API": "应用程序接口",
"SDK": "软件开发工具包",
"Framework": "框架",
"Containerization": "容器化"
}
}
错误处理
常见错误码
| 错误码 | 描述 | 解决方案 |
|---|---|---|
400 | 请求参数错误 | 检查请求体格式和参数 |
401 | 认证失败 | 检查API密钥是否正确 |
403 | 权限不足 | 检查API密钥权限 |
404 | 资源不存在 | 检查视频ID或任务ID |
429 | 请求频率限制 | 降低请求频率 |
500 | 服务器内部错误 | 联系技术支持 |
错误响应示例
{
"code": 429,
"message": "Rate limit exceeded",
"data": {
"retry_after": 60,
"limit": 100,
"remaining": 0
},
"timestamp": "2024-01-15T10:30:00Z"
}
最佳实践
1. 异步处理模式
import requests
import time
def process_video_async(video_file, api_key):
# 上传视频
upload_response = requests.post(
"https://api.videolingo.io/v1/videos/upload",
files={"file": video_file},
headers={"Authorization": f"Bearer {api_key}"}
)
video_id = upload_response.json()["data"]["video_id"]
# 启动字幕处理
subtitle_task = requests.post(
f"https://api.videolingo.io/v1/videos/{video_id}/subtitles/process",
json={"process_type": "full"},
headers={"Authorization": f"Bearer {api_key}"}
)
task_id = subtitle_task.json()["data"]["task_id"]
# 轮询任务状态
while True:
status_response = requests.get(
f"https://api.videolingo.io/v1/tasks/{task_id}",
headers={"Authorization": f"Bearer {api_key}"}
)
status = status_response.json()["data"]["status"]
if status == "completed":
break
elif status == "failed":
raise Exception("Processing failed")
time.sleep(10) # 每10秒检查一次
# 获取结果
results = requests.get(
f"https://api.videolingo.io/v1/videos/{video_id}/results",
headers={"Authorization": f"Bearer {api_key}"}
)
return results.json()
2. Webhook集成
from flask import Flask, request
app = Flask(__name__)
@app.route('/webhook/videolingo', methods=['POST'])
def videolingo_webhook():
data = request.json
if data['event'] == 'task_completed':
video_id = data['video_id']
task_type = data['task_type']
# 处理完成通知
if task_type == 'subtitle_processing':
print(f"字幕处理完成: {video_id}")
elif task_type == 'dubbing_processing':
print(f"配音处理完成: {video_id}")
return {'status': 'ok'}
if __name__ == '__main__':
app.run(port=5000)
性能优化建议
1. 并发处理限制
2. 缓存策略
| 缓存类型 | 有效期 | 适用场景 |
|---|---|---|
| 视频元数据 | 24小时 | 频繁查询的视频信息 |
| 处理配置 | 1小时 | 常用处理配置模板 |
| 术语库 | 7天 | 领域特定术语翻译 |
| 任务状态 | 5分钟 | 实时状态查询 |
总结
VideoLingo API提供了一套完整的视频字幕处理和配音解决方案，支持从简单的字幕翻译到复杂的多语言配音工作流。通过合理的API设计和错误处理机制，开发者可以轻松地将专业的视频处理能力集成到自己的应用中。
关键特性包括：
- 完整的异步处理流水线
- 多TTS引擎支持
- 批量处理能力
- Webhook事件通知
- 详细的进度跟踪
建议开发者根据实际业务需求选择合适的处理配置，并合理使用缓存和并发控制来优化性能。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
