RunPod FastAPI Transcription Service

A simplified HTTP API-based solution for audio transcription using RunPod GPU pods. This replaces the complex SSH-based file transfer approach with simple HTTP requests.

🚀 Quick Start

1. Build and Deploy Container

# Use the automated deployment script
./deploy.sh your-docker-username

# Or manually:
docker build -t your-username/whisper-transcription .
docker push your-username/whisper-transcription

# Deploy to RunPod using the Docker image
# Set environment variable: RUNPOD_API_KEY=your-secret-api-key

2. Use the Client

# Install client dependencies
pip install requests

# Transcribe audio files
python transcribe_client.py /path/to/audio /path/to/output \
  --server https://your-pod-id.runpod.io:8080 \
  --api-key your-secret-api-key

📋 What's Included

Files Included:

• runpod_fastapi_server.py - FastAPI server with HTTP endpoints
• Dockerfile - Optimized Dockerfile without SSH
• transcribe_client.py - Simple Python client for uploads/downloads

Features:

• ✅ Simple HTTP API - No SSH keys or complex setup
• ✅ Individual file uploads - Upload files one-by-one with progress bars
• ✅ Extended timeouts - 30-minute timeouts + 3-attempt retry logic
• ✅ Real-time progress - tqdm progress bars and upload speed display
• ✅ Multi-job processing - Parallel processing with live status updates
• ✅ API key authentication - Simple security
• ✅ Auto cleanup - Server manages temporary files
• ✅ Multiple formats - Supports MP3, WAV, M4A, FLAC, OGG
• ✅ Robust error handling - Automatic retry and graceful failure recovery

🔧 API Endpoints

Upload Files

curl -X POST "https://your-pod.runpod.io:8080/upload" \
  -H "Authorization: Bearer your-api-key" \
  -F "files=@audio1.mp3" \
  -F "files=@audio2.mp3" \
  -F "model=turbo"

Check Status

curl "https://your-pod.runpod.io:8080/status/job-id" \
  -H "Authorization: Bearer your-api-key"

Download Results

curl "https://your-pod.runpod.io:8080/download/job-id" \
  -H "Authorization: Bearer your-api-key" \
  -o transcripts.zip

Health Check

curl "https://your-pod.runpod.io:8080/health" \
  -H "Authorization: Bearer your-api-key"

🎯 Usage Examples

Basic Usage

# Transcribe a directory of MP3s
python transcribe_client.py ~/podcasts ~/transcripts

# Transcribe a single file
python transcribe_client.py ~/audio/meeting.mp3 ~/transcripts

Advanced Usage

# Use different model
python transcribe_client.py ~/audio ~/output --model large-v3

# Custom server and API key
python transcribe_client.py ~/audio ~/output \
  --server https://abc123.runpod.io:8080 \
  --api-key your-secret-key

# Keep job on server (don't auto-cleanup)
python transcribe_client.py ~/audio ~/output --no-cleanup

Environment Variables

# Set default server and API key
export RUNPOD_SERVER_URL=https://your-pod.runpod.io:8080
export RUNPOD_API_KEY=your-secret-api-key

# Now you can use simple commands
python transcribe_client.py ~/audio ~/output

🏗️ Deployment Steps

1. RunPod Setup

1. Create RunPod account and get API key
2. Build and push Docker image to registry
3. Create pod with your Docker image
4. Set environment variable RUNPOD_API_KEY=your-secret-key
5. Expose port 8080

2. Local Client Setup

# Install Python dependencies
pip install requests

# Make client executable
chmod +x transcribe_client.py

# Test connection
python transcribe_client.py --help

🔒 Security

• API Key Authentication: All endpoints require Bearer token
• Input Validation: File type and model validation
• Temporary Storage: Files auto-deleted after processing
• Error Handling: Graceful error responses

🎚️ Model Options

• tiny - Fastest, lowest quality
• base - Fast, basic quality
• small - Good balance
• medium - Better quality
• large - Best quality, slower
• large-v2 - Enhanced large model
• large-v3 - Latest large model
• turbo - Default - 8x faster than large with similar quality

📊 Response Formats

Upload Response

{
  "job_id": "uuid-string",
  "status": "pending",
  "files_count": 5,
  "message": "Files uploaded successfully. Processing started.",
  "status_url": "/status/uuid-string"
}

Status Response

{
  "job_id": "uuid-string",
  "status": "processing",
  "created_at": "2024-01-01T12:00:00",
  "updated_at": "2024-01-01T12:05:00",
  "files_count": 5,
  "processed_count": 3,
  "failed_count": 0,
  "error": null,
  "download_url": "/download/uuid-string"
}

🛠️ Troubleshooting

Common Issues

1. Connection Failed

   # Check if pod is running
   curl https://your-pod.runpod.io:8080/health
   

2. Authentication Failed

   # Verify API key matches pod environment variable
   echo $RUNPOD_API_KEY
   

3. Upload Timeout

   # Check
   

...