logo
l8ai/document/MediaConvert
Public
3
0
WeChat Login
CodeIssuesPull requestsEventsPackagesInsights
main
MediaConvert/README.md
帷幄庸者
docs: 更新API文档、部署文档和README
1780c78c

MediaConvert API - 多媒体处理服务

基于 OpenAI Whisper 和 FFmpeg 的多媒体处理 API 服务，支持语音转文本和音视频转码功能。

功能特性

  • 🎯 语音转文本：支持多种音频格式（MP3, WAV, M4A, FLAC, MP4 等）
  • 🎬 音视频转码：支持多种格式转换和参数调整
  • 🌍 支持 99+ 种语言的语音识别
  • ⚡ GPU 加速支持，提升处理速度
  • 🔄 异步任务处理，支持大文件处理
  • 📊 实时任务状态查询和监控
  • 🎛️ 灵活的参数配置和优先级管理
  • 📝 多种输出格式（文本、SRT字幕、JSON、音频、视频等）
  • 🐳 Docker 容器化部署，生产就绪
  • ☁️ S3/MinIO 对象存储支持，直接从云存储下载和上传文件
  • 🔄 统一任务API，简化接口调用
  • 📋 完整的API文档，支持多种调用方式

快速开始

方式一：Docker 部署（推荐）

生产环境部署

# 1. 拉取最新镜像
docker pull docker.cnb.cool/l8ai/document/mediaconvert:latest

# 2. 创建必要的目录（数据持久化）
mkdir -p data logs models task_workspace

# 3. 创建环境配置文件
cat > .env << 'EOF'
# 数据库配置
DB_TYPE=sqlite
SQLITE_DB_NAME=data/MediaConvert.db

# S3/MinIO配置（下载服务）
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
S3_ENDPOINT_URL=http://your-minio:9000
AWS_REGION=us-east-1

# S3/MinIO配置（上传服务）
UPLOAD_S3_ACCESS_KEY_ID=your_access_key
UPLOAD_S3_SECRET_ACCESS_KEY=your_secret_key
UPLOAD_S3_ENDPOINT_URL=http://your-minio:9000
UPLOAD_S3_REGION=us-east-1
UPLOAD_S3_BUCKET=ai-file

# 日志配置
LOG_LEVEL=20
LOG_FILES_DIR=/workspace/log_files

# GPU配置（如果有GPU）
WHISPER_DEVICE=cuda
FORCE_CPU=false
EOF

# 4. 启动服务（生产环境）
docker run -d \
  --name mediaconvert-api \
  --restart unless-stopped \
  -p 33080:80 \
  --env-file .env \
  -v $(pwd)/data:/workspace/data \
  -v $(pwd)/logs:/workspace/log_files \
  -v $(pwd)/models:/workspace/models \
  -v $(pwd)/task_workspace:/workspace/task_workspace \
  docker.cnb.cool/l8ai/document/mediaconvert:latest

GPU支持部署

# 启动服务（GPU加速）
docker run -d \
  --name mediaconvert-api \
  --restart unless-stopped \
  --gpus all \
  -p 33080:80 \
  --env-file .env \
  -v $(pwd)/data:/workspace/data \
  -v $(pwd)/logs:/workspace/log_files \
  -v $(pwd)/models:/workspace/models \
  -v $(pwd)/task_workspace:/workspace/task_workspace \
  docker.cnb.cool/l8ai/document/mediaconvert:latest

Docker Compose 部署（推荐）

# 1. 下载 docker-compose.yml
curl -O https://raw.githubusercontent.com/your-repo/mediaconvert-api/main/docker-compose.yml

# 2. 启动服务
docker-compose up -d

# 3. 查看服务状态
docker-compose ps

# 4. 查看日志
docker-compose logs -f

目录结构说明

