How jacky-xbb/faceless-video-api works
Project Type and Purpose
• This is a backend API service (FastAPI) for automated, AI-powered faceless video creation.
• It exposes REST endpoints for authentication, story generation, image creation, and video compilation.
• It leverages external AI services (OpenAI/Azure, FAL, Replicate), a PostgreSQL database, and Cloudflare R2 for asset storage.
File Structure
• app/api: FastAPI routers & endpoints (auth.py, image.py, video.py)
• app/core: Configuration, logging, security utilities
• app/db: SQLAlchemy setup (base classes, session, init script)
• app/models: ORM models (User, Image, Video, VideoTask)
• app/schemas: Pydantic schemas for request/response validation
• app/services: Business-logic layers – story_generator, image_generator, video_generator, audio_generator, storage, video_task_processor, image_api
• app/utils: Helper functions (image processing, transitions, etc.)
• app/scripts: Database initialization script
• config.json: Feature toggles & model parameters
• resources/fonts & assets: Static assets & font files
• requirements.txt, .env.example, log_conf.yaml: Environment & deployment configuration
README for Architecture Insights
• RESTful API with Token-based authentication (OAuth2PasswordBearer)
• Async background processing for long-running tasks (video compilation)
• Progress tracking via polling endpoints (VideoTask entities)
• External integrations: OpenAI/Azure OpenAI, FAL flux (schnell/dev), Replicate, Cloudflare R2
Key Components
a. Clients
• Web or CLI clients consuming the API (Swagger UI, Postman, custom frontends)
b. API Layer
• FastAPI server (app/main.py)
• Routers: /v1/auth, /v1/image, /v1/video
• Dependency injection (config, security)
c. Authentication Service
• OAuth2PasswordBearer
• JWT token issuance & validation (app/core/security.py)
d. Business Logic Services
• StoryGenerator: calls OpenAI to create story text
• ImageAPI/ImageGenerator: calls FAL or Replicate to generate scene images
• AudioGenerator (TTS): creates audio narration
• VideoGenerator: compiles images + audio + subtitles into video
• VideoTaskProcessor: orchestrates background task workflow
• StorageService: uploads/fetches blobs from Cloudflare R2
e. Database
• PostgreSQL
• SQLAlchemy models & session (User, Image, Video, VideoTask)
f. Background Task Queue
• FastAPI’s BackgroundTasks or an external queue (represented logically)
g. External AI Services
• OpenAI / Azure OpenAI (story text)
• FAL Flux Schnell/Dev, Replicate (image generation)
h. Asset Storage
• Cloudflare R2 for images, audio, and final videos
Relationships & Data Flow
1. Client → FastAPI → Auth endpoint → JWT
2. Client (with token) → Story endpoint → StoryGenerator → OpenAI → returns story text → persisted in DB
3. Client → Image endpoint → ImageGenerator → FAL/Replicate → stores images in R2 → records in DB
4. Client → Video endpoint → VideoTaskProcessor → enqueues background job
5. Background job sequence:
• fetch story & images from DB/R2
• AudioGenerator (TTS) → audio file in R2
• VideoGenerator → combine images + audio + subtitles → upload final video to R2
• Update VideoTask status in DB
6. Client polls status endpoint → fetches final video URL
Architectural Patterns & Principles
• Layered Architecture: separation of API, core config, services, data access
• Dependency Injection via FastAPI for config, DB session, security
• Asynchronous/Background Processing for heavy tasks
• External Integration Points clearly abstracted in service modules
• Configuration-Driven Behavior (feature toggles in config.json)