Feat: Advanced API Key Management (Firebase rotation, deactivation logic), Swagger UI improvements, and bug fixes.

core/analyze.py

@@ -14,23 +14,67 @@ except Exception:
     print("⚠️ Firebase not configured, falling back to local SQLite.")
     db = DatabaseManager(use_firebase=False)
 
-# Retrieve API Key from Secure Storage
-# 1. Try to get from Database
-api_key = db.get_key("openrouter")
-
-# 2. If not in DB, fallback to .env (Legacy support)
-if not api_key:
-    api_key = os.getenv("OPENROUTER_API_KEY")
-
-if not api_key:
-    print("❌ ERROR: OPENROUTER_API_KEY not found in Database or .env")
-    # We don't raise error here to allow module import, but client creation will fail if used.
-
 # Configure OpenAI Client
-client = OpenAI(
-    base_url="https://openrouter.ai/api/v1",
-    api_key=api_key
-)
+def get_working_client():
+    """
+    Retrieves a working OpenAI client by testing available keys.
+    Rotates through keys in DB, deactivates invalid ones, and falls back to .env.
+    """
+    print("🔍 Searching for a valid API Key...")
+    
+    # 1. Try keys from Database (Firebase/SQLite)
+    # We fetch ALL keys to rotate through them
+    db_keys_data = db.get_all_keys("openrouter") 
+    
+    if db_keys_data:
+        print(f"📊 Found {len(db_keys_data)} potential keys in Database.")
+        print(f"👥 Contributors: {', '.join([k['name'] for k in db_keys_data])}")
+    else:
+        print("⚠️ No keys found in Database for service 'openrouter'.")
+
+    for key_data in db_keys_data:
+        key = key_data['key']
+        contributor = key_data['name']
+        
+        print(f"👉 Testing Key provided by: {contributor}...")
+        
+        temp_client = OpenAI(
+            base_url="https://openrouter.ai/api/v1",
+            api_key=key
+        )
+        try:
+            # Enhanced Validation: Try a minimal generation to ensure quota/permissions
+            temp_client.chat.completions.create(
+                model="deepseek/deepseek-v3.2", # Use a cheap/fast model for check
+                messages=[{"role": "user", "content": "Hi"}],
+                max_tokens=1
+            )
+            print(f"✅ SUCCESS: Key from {contributor} is working and ready!")
+            return temp_client
+        except Exception as e:
+            # If 401 Unauthorized or Quota Exceeded, key is invalid -> Deactivate it
+            error_str = str(e).lower()
+            if "401" in error_str or "unauthorized" in error_str or "insufficient_quota" in error_str:
+                print(f"🚫 Invalid/Expired Key from {contributor}. Deactivating... ({str(e)})")
+                db.deactivate_key("openrouter", key)
+            else:
+                print(f"⚠️ Key check failed for {contributor} (Error: {str(e)})")
+                # We skip non-auth errors but don't deactivate immediately
+
+    # 2. If no DB keys work, fallback to .env
+    print("⚠️ No valid Community keys found. Trying local .env...")
+    env_key = os.getenv("OPENROUTER_API_KEY")
+    if env_key:
+        print("✅ Found valid API Key in .env.")
+        return OpenAI(
+            base_url="https://openrouter.ai/api/v1",
+            api_key=env_key
+        )
+    
+    print("❌ ERROR: No valid API keys found in Database or .env")
+    return None
+
+client = get_working_client()
 
 def analyze_transcript_gemini(transcript):
     """تحليل النص باستخدام OpenRouter (DeepSeek) للحصول على أفضل النتائج"""

core/database.py

@@ -68,6 +68,8 @@ class DatabaseManager:
         encrypted = self.security.encrypt_data(api_key)
         
         if self.use_firebase:
+            # Local import to ensure symbol availability
+            from firebase_admin import firestore
             # Save to Firestore
             # We use a hash of the encrypted key as document ID to prevent duplicates
             doc_id = f"{service_name}_{hash(encrypted)}"
@@ -92,6 +94,78 @@ class DatabaseManager:
             finally:
                 conn.close()
 