./
├── data/                    # 数据库文件（持久化）
│   └── MediaConvert.db     # SQLite数据库
├── logs/                   # 日志文件（持久化）
│   ├── app.log            # 应用日志
│   └── error.log          # 错误日志
├── models/                 # 模型文件（持久化，可选）
│   ├── whisper/           # Whisper模型
│   └── huggingface/       # HuggingFace模型
├── task_workspace/         # 任务工作空间（持久化）
│   └── task_*/            # 各任务的临时文件
├── .env                   # 环境配置文件
└── docker-compose.yml     # Docker Compose配置

方式二：源码部署

环境要求

  • Python 3.8+
  • CUDA 支持的 GPU（可选，用于加速）
  • FFmpeg（用于音频处理）

安装依赖

# 使用国内镜像加速
pip install -r requirements.txt -i https://mirrors.cloud.tencent.com/pypi/simple

启动服务

python start.py

服务将在 http://localhost:80 启动。

服务验证

# 健康检查
curl "http://localhost:33080/api/tasks/health"

# 预期返回
{"status":"healthy","message":"Unified Task API is running"}

# Whisper服务检查
curl "http://localhost:33080/api/whisper/health"

# 预期返回
{"status":"healthy","message":"Whisper API is running"}

# 访问API文档
open http://localhost:33080/docs

API 使用说明

统一任务API（推荐）

创建语音转文本任务

POST /api/tasks/create

# S3存储方式（推荐）
curl -X POST "http://localhost:33080/api/tasks/create" \
  -F "bucket=gaojiaqi" \
  -F "file_path=audio.mp3" \
  -F "task_type=transcribe" \
  -F "language=zh" \
  -F "word_timestamps=true" \
  -F "priority=high"

# 本地文件上传
curl -X POST "http://localhost:33080/api/tasks/create" \
  -F "file_upload=@audio.mp3" \
  -F "task_type=transcribe" \
  -F "language=zh" \
  -F "priority=high"

创建音视频转码任务

# 高质量音频转码
curl -X POST "http://localhost:33080/api/tasks/create" \
  -F "bucket=gaojiaqi" \
  -F "file_path=video.mp4" \
  -F "task_type=transcode" \
  -F "transcode_type=audio_high" \
  -F "output_format=mp3"

# H264视频转码
curl -X POST "http://localhost:33080/api/tasks/create" \
  -F "bucket=gaojiaqi" \
  -F "file_path=video.mp4" \
  -F "task_type=transcode" \
  -F "transcode_type=video_h264" \
  -F "output_format=mp4" \
  -F "resolution=1280x720"

查询任务结果

# 根据任务ID查询
curl "http://localhost:33080/api/tasks/query/{task_id}"

# 根据bucket和文件路径查询
curl "http://localhost:33080/api/tasks/query?bucket=gaojiaqi&file_url=s3://gaojiaqi/audio.mp3"

专用API

Whisper专用API

POST /api/tasks/whisper/create

curl -X POST "http://localhost:33080/api/tasks/whisper/create" \
  -F "bucket=gaojiaqi" \
  -F "file_path=audio.mp3" \
  -F "language=zh" \
  -F "word_timestamps=true" \
  -F "priority=high"

转码专用API

POST /api/tasks/transcode/create

curl -X POST "http://localhost:33080/api/tasks/transcode/create" \
  -F "bucket=gaojiaqi" \
  -F "file_path=video.mp4" \
  -F "transcode_type=audio_high" \
  -F "output_format=mp3"

响应示例

{
  "code": 200,
  "message": "统一任务创建成功: 类型=transcribe, 文件来源=s3",
  "data": {
    "task_id": 19,
    "status": "queued",
    "task_type": "transcribe",
    "file_name": "audio.mp3",
    "file_url": "s3://gaojiaqi/audio.mp3",
    "created_at": "2025-08-08T14:50:00.123456",
    "priority": "high",
    "result_url": "http://localhost:33080/api/tasks/query/19"
  }
}

任务状态说明

