Tech Stack
Python
FastAPI
OpenRouter
Gemini
MongoDB
Docker
Linux
Description
I developed an asynchronous FastAPI microservice for translating WebVTT subtitle files between languages using Google's Gemini model through OpenRouter.
The service processes translation jobs in the background, persists job state in MongoDB, and provides a polling-based workflow without blocking the API request.
The implementation was designed around defensive AI integration, with strict structured prompting, duplicate-job prevention, output validation, and recovery from common LLM formatting issues.
- Designed a structured LLM workflow that converts subtitle cues into a strict JSON array of [ID, text] and requires the model to preserve IDs exactly.
- Implemented asynchronous translation processing with FastAPI BackgroundTasks and a MongoDB-backed job lifecycle: pending → processing → completed/failed.
- Added idempotency checks to prevent duplicate translation jobs for the same video and language pair.
- Implemented defensive parsing and automatic recovery for common LLM output issues such as unexpected JSON formatting and markdown code fences.
- Validated subtitle IDs and failed jobs immediately when mismatches could corrupt timestamp alignment.
- Kept the service lightweight with FastAPI, OpenAI-compatible API access through OpenRouter, PyMongo, and standard Python libraries.
Page Info
AI Subtitle Translation API
A production-oriented translation microservice that processes WebVTT subtitle files asynchronously while preserving subtitle IDs and timestamp alignment.