+    def save_key_with_meta(self, name: str, provider: str, api_key: str, community_message: str = None):
+        """
+        Encrypts and saves an API key with extra metadata.
+        Args:
+            name: User defined name for the key.
+            provider: The service provider (e.g. OpenAI).
+            api_key: The RAW api key string (will be encrypted here).
+            community_message: Optional message from the contributor.
+        """
+        # Encrypt the key SERVER-SIDE before storage
+        encrypted = self.security.encrypt_data(api_key)
+        
+        if self.use_firebase:
+            from firebase_admin import firestore
+            
+            # Create a unique ID based on provider and key hash to prevent duplicates
+            doc_id = f"{provider.lower()}_{hash(encrypted)}"
+            
+            data = {
+                'name': name,
+                'provider': provider.lower(),
+                'service': provider.lower(),
+                'encrypted_key': encrypted,
+                'is_active': True,
+                'added_at': firestore.SERVER_TIMESTAMP
+            }
+            
+            if community_message:
+                data['community_message'] = community_message
+            
+            self.collection.document(doc_id).set(data)
+            return True
+        else:
+            # Fallback to standard save for SQLite
+            self.save_key(provider, api_key)
+            return False
+
+    def deactivate_key(self, service_name: str, api_key: str):
+        """
+        Marks an API key as inactive instead of deleting it.
+        This preserves the contributor's name and message history.
+        """
+        encrypted = self.security.encrypt_data(api_key)
+        
+        if self.use_firebase:
+            from firebase_admin import firestore
+            # Reconstruct doc_id to find the document
+            doc_id = f"{service_name.lower()}_{hash(encrypted)}"
+            try:
+                self.collection.document(doc_id).update({
+                    'is_active': False,
+                    'deactivated_at': firestore.SERVER_TIMESTAMP
+                })
+                print(f"🚫 Deactivated invalid key for service: {service_name}")
+            except Exception as e:
+                print(f"⚠️ Failed to deactivate key in Firebase: {e}")
+        else:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            try:
+                cursor.execute('''
+                    UPDATE api_keys 
+                    SET is_active = 0 
+                    WHERE service_name = ? AND encrypted_key = ?
+                ''', (service_name.lower(), encrypted))
+                conn.commit()
+                print(f"🚫 Deactivated invalid key in SQLite")
+            except Exception as e:
+                print(f"⚠️ Failed to deactivate key in SQLite: {e}")
+            finally:
+                conn.close()
+
     def get_key(self, service_name: str) -> Optional[str]:
         """Retrieves a valid API key (Round-Robin or Random could be implemented here)."""
         # For now, just get the first available active key
@@ -118,19 +192,26 @@ class DatabaseManager:
                 return self.security.decrypt_data(row[0])
             return None
 
-    def get_all_keys(self, service_name: str) -> List[str]:
-        """Returns ALL valid decrypted keys for a service (useful for rotation)."""
-        keys = []
+    def get_all_keys(self, service_name: str) -> List[Dict]:
+        """Returns ALL valid decrypted keys with metadata for a service."""
+        keys_data = []
         if self.use_firebase:
             docs = self.collection.where('service', '==', service_name.lower())\
                                 .where('is_active', '==', True).stream()
             for doc in docs:
-                decrypted = self.security.decrypt_data(doc.to_dict()['encrypted_key'])
+                data = doc.to_dict()
+                decrypted = self.security.decrypt_data(data['encrypted_key'])
                 if decrypted:
-                    keys.append(decrypted)
+                    keys_data.append({
+                        'key': decrypted,
+                        'name': data.get('name', 'Anonymous'),
+                        'message': data.get('community_message', '')
+                    })
         else:
             conn = sqlite3.connect(self.db_path)
             cursor = conn.cursor()