状态说明下一步
queued任务已排队，等待处理继续等待
processing任务正在处理中继续等待
completed✅ 任务已完成获取结果
failed❌ 任务处理失败检查错误信息

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "task_id": 18,
    "status": "completed",
    "task_type": "transcribe",
    "file_name": "audio.mp3",
    "file_url": "s3://gaojiaqi/audio.mp3",
    "ai_file_path": [
      "gaojiaqi/audio/whisper/transcription_result.json",
      "gaojiaqi/audio/whisper/transcription_text.txt",
      "gaojiaqi/audio/whisper/transcription_timeline.txt",
      "gaojiaqi/audio/whisper/transcription_subtitles.srt"
    ],
    "s3_urls": [
      "http://shenben.club:9000/ai-file/gaojiaqi/audio/whisper/transcription_result.json",
      "http://shenben.club:9000/ai-file/gaojiaqi/audio/whisper/transcription_text.txt",
      "http://shenben.club:9000/ai-file/gaojiaqi/audio/whisper/transcription_timeline.txt",
      "http://shenben.club:9000/ai-file/gaojiaqi/audio/whisper/transcription_subtitles.srt"
    ],
    "result": {
      "text": "这是转录的完整文本内容...",
      "language": "zh",
      "segments": [
        {
          "id": 0,
          "start": 0.0,
          "end": 5.0,
          "text": "这是第一段文本"
        }
      ]
    },
    "task_processing_time": 100.98
  }
}

配置说明

环境变量配置

主要配置通过环境变量或.env文件设置：

数据库配置

DB_TYPE=sqlite                    # 数据库类型
SQLITE_DB_NAME=data/MediaConvert.db  # SQLite数据库文件路径

S3/MinIO配置

# 下载服务配置
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
S3_ENDPOINT_URL=http://your-minio:9000
AWS_REGION=us-east-1

# 上传服务配置
UPLOAD_S3_ACCESS_KEY_ID=your_access_key
UPLOAD_S3_SECRET_ACCESS_KEY=your_secret_key
UPLOAD_S3_ENDPOINT_URL=http://your-minio:9000
UPLOAD_S3_REGION=us-east-1
UPLOAD_S3_BUCKET=ai-file

模型和性能配置

WHISPER_DEVICE=cuda              # 设备类型：cuda/cpu
FORCE_CPU=false                  # 强制使用CPU
LOG_LEVEL=20                     # 日志级别
MAX_FILE_SIZE=2147483648         # 最大文件大小（2GB）

高级配置

详细配置选项请参考：config/settings.py

性能优化

GPU 加速

# 检查 CUDA 可用性
docker run --rm --gpus all docker.cnb.cool/l8ai/document/mediaconvert:latest \
  python -c "import torch; print('CUDA available:', torch.cuda.is_available())"

# 检查GPU状态
nvidia-smi

模型选择

模型大小速度准确性推荐用途
tiny39MB最快较低实时转录
base74MB快中等快速处理
small244MB中等良好平衡选择
medium769MB较慢很好高质量转录
large-v31550MB慢最佳最高质量（默认）

并发优化

# 调整并发任务数（通过环境变量）
MAX_CONCURRENT_TASKS=3

# 监控系统资源
docker stats mediaconvert-api

故障排除

常见问题

  1. CUDA 内存不足

    # 修改环境变量使用 CPU
echo "FORCE_CPU=true" >> .env
docker restart mediaconvert-api

  2. 容器启动失败

    # 查看容器日志
docker logs mediaconvert-api

# 检查端口占用
netstat -tlnp | grep :80

# 检查磁盘空间
df -h

  3. 任务处理失败

    # 查看任务详情
curl "http://localhost:33080/api/tasks/query/{task_id}"

# 查看应用日志
tail -f logs/app.log

  4. S3连接问题

    # 测试S3连接
curl "http://your-minio:9000"

# 验证S3配置
docker exec mediaconvert-api env | grep S3

监控和维护

# 查看容器状态
docker ps
docker stats mediaconvert-api

# 查看日志
docker logs -f mediaconvert-api
tail -f logs/app.log

# 重启服务
docker restart mediaconvert-api

