feat: Add Quick Start Guide and enhance testing scripts

- Introduced QUICK_START.md for API testing instructions, including cookie management and testing options.
- Added test_upload_and_generation.py to validate image upload and media generation workflows.
- Created test_uvicorn.py for smoke testing the uvicorn server endpoints.
- Implemented html_scraper.py for extracting video URLs from Meta AI conversation pages.
- Developed test_network_patterns.py for comprehensive testing of API responses, SSE parsing, and cookie handling.

Author: mir-ashiq

.env.example

@@ -1,27 +1,113 @@
 # Meta AI API Cookie Configuration
 # Copy this file to .env and fill in your Meta AI cookies
 
-# Required cookies (Get these from your browser when logged into meta.ai)
+# =========================================
+# Required Cookies (MUST be provided)
+# =========================================
+# Get these from your browser when logged into https://meta.ai
+
+# Device/browser identifier cookie - REQUIRED
+# Extract from: DevTools > Application > Cookies > meta.ai
 META_AI_DATR=your_datr_cookie_value
+
+# Meta AI session cookie - REQUIRED  
+# Extract from: DevTools > Application > Cookies > meta.ai
 META_AI_ABRA_SESS=your_abra_sess_cookie_value
-META_AI_DPR=your_dpr_cookie_value
-META_AI_WD=your_wd_cookie_value
 
-# Optional cookies (recommended for better stability)
-#META_AI_JS_DATR=your_js_datr_value
-#META_AI_ABRA_CSRF=your_abra_csrf_value
+# =========================================
+# Critical Session Cookie (HIGHLY RECOMMENDED)
+# =========================================
+
+# Ecto session token - Maintains session state across requests
+# This is the most important cookie for API functionality
+# Format: <uuid>.v1%3A<base64-encoded-data>
+# Extract from: DevTools > Application > Cookies > meta.ai
+# NOTE: This changes frequently and may expire, so re-extract if API calls fail
+META_AI_ECTO_1_SESS=your_ecto_1_sess_value
+
+# =========================================
+# Recommended Optional Cookies
+# =========================================
+
+# Device pixel ratio (typical: 1 or 1.25)
+META_AI_DPR=1.25
+
+# Window dimensions (e.g., "1366x732" or "1920x1080")
+META_AI_WD=759x732
+
+# JavaScript-based datr variant
+META_AI_JS_DATR=your_js_datr_value
+
+# CSRF token for Meta AI
+META_AI_ABRA_CSRF=your_abra_csrf_value
+
+# Page state cookies (static values, usually: 1)
+META_AI_PS_L=1
+META_AI_PS_N=1
+
+# =========================================
+# Additional Cookies (For enhanced compatibility)
+# =========================================
 
-# Additional cookies for image/video generation
 META_AI_C_USER=your_c_user_value
 META_AI_XS=your_xs_value
 META_AI_FR=your_fr_value
 
+# Challenge verification cookie (auto-handled, optional)
+META_AI_RD_CHALLENGE=your_rd_challenge_value
+
+# =========================================
+# API Configuration
+# =========================================
+
 # Refresh interval in seconds (default: 3600 = 1 hour)
 META_AI_REFRESH_INTERVAL_SECONDS=3600
 
-# How to get cookies:
+# =========================================
+# Proxy Configuration (Optional)
+# =========================================
+
+# HTTP proxy URL (if needed)
+# Example: http://proxy.example.com:8080
+#META_AI_PROXY_HTTP=
+
+# HTTPS proxy URL (if needed)  
+# Example: http://proxy.example.com:8080
+#META_AI_PROXY_HTTPS=
+
+# =========================================
+# How to Extract Cookies
+# =========================================
 # 1. Open browser and go to https://meta.ai
-# 2. Open Developer Tools (F12)
-# 3. Go to Application/Storage > Cookies > https://meta.ai
-# 4. Copy the values for: datr, abra_sess, dpr, wd, c_user, xs, fr
-# 5. Paste them above (without quotes)
+# 2. Open Developer Tools (F12 or Ctrl+Shift+I)
+# 3. Go to "Application" or "Storage" tab
+# 4. Click on "Cookies" in the left sidebar
+# 5. Select "https://www.meta.ai" from the list
+# 6. Extract these cookies in order of importance:
+#
+#    CRITICAL:
+#    --------
+#    - ecto_1_sess (META_AI_ECTO_1_SESS) - Session state token - MOST IMPORTANT
+#    - datr (META_AI_DATR) - Device tracking - REQUIRED
+#    - abra_sess (META_AI_ABRA_SESS) - Session - REQUIRED
+#
+#    RECOMMENDED:
+#    -----------
+#    - _js_datr (META_AI_JS_DATR) - JavaScript datr
+#    - abra_csrf (META_AI_ABRA_CSRF) - CSRF protection
+#    - dpr (META_AI_DPR) - Device pixel ratio
+#    - wd (META_AI_WD) - Window dimensions
+#
+#    OPTIONAL:
+#    --------
+#    - ps_l (META_AI_PS_L) - Page state (usually 1)
+#    - ps_n (META_AI_PS_N) - Page state (usually 1)
+#    - c_user (META_AI_C_USER) - User ID
+#    - xs (META_AI_XS) - Session check
+#    - fr (META_AI_FR) - Friend request
+#
+# NOTE: ecto_1_sess is the PRIMARY session identifier.
+#       If API calls return empty responses, ecto_1_sess may be expired.
+#       Try re-extracting it from the browser.
+# 7. Paste the values above (without quotes)
+# 8. Rename this file from .env.example to .env

.gitignore

@@ -98,6 +98,11 @@ TEST_UPDATES.md
 FINAL_RESULTS.md
 VIDEO_BREAKTHROUGH.md
 IMPLEMENTATION_SUMMARY.md
+
+# =========================
+# Archive folder (old tests, debug files, etc.)
+# =========================
+archive/
 DEPLOYMENT_FIX.md
 GITHUB_ISSUE_RESPONSE.md
 QUICK_FIX_GUIDE.md