+            # Note: SQLite schema might need migration to support 'name' if not present, 
+            # but we'll stick to basic key retrieval for local fallback
             cursor.execute('''
                 SELECT encrypted_key FROM api_keys 
                 WHERE service_name = ? AND is_active = 1
@@ -140,5 +221,9 @@ class DatabaseManager:
             for row in rows:
                 decrypted = self.security.decrypt_data(row[0])
                 if decrypted:
-                    keys.append(decrypted)
-        return keys
+                    keys_data.append({
+                        'key': decrypted,
+                        'name': 'Local User',
+                        'message': ''
+                    })
+        return keys_data

core/task_queue.py

@@ -62,11 +62,13 @@ class TaskManager:
         """Get the current status and result of a task."""
         return self.tasks.get(task_id)
 
-    def update_task_progress(self, task_id: str, progress: int, message: str = ""):
+    def update_task_progress(self, task_id: str, progress: int, message: str = "", result: Any = None):
         """Update the progress of a running task."""
         if task_id in self.tasks:
             self.tasks[task_id]["progress"] = progress
             self.tasks[task_id]["message"] = message
+            if result is not None:
+                self.tasks[task_id]["result"] = result
             logger.info(f"📈 Task {task_id} progress: {progress}% - {message}")
 
     def _worker(self):

main.py

@@ -1,6 +1,7 @@
-from fastapi import FastAPI, UploadFile, File, Form, BackgroundTasks
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException
 from fastapi.responses import JSONResponse, FileResponse
-from typing import Optional, Union, Any
+from fastapi.openapi.utils import get_openapi
+from typing import Optional, List
 from enum import Enum
 import os
 import uuid
@@ -13,7 +14,8 @@ from core.config import Config
 from core.logger import Logger
 from core.task_queue import TaskManager
 from core.database import DatabaseManager
-from pydantic import BaseModel
+from core.security import SecurityManager
+from pydantic import BaseModel, Field
 
 logger = Logger.get_logger(__name__)
 task_manager = TaskManager()
@@ -27,76 +29,154 @@ except Exception:
 # Ensure directories exist
 Config.setup_dirs()
 
-class APIKeyInput(BaseModel):
-    service: str
-    key: str
-    use_firebase: bool = False
+security_mgr = SecurityManager()
+
+# ─────────────────────────────────────────────
+# Pydantic Models
+# ─────────────────────────────────────────────
+
+class APIKeyCreate(BaseModel):
+    name: str = Field(
+        ..., 
+        title="Key Name", 
+        description="A friendly name to identify this key.",
+        json_schema_extra={"example": "My OpenAI Key"}
+    )
+    provider: str = Field(
+        ..., 
+        title="Provider Service", 
+        description="The name of the AI service provider (e.g., openai, anthropic).",
+        json_schema_extra={"example": "openai"}
+    )
+    api_key: str = Field(
+        ..., 
+        title="API Key", 
+        description="The actual API key string. It will be encrypted securely on the server.",
+        json_schema_extra={"example": "sk-..."}
+    )
+    community_message: Optional[str] = Field(
+        None, 
+        title="Community Message", 
+        description="Optional message to share with the community.",
+        json_schema_extra={"example": "Free to use for testing!"}
+    )
+
+class TaskStatusResponse(BaseModel):
+    task_id: str
+    status: str
+    progress: Optional[int] = None
+    message: Optional[str] = None
+    result: Optional[dict] = None
+
+class FileInfo(BaseModel):
+    filename: str
+    size: int
+    size_mb: float
+    download_url: str
+
+class FilesListResponse(BaseModel):
+    status: str
+    total_files: int
+    files: List[FileInfo]
+
+class QueuedTaskResponse(BaseModel):
+    status: str
+    task_id: str
+    message: str
+
+# ─────────────────────────────────────────────
+# Enums
+# ─────────────────────────────────────────────
 
 class VideoStyle(str, Enum):
-    cinematic = "cinematic"
-    cinematic_blur = "cinematic_blur"
-    vertical_full = "vertical_full"
-    split_vertical = "split_vertical"
-    split_horizontal = "split_horizontal"
+    cinematic         = "cinematic"
+    cinematic_blur    = "cinematic_blur"
+    vertical_full     = "vertical_full"
+    split_vertical    = "split_vertical"
+    split_horizontal  = "split_horizontal"
 
 class CaptionMode(str, Enum):
-    word = "word"
-    sentence = "sentence"
+    word           = "word"
+    sentence       = "sentence"
     highlight_word = "highlight_word"
 
 class CaptionStyle(str, Enum):
-    classic = "classic"
-    modern_glow = "modern_glow"
-    tiktok_bold = "tiktok_bold"
-    tiktok_neon = "tiktok_neon"
+    classic       = "classic"
+    modern_glow   = "modern_glow"
+    tiktok_bold   = "tiktok_bold"
+    tiktok_neon   = "tiktok_neon"
     youtube_clean = "youtube_clean"
-    youtube_box = "youtube_box"
+    youtube_box   = "youtube_box"
 
 class Language(str, Enum):
     auto = "auto"
-    ar = "ar"
-    en = "en"
-    hi = "hi"
-    zh = "zh"
-    es = "es"
-    fr = "fr"
-    de = "de"
-    ru = "ru"
-    ja = "ja"
-
-app = FastAPI(title="Auto-Clipping API")
+    ar   = "ar"
+    en   = "en"
+    hi   = "hi"
+    zh   = "zh"
+    es   = "es"
+    fr   = "fr"
+    de   = "de"
+    ru   = "ru"
+    ja   = "ja"
+
+# ─────────────────────────────────────────────
+# App Initialization
+# ─────────────────────────────────────────────
+
+app = FastAPI(
+    title="🎬 Auto-Clipping API",
+    description="""
+## Auto-Clipping API
+
+Automatically extract **viral-worthy clips** from long-form videos using AI.
+
+### Features
+- 🎯 **Smart clip detection** — AI analyzes and scores the most impactful moments
+- 🎨 **Multiple video styles** — Cinematic, TikTok vertical, split-screen, and more
+- 💬 **Auto captions** — Word-by-word, sentence, or highlight-word modes
+- 🌍 **Multi-language support** — Auto-detect or specify the output language
+- 🔔 **Webhook notifications** — Get notified when processing is done
+- 🔐 **Encrypted API key storage** — Community-shared provider keys with encryption
+
+### Workflow
+1. Upload your video via `/auto-clip`
+2. Poll `/status/{task_id}` for progress
+3. Download results via `/download/{filename}`
+    """,
+    version="1.0.0",
+    contact={
+        "name": "Auto-Clip Support",
+        "url": "https://github.com/your-repo",
+    },
+    license_info={
+        "name": "MIT",
+    },
+    openapi_tags=[
+        {
+            "name": "Clipping",
+            "description": "Upload videos and manage the auto-clipping pipeline."
+        },
+        {
+            "name": "Tasks",
+            "description": "Monitor task status and progress."
+        },
+        {
+            "name": "Files",
+            "description": "List and download processed video clips."
+        },
+        {
+            "name": "API Keys",
+            "description": "Manage community-shared AI provider API keys."
+        },
+    ]
+)
+
 clipper = VideoProcessor()
 
-@app.post("/api/keys")
-async def add_api_key(input_data: APIKeyInput):
-    """
-    Securely adds an API key to the database.
-    - service: Service name (e.g., 'openrouter', 'openai')
-    - key: The API key string
-    - use_firebase: If true, saves to community database (Firebase). If false, saves to local SQLite.
-    """
-    try:
-        # If user explicitly requested Firebase but it wasn't initialized globally
-        target_db = db_manager
-        if input_data.use_firebase and not db_manager.use_firebase:
-            # Try to init a temporary firebase manager
-            try:
-                target_db = DatabaseManager(use_firebase=True)
-            except Exception as e:
-                return JSONResponse(
-                    status_code=400, 
-                    content={"error": f"Firebase not configured: {str(e)}"}
-                )
-        
-        # Save key
-        target_db.save_key(input_data.service, input_data.key)
-        
-        dest = "Firebase (Community)" if input_data.use_firebase else "Local SQLite"
-        return {"message": f"API Key for {input_data.service} saved securely to {dest}."}
-        
-    except Exception as e:
-        logger.error(f"Error saving API key: {e}")
-        return JSONResponse(status_code=500, content={"error": str(e)})
+# ─────────────────────────────────────────────
+# Background Task Function
+# ─────────────────────────────────────────────
 
 def process_video_task(
     task_id: str,
@@ -112,44 +192,41 @@ def process_video_task(
     caption_mode: CaptionMode = CaptionMode.sentence,
     caption_style: CaptionStyle = CaptionStyle.classic
 ):
-    from moviepy.editor import VideoFileClip
-    full_video_clip = None
+    result = {}
     try:
-        # Helper for progress updates
         def update_progress(progress, message):
             task_manager.update_task_progress(task_id, progress, message)
-        
+
         update_progress(1, "Starting video analysis...")
-        
-        # 1. Analyze video
-        # Fix: Ensure 'words' mode is used for highlight_word too
-        timestamp_mode = "words" if caption_mode in (CaptionMode.word, CaptionMode.highlight_word) else "segments"
+
+        # 1. Determine timestamp mode
+        timestamp_mode = (
+            "words" if caption_mode in (CaptionMode.word, CaptionMode.highlight_word)
+            else "segments"
+        )
+
+        # 2. Analyze video
         scored_segments, total_duration, llm_moments = clipper.analyze_impact(
-            video_path, 
-            # video_clip removed as it's not supported
-            # language passed as target_language if needed, or source? 
-            # In processor.py: source_language=None (auto), target_language=...
-            # main.py seems to treat 'language' as the output/target language
+            video_path,
             target_language=language,
             timestamp_mode=timestamp_mode,
             progress_callback=update_progress
         )
-        
-        # 2. Select best clips
+
+        # 3. Select best clips
         best_clips = clipper.get_best_segments(
-            scored_segments, 
+            scored_segments,
             video_duration=total_duration
         )
-        
-        # 3. Final processing
+
+        # 4. Process and export clips
         output_files = clipper.process_clips(
-            video_path, 
-            best_clips, 
+            video_path,
+            best_clips,
             llm_moments,
             style=style,
             task_id=task_id,
-            language=language, # target language
-            # video_clip removed
+            language=language,
             playground_path=playground_path,
             audio_path=audio_path,
             bg_music_volume=bg_music_volume,
@@ -159,7 +236,7 @@ def process_video_task(
             caption_style=caption_style,
             progress_callback=update_progress
         )
-        
+
         result = {
             "status": "success",
             "task_id": task_id,
@@ -167,12 +244,13 @@ def process_video_task(
             "output_files": [os.path.basename(f) for f in output_files],
             "best_segments_info": best_clips
         }
-        
-        task_manager.update_task_progress(task_id, 100, "Completed successfully")
-        
+
+        # ✅ FIX: Store final result in task manager so /status returns it
+        task_manager.update_task_progress(task_id, 100, "Completed successfully", result=result)
+
     except Exception as e:
         import traceback
-        error_msg = f"❌ Error during processing: {str(e)}"
+        error_msg = f"Error during processing: {str(e)}"
         logger.error(error_msg)
         logger.error(traceback.format_exc())
         result = {
@@ -181,144 +259,89 @@ def process_video_task(
             "error": str(e),
             "traceback": traceback.format_exc()
         }
-    finally:
-        pass
+        # ✅ FIX: Store error result too
+        task_manager.update_task_progress(task_id, -1, error_msg, result=result)
 
-    # Send webhook
+    # Send webhook notification
     if webhook_url and webhook_url.strip() and webhook_url.startswith(('http://', 'https://')):
         try:
-            logger.info(f"📡 Sending results to webhook: {webhook_url}")
-            json_payload = json.dumps(result)
-            headers = {'Content-Type': 'application/json'}
-            
-            response = requests.post(webhook_url, data=json_payload, headers=headers, timeout=30)
-            
-            logger.info(f"✅ Webhook sent. Status Code: {response.status_code}")
+            logger.info(f"Sending results to webhook: {webhook_url}")
+            response = requests.post(
+                webhook_url,
+                data=json.dumps(result),
+                headers={'Content-Type': 'application/json'},
+                timeout=30
+            )
+            logger.info(f"Webhook sent. Status Code: {response.status_code}")
             if response.status_code >= 400:
-                logger.warning(f"⚠️ Webhook Response Error: {response.text}")
+                logger.warning(f"Webhook Response Error: {response.text}")
         except Exception as webhook_err:
-            logger.error(f"⚠️ Failed to send webhook: {webhook_err}")
-    else:
-        logger.info("ℹ️ No webhook URL provided, skipping webhook notification")
+            logger.error(f"Failed to send webhook: {webhook_err}")
 
     return result
 
-@app.get("/download/{filename}")
-async def download_video(filename: str):
-    """Download video from outputs folder"""
-    file_path = os.path.join(Config.OUTPUTS_DIR, "viral_clips", filename)
-    # Check if file exists in the specific viral_clips folder or root outputs
-    if not os.path.exists(file_path):
-         file_path = os.path.join(Config.OUTPUTS_DIR, filename)
-         
-    if os.path.exists(file_path):
-        return FileResponse(file_path, media_type='video/mp4', filename=filename)
-    return JSONResponse(status_code=404, content={"error": "File not found"})
+# ─────────────────────────────────────────────
+# Endpoints — Clipping
+# ─────────────────────────────────────────────
 
-@app.get("/status/{task_id}")
-async def get_task_status(task_id: str):
-    """Check the status of a specific task"""
-    status_info = task_manager.get_task_status(task_id)
-    if not status_info:
-        return JSONResponse(status_code=404, content={"error": "Task not found"})
-    
-    return status_info
-
-@app.get("/files")
-async def list_files():
-    """List all files in outputs folder"""
-    try:
-        files = []
-        # Search in viral_clips subdirectory as well
-        search_dirs = [Config.OUTPUTS_DIR, os.path.join(Config.OUTPUTS_DIR, "viral_clips")]
-        
-        for d in search_dirs:
-            if os.path.exists(d):
-                for filename in os.listdir(d):
-                    file_path = os.path.join(d, filename)
-                    if os.path.isfile(file_path) and filename.endswith('.mp4'):
-                        file_size = os.path.getsize(file_path)
-                        files.append({
-                            "filename": filename,
-                            "size": file_size,
-                            "size_mb": round(file_size / (1024 * 1024), 2),
-                            "download_url": f"/download/{filename}"
-                        })
-        
-        return {
-            "status": "success",
-            "total_files": len(files),
-            "files": files
-        }
-    except Exception as e:
-        return JSONResponse(status_code=500, content={"error": str(e)})
-
-@app.post("/clear")
-async def clear_files():
-    """Clear all files in upload, output and temp directories"""
-    try:
-        count = 0
-        for directory in [Config.UPLOADS_DIR, Config.OUTPUTS_DIR, Config.TEMP_DIR]:
-            if os.path.exists(directory):
-                files = glob.glob(os.path.join(directory, "**", "*"), recursive=True)
-                for f in files:
-                    try:
-                        if os.path.isfile(f):
-                            os.remove(f)
-                            count += 1
-                        elif os.path.isdir(f) and f != directory:
-                            # Don't delete the root directories themselves, just content
-                            # But glob returns directories too. 
-                            pass 
-                    except Exception as e:
-                        logger.error(f"Error deleting {f}: {e}")
-        return {"status": "success", "message": f"Cleared {count} files"}
-    except Exception as e:
-        return JSONResponse(status_code=500, content={"error": str(e)})
-
-@app.post("/auto-clip")
+@app.post(
+    "/auto-clip",
+    tags=["Clipping"],
+    response_model=QueuedTaskResponse,
+    summary="Upload & auto-clip a video",
+    responses={
+        200: {"description": "Task queued successfully"},
+        500: {"description": "Internal server error"},
+    }
+)
 async def create_auto_clip(
-    video: UploadFile = File(...),
-    playground_video: Optional[UploadFile] = File(None),
-    audio: Optional[UploadFile] = File(None),
-    background_image: Optional[UploadFile] = File(None),
-    style: VideoStyle = Form(VideoStyle.cinematic_blur),
-    caption_mode: CaptionMode = Form(CaptionMode.sentence),
-    caption_style: CaptionStyle = Form(CaptionStyle.classic),
-    webhook_url: Optional[str] = Form(None),
-    language: Language = Form(Language.auto),
-    bg_music_volume: float = Form(0.1),
-    secondary_video_volume: float = Form(0.2)
+    video: UploadFile = File(..., description="Main video file to clip (required)"),
+    playground_video: Optional[UploadFile] = File(None, description="Secondary video for split-screen styles"),
+    audio: Optional[UploadFile] = File(None, description="Background music file"),
+    background_image: Optional[UploadFile] = File(None, description="Background image for vertical styles"),
+    style: VideoStyle = Form(VideoStyle.cinematic_blur, description="Output video style"),
+    caption_mode: CaptionMode = Form(CaptionMode.sentence, description="Caption display mode"),
+    caption_style: CaptionStyle = Form(CaptionStyle.classic, description="Caption visual style"),
+    webhook_url: Optional[str] = Form(None, description="URL to notify when processing completes"),
+    language: Language = Form(Language.auto, description="Target language for captions"),
+    bg_music_volume: float = Form(0.1, ge=0.0, le=1.0, description="Background music volume (0.0 – 1.0)"),
+    secondary_video_volume: float = Form(0.2, ge=0.0, le=1.0, description="Secondary video volume (0.0 – 1.0)")
 ):
+    """
+    Upload a video to be automatically clipped into viral-ready short clips.
+
+    - The task runs **asynchronously** in the background.
+    - Use the returned `task_id` to check progress at `/status/{task_id}`.
+    - Download finished clips at `/download/{filename}`.
+    """
     task_id = uuid.uuid4().hex[:8]
-    
-    # 1. Save main video
+
+    # Save main video
     video_path = os.path.join(Config.UPLOADS_DIR, f"{task_id}_{video.filename}")
     with open(video_path, "wb") as f:
         shutil.copyfileobj(video.file, f)
-        
-    # 2. Save secondary video
+
+    # Save secondary (playground) video — only relevant for split styles
     playground_path = None
     if playground_video and playground_video.filename and style in [VideoStyle.split_vertical, VideoStyle.split_horizontal]:
         playground_path = os.path.join(Config.UPLOADS_DIR, f"{task_id}_{playground_video.filename}")
         with open(playground_path, "wb") as f:
             shutil.copyfileobj(playground_video.file, f)
-            
-    # 3. Save background image
+
+    # Save background image
     bg_image_path = None
     if background_image and background_image.filename:
         bg_image_path = os.path.join(Config.UPLOADS_DIR, f"{task_id}_{background_image.filename}")
         with open(bg_image_path, "wb") as f:
             shutil.copyfileobj(background_image.file, f)
 
-    # 4. Save audio file
+    # Save audio
     audio_path = None
     if audio and audio.filename:
         audio_path = os.path.join(Config.UPLOADS_DIR, f"{task_id}_{audio.filename}")
         with open(audio_path, "wb") as f:
             shutil.copyfileobj(audio.file, f)
 
-    # Add task to queue
     task_manager.add_task(
         process_video_task,
         task_id=task_id,
@@ -334,13 +357,201 @@ async def create_auto_clip(
         caption_mode=caption_mode,
         caption_style=caption_style
     )
-    
+
     return {
         "status": "queued",
         "task_id": task_id,
-        "message": "Task added to queue. Check status at /status/{task_id}"
+        "message": f"Task queued successfully. Track progress at /status/{task_id}"
+    }
+
+# ─────────────────────────────────────────────
+# Endpoints — Tasks
+# ─────────────────────────────────────────────
+
+@app.get(
+    "/status/{task_id}",
+    tags=["Tasks"],
+    summary="Get task status",
+    responses={
+        200: {"description": "Task status returned"},
+        404: {"description": "Task not found"},
+    }
+)
+async def get_task_status(task_id: str):
+    """
+    Poll the status and progress of a clipping task by its `task_id`.
+
+    **Progress values:**
+    - `1–99` → In progress
+    - `100` → Completed successfully
+    - `-1` → Failed with error
+    """
+    status_info = task_manager.get_task_status(task_id)
+    if not status_info:
+        raise HTTPException(status_code=404, detail=f"Task '{task_id}' not found.")
+    return status_info
+
+# ─────────────────────────────────────────────
+# Endpoints — Files
+# ─────────────────────────────────────────────
+
+@app.get(
+    "/download/{filename}",
+    tags=["Files"],
+    summary="Download a processed clip",
+    responses={
+        200: {"description": "Video file returned"},
+        404: {"description": "File not found"},
+    }
+)
+async def download_video(filename: str):
+    """Download a processed clip by filename."""
+    # Check viral_clips subdirectory first, then root outputs
+    file_path = os.path.join(Config.OUTPUTS_DIR, "viral_clips", filename)
+    if not os.path.exists(file_path):
+        file_path = os.path.join(Config.OUTPUTS_DIR, filename)
+
+    if not os.path.exists(file_path):
+        raise HTTPException(status_code=404, detail=f"File '{filename}' not found.")
+
+    return FileResponse(file_path, media_type="video/mp4", filename=filename)
+
+@app.get(
+    "/files",
+    tags=["Files"],
+    response_model=FilesListResponse,
+    summary="List all output files",
+)
+async def list_files():
+    """List all processed `.mp4` clips available for download."""
+    try:
+        files = []
+        search_dirs = [
+            Config.OUTPUTS_DIR,
+            os.path.join(Config.OUTPUTS_DIR, "viral_clips")
+        ]
+        seen = set()
+
+        for d in search_dirs:
+            if not os.path.exists(d):
+                continue
+            for filename in os.listdir(d):
+                if filename in seen or not filename.endswith(".mp4"):
+                    continue
+                file_path = os.path.join(d, filename)
+                if os.path.isfile(file_path):
+                    size = os.path.getsize(file_path)
+                    files.append({
+                        "filename": filename,
+                        "size": size,
+                        "size_mb": round(size / (1024 * 1024), 2),
+                        "download_url": f"/download/{filename}"
+                    })
+                    seen.add(filename)
+
+        return {
+            "status": "success",
+            "total_files": len(files),
+            "files": files
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.post(
+    "/clear",
+    tags=["Files"],
+    summary="Clear all uploaded and output files",
+    responses={200: {"description": "Files cleared"}, 500: {"description": "Error during cleanup"}}
+)
+async def clear_files():
+    """
+    ⚠️ **Danger zone** — deletes all files in upload, output, and temp directories.
+    This action is irreversible.
+    """
+    try:
+        count = 0
+        for directory in [Config.UPLOADS_DIR, Config.OUTPUTS_DIR, Config.TEMP_DIR]:
+            if not os.path.exists(directory):
+                continue
+            # ✅ FIX: Sort so files are deleted before their parent directories
+            all_paths = sorted(
+                glob.glob(os.path.join(directory, "**", "*"), recursive=True),
+                reverse=True
+            )
+            for path in all_paths:
+                try:
+                    if os.path.isfile(path):
+                        os.remove(path)
+                        count += 1
+                    elif os.path.isdir(path) and path != directory:
+                        # Only remove truly empty sub-directories
+                        if not os.listdir(path):
+                            os.rmdir(path)
+                except Exception as e:
+                    logger.error(f"Error deleting {path}: {e}")
+
+        return {"status": "success", "message": f"Cleared {count} files"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+# ─────────────────────────────────────────────
+# Endpoints — API Keys
+# ─────────��───────────────────────────────────
+
+@app.post(
+    "/api/key",
+    tags=["API Keys"],
+    summary="Add a community API key",
+    responses={
+        200: {"description": "Key saved successfully"},
+        400: {"description": "Firebase not configured"},
+        500: {"description": "Internal error"},
     }
+)
+async def add_api_key(
+    name: str = Form(..., description="A friendly name to identify this key."),
+    provider: str = Form(..., description="The AI service provider (e.g., openai)."),
+    api_key: str = Form(..., description="The actual API key string."),
+    community_message: Optional[str] = Form(None, description="Optional message to share.")
+):
+    """
+    **Add a new API Key to the Community Database.**
+
+    The key is **encrypted immediately** by the server before being stored in Firebase.
+    It is never stored in plain text.
+    """
+    try:
+        target_db = db_manager
+        if not db_manager.use_firebase:
+            try:
+                target_db = DatabaseManager(use_firebase=True)
+            except Exception as e:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Firebase not configured: {str(e)}"
+                )
+
+        target_db.save_key_with_meta(
+            name=name,
+            provider=provider,
+            api_key=api_key,
+            community_message=community_message
+        )
+
+        return {
+            "message": f"API key for provider '{provider}' saved securely to Firebase."
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in /api/key: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+# ─────────────────────────────────────────────
+# Entry Point
+# ─────────────────────────────────────────────
 
 if __name__ == "__main__":
     import uvicorn
-    uvicorn.run(app, host="0.0.0.0", port=7860)
+    uvicorn.run(app, host="0.0.0.0", port=7860)