# 更新镜像
docker pull docker.cnb.cool/l8ai/document/mediaconvert:latest
docker-compose down && docker-compose up -d

文档和资源

完整文档

在线API文档

启动服务后，访问以下地址查看交互式API文档：

  • Swagger UI: http://localhost:33080/docs
  • ReDoc: http://localhost:33080/redoc

支持的文件格式

音频格式

  • MP3, WAV, M4A, FLAC, AAC, OGG

视频格式

  • MP4, AVI, MOV, MKV, WEBM, FLV

文件大小限制

  • S3存储：无限制（推荐大文件使用）
  • 本地上传：2GB
  • HTTP URL：取决于源服务器

技术架构

系统组件

  • FastAPI: Web框架和API服务
  • OpenAI Whisper: 语音转文本引擎
  • FFmpeg: 音视频处理引擎
  • SQLite: 任务数据存储
  • S3/MinIO: 对象存储支持
  • Docker: 容器化部署

存储结构

ai-file bucket/
├── {原始bucket}/
│   └── {文件路径(去掉后缀)}/
│       ├── whisper/              # 语音转文本结果
│       │   ├── transcription_result.json
│       │   ├── transcription_text.txt
│       │   ├── transcription_timeline.txt
│       │   └── transcription_subtitles.srt
│       └── ffmpeg/               # 转码结果
│           └── output_file.mp3

测试验证

本地测试

  1. 启动服务：
python main.py
  1. 测试转码任务：
# 移动端转码
curl -X POST "http://localhost:33080/api/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "s3://gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人.mp4",
    "task_type": "transcode",
    "transcode_type": "mobile_high"
  }'

# PC端转码
curl -X POST "http://localhost:33080/api/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "s3://gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人.mp4",
    "task_type": "transcode",
    "transcode_type": "pc_high"
  }'

# 4K转码
curl -X POST "http://localhost:33080/api/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "s3://gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人.mp4",
    "task_type": "transcode",
    "transcode_type": "4k_standard"
  }'
  1. 测试转录任务：
curl -X POST "http://localhost:33080/api/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "s3://gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人.mp4",
    "task_type": "transcribe",
    "language": "zh"
  }'
  1. 查询任务状态：
curl "http://localhost:33080/api/tasks/query/{task_id}"

测试结果

✅ 完整功能验证（2025-08-09）

测试环境：

  • GPU: NVIDIA L20 (44.53GB显存)
  • 测试文件: 145MB，131分钟视频
  • 所有任务均成功完成并上传到S3

测试结果：

  1. 移动端视频转码 ✅ 成功

  2. PC端视频转码 ✅ 成功

  3. 4K高清视频转码 ✅ 成功

  4. 音频文本转录 ✅ 成功

验证要点：

  • ✅ S3文件下载正常
  • ✅ GPU加速转码正常
  • ✅ Whisper语音转录正常
  • ✅ S3文件上传正常
  • ✅ 文件复用机制正常
  • ✅ 并发处理能力正常
  • ✅ 系统性能稳定

版本信息

  • 当前版本: v1.0.7
  • Docker镜像: docker.cnb.cool/l8ai/document/mediaconvert:latest
  • API版本: v1.0
  • 最后更新: 2025-08-09

许可证

Apache License 2.0

贡献

欢迎提交 Issue 和 Pull Request！

开发环境设置

# 克隆仓库
git clone https://github.com/your-repo/mediaconvert-api.git
cd mediaconvert-api

# 安装依赖
pip install -r requirements.txt -i https://mirrors.cloud.tencent.com/pypi/simple

# 启动开发服务
python start.py

提交规范

  • 功能开发：feat: 添加新功能
  • 问题修复：fix: 修复问题
  • 文档更新：docs: 更新文档
  • 性能优化：perf: 性能优化
© 2026 Tencent, Inc. Supported by Tencent Cloud
About Us
Privacy Policy
Terms of Service
SLA
API
Docs
Showcase
Feedback
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
京ICP备11018762号-111
粤公网安备44030002006058号粤公网安备44030002006058号