{ "openapi": "3.0.3", "info": { "title": "Media & Link Analyzer API", "description": "High-performance microservice for Media Inspection, Async FFmpeg Processing & CPU-Optimized AI Engine (Fast-Whisper, Kokoro, RMBG, YuNet, Diarization).", "version": "1.0.11" }, "servers": [ { "url": "/", "description": "Current Server Instance" } ], "tags": [ { "name": "Download Engines", "description": "Universal Video, Audio, Gallery, Playlist & Live Stream Downloading (yt-dlp, aria2, gallery-dl, streamlink)" }, { "name": "AI Services", "description": "Artificial Intelligence Speech, Vision, Demixing & Dubbing" }, { "name": "Media Processing", "description": "FFmpeg Audio & Video Encoding, Trimming, Merging and Composition" }, { "name": "Metadata & Info", "description": "Remote Metadata Probing, Thumbnails, Waveforms and Fonts" }, { "name": "Jobs & Queue", "description": "Background Asynchronous Task Management & Cancellation" }, { "name": "System & Health", "description": "System Readiness, Metrics, and Error Logs" }, { "name": "Storage", "description": "Date-partitioned Storage Management and Cleanup" } ], "paths": { "/api/download": { "post": { "tags": [ "Download Engines" ], "summary": "Universal media download from 1,800+ sites (auto-selects best engine)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, "quality": { "type": "string", "enum": [ "best", "1080p", "720p", "480p", "360p", "audio_only" ], "default": "best" }, "format": { "type": "string", "example": "mp4", "default": "mp4" }, "extract_audio": { "type": "boolean", "default": false }, "audio_format": { "type": "string", "enum": [ "mp3", "m4a", "wav", "flac", "opus" ], "default": "mp3" }, "audio_quality": { "type": "string", "example": "320k", "default": "192k" }, "subtitles": { "type": "boolean", "default": false }, "subtitle_langs": { "type": "string", "example": "ar,en" }, "embed_thumbnail": { "type": "boolean", "default": false }, "engine": { "type": "string", "enum": [ "auto", "yt-dlp", "aria2", "gallery-dl", "streamlink", "scraper" ], "default": "auto" }, "proxy": { "type": "string", "example": "http://user:pass@host:port" }, "user_agent": { "type": "string" }, "async": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Download job queued or completed synchronously" } } } }, "/api/download/video": { "post": { "tags": [ "Download Engines" ], "summary": "Download video with custom resolution, codec, and subtitles", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "quality": { "type": "string", "default": "best" }, "format": { "type": "string", "default": "mp4" }, "subtitles": { "type": "boolean", "default": false }, "embed_thumbnail": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Video download job queued" } } } }, "/api/download/audio": { "post": { "tags": [ "Download Engines" ], "summary": "Extract and download high-quality audio track (MP3, M4A, WAV, FLAC, OPUS)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "format": { "type": "string", "enum": [ "mp3", "m4a", "wav", "flac", "opus" ], "default": "mp3" }, "quality": { "type": "string", "enum": [ "320k", "256k", "192k", "128k", "64k" ], "default": "192k" }, "embed_thumbnail": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Audio download job queued" } } } }, "/api/download/gallery": { "post": { "tags": [ "Download Engines" ], "summary": "Download image gallery, photo album or carousel (Instagram, Twitter, Reddit, etc.)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "engine": { "type": "string", "default": "gallery-dl" } } } } } }, "responses": { "200": { "description": "Gallery download job queued" } } } }, "/api/download/direct": { "post": { "tags": [ "Download Engines" ], "summary": "Multi-threaded high-speed direct file download via Aria2c", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "max_connections": { "type": "integer", "default": 8 }, "split": { "type": "integer", "default": 8 } } } } } }, "responses": { "200": { "description": "Direct download job queued" } } } }, "/api/download/playlist": { "post": { "tags": [ "Download Engines" ], "summary": "Download video/audio playlists and channel batches", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "max_items": { "type": "integer", "default": 50 }, "quality": { "type": "string", "default": "720p" } } } } } }, "responses": { "200": { "description": "Playlist download job queued" } } } }, "/api/download/live": { "post": { "tags": [ "Download Engines" ], "summary": "Record live streams (Twitch, YouTube Live, HLS/DASH) via Streamlink/yt-dlp", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "duration": { "type": "integer", "example": 300, "description": "Duration in seconds" }, "quality": { "type": "string", "default": "best" } } } } } }, "responses": { "200": { "description": "Live stream recording job queued" } } } }, "/api/admin/cookies": { "get": { "tags": [ "Download Engines" ], "summary": "Get current cookies status (file size, lines count, domain count, updated at)", "responses": { "200": { "description": "Cookies file statistics and domain summary" } } }, "post": { "tags": [ "Download Engines" ], "summary": "Upload or update Netscape-format cookies.txt for authenticated downloads", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "Netscape format cookies text" } } } } } }, "responses": { "200": { "description": "Cookies updated successfully" } } }, "delete": { "tags": [ "Download Engines" ], "summary": "Delete active cookies.txt file", "responses": { "200": { "description": "Cookies file deleted" } } } }, "/api/admin/cookies/test": { "post": { "tags": [ "Download Engines" ], "summary": "Test cookies validity against protected platforms (YouTube, Instagram)", "responses": { "200": { "description": "Validation test results" } } } }, "/api/system/update-engines": { "post": { "tags": [ "Download Engines", "System & Health" ], "summary": "Update yt-dlp, gallery-dl, and streamlink to latest upstream releases", "responses": { "200": { "description": "Update status and output" } } } }, "/api/v1/ai/models": { "get": { "tags": [ "AI Services" ], "summary": "List all AI models, package versions, and readiness status", "responses": { "200": { "description": "Detailed model inventory with versions and readiness" } } } }, "/api/v1/ai/remove-bg": { "post": { "tags": [ "AI Services" ], "summary": "Automatic AI Background Removal (BRIA RMBG-1.4)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "example": "https://example.com/photo.jpg" }, "format": { "type": "string", "enum": [ "png", "webp" ], "default": "png" }, "return_mask": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Job scheduled successfully (returns job_id)" } } } }, "/api/v1/ai/blur-faces": { "post": { "tags": [ "AI Services" ], "summary": "Detect human faces and apply privacy Gaussian blur (YuNet Face AI)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "blur_strength": { "type": "integer", "default": 31 }, "confidence": { "type": "number", "default": 0.6 } } } } } }, "responses": { "200": { "description": "Job scheduled successfully" } } } }, "/api/v1/ai/diarize": { "post": { "tags": [ "AI Services" ], "summary": "Speaker Diarization — identify who spoke when (3D-Speaker CAM++)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "num_speakers": { "type": "integer", "nullable": true } } } } } }, "responses": { "200": { "description": "Job scheduled successfully" } } } }, "/api/v1/media/split-scenes": { "post": { "tags": [ "AI Services" ], "summary": "Content-Aware Video Scene Cut Detection and automated splitting", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "threshold": { "type": "number", "default": 27 }, "min_scene_length": { "type": "number", "default": 1.5 }, "split_files": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Job scheduled successfully" } } } }, "/api/v1/ai/moderation": { "post": { "tags": [ "AI Services" ], "summary": "Media Content Safety & NSFW Moderation pre-screening", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } } } }, "responses": { "200": { "description": "Job scheduled successfully" } } } }, "/api/v1/ai/separate": { "post": { "tags": [ "AI Services" ], "summary": "Separate vocals/dialogue from background music (BS-RoFormer)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "stem": { "type": "string", "default": "all" }, "model": { "type": "string", "default": "bs-roformer" } } } } } }, "responses": { "200": { "description": "Returns dual stems: vocals and background" } } } }, "/api/v1/ai/transcribe": { "post": { "tags": [ "AI Services" ], "summary": "Speech-to-Text with millisecond word timestamps (Faster-Whisper)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "language": { "type": "string", "default": "auto" }, "format": { "type": "string", "enum": [ "json", "srt", "vtt" ], "default": "json" }, "word_timestamps": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Transcription result with timestamps" } } } }, "/api/v1/ai/synthesize": { "post": { "tags": [ "AI Services" ], "summary": "Natural Text-to-Speech synthesis (Kokoro-82M / Piper)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "voice": { "type": "string", "default": "default" }, "speed": { "type": "number", "default": 1 }, "format": { "type": "string", "default": "mp3" } } } } } }, "responses": { "200": { "description": "Synthesized audio" } } } }, "/api/v1/ai/clone-voice": { "post": { "tags": [ "AI Services" ], "summary": "Zero-shot voice cloning from audio sample (XTTS-v2)", "responses": { "200": { "description": "Voice clone job scheduled" } } } }, "/api/v1/ai/dub-pipeline": { "post": { "tags": [ "AI Services" ], "summary": "End-to-end Automated Dubbing Pipeline", "responses": { "200": { "description": "Full AI Dubbing job scheduled" } } } }, "/api/v1/ai/denoise": { "post": { "tags": [ "AI Services" ], "summary": "Neural speech noise and reverb reduction (DeepFilterNet3)", "responses": { "200": { "description": "Denoise job scheduled" } } } }, "/api/v1/ai/upscale": { "post": { "tags": [ "AI Services" ], "summary": "Super-Resolution image upscaler 2x / 4x (Real-ESRGAN)", "responses": { "200": { "description": "Upscale job scheduled" } } } }, "/api/v1/ai/translate": { "post": { "tags": [ "AI Services" ], "summary": "Neural machine translation across 200+ languages", "responses": { "200": { "description": "Translation result" } } } }, "/api/v1/ai/vad-trim": { "post": { "tags": [ "AI Services" ], "summary": "Voice Activity Detection & Smart Silence Trimming (Silero VAD)", "responses": { "200": { "description": "VAD result" } } } }, "/api/v1/ai/ocr": { "post": { "tags": [ "AI Services" ], "summary": "Optical Character Recognition in Arabic & English (RapidOCR)", "responses": { "200": { "description": "Extracted text" } } } }, "/api/convert": { "post": { "tags": [ "Media Processing" ], "summary": "Convert format of audio, video or image", "responses": { "200": { "description": "Job scheduled" } } } }, "/api/trim": { "post": { "tags": [ "Media Processing" ], "summary": "Trim audio or video clip", "responses": { "200": { "description": "Job scheduled" } } } }, "/api/trim-segments": { "post": { "tags": [ "Media Processing" ], "summary": "Cut multiple segments and stitch them into a single file", "responses": { "200": { "description": "Job scheduled" } } } }, "/api/delete-segments": { "post": { "tags": [ "Media Processing" ], "summary": "Delete unwanted segments from video and stitch remaining", "responses": { "200": { "description": "Job scheduled" } } } }, "/api/merge-media": { "post": { "tags": [ "Media Processing" ], "summary": "Sequentially concatenate multiple video files", "responses": { "200": { "description": "Job scheduled" } } } }, "/api/composite": { "post": { "tags": [ "Media Processing" ], "summary": "Composite multiple videos: PiP, Grid, Horizontal/Vertical Stack, Overlay", "responses": { "200": { "description": "Job scheduled" } } } }, "/api/compress": { "post": { "tags": [ "Media Processing" ], "summary": "Smart video compression with target size or CRF", "responses": { "200": { "description": "Job scheduled" } } } }, "/api/subtitles": { "post": { "tags": [ "Media Processing" ], "summary": "Burn-in Arabic / Latin styled subtitles into video", "responses": { "200": { "description": "Job scheduled" } } } }, "/api/watermark": { "post": { "tags": [ "Media Processing" ], "summary": "Add image or text watermark with position and opacity control", "responses": { "200": { "description": "Job scheduled" } } } }, "/api/reels-crop": { "post": { "tags": [ "Media Processing" ], "summary": "Crop 16:9 video to 9:16 vertical with blurred background", "responses": { "200": { "description": "Job scheduled" } } } }, "/api/info": { "post": { "tags": [ "Metadata & Info" ], "summary": "Remote probe of media metadata (duration, codecs, dimensions, bitrates) without full download", "responses": { "200": { "description": "Complete metadata" } } } }, "/api/thumbnail": { "post": { "tags": [ "Metadata & Info" ], "summary": "Generate thumbnail screenshot at specific second", "responses": { "200": { "description": "Thumbnail image" } } } }, "/api/waveform": { "post": { "tags": [ "Metadata & Info" ], "summary": "Generate visual audio waveform PNG", "responses": { "200": { "description": "Waveform image" } } } }, "/api/fonts": { "get": { "tags": [ "Metadata & Info" ], "summary": "List all installed Arabic and Latin fonts on system", "responses": { "200": { "description": "Fonts list" } } } }, "/api/jobs/{id}": { "get": { "tags": [ "Jobs & Queue" ], "summary": "Get real-time job status, progress, speed, ETA, and result", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job status" } } } }, "/api/jobs/{id}/cancel": { "post": { "tags": [ "Jobs & Queue" ], "summary": "Cancel a pending or running job and terminate its OS process", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancellation result" } } } }, "/api/health": { "get": { "tags": [ "System & Health" ], "summary": "System health, memory, disk, and queue stats", "responses": { "200": { "description": "System health report" } } } }, "/api/check": { "get": { "tags": [ "System & Health" ], "summary": "Verify FFmpeg and FFprobe binary availability", "responses": { "200": { "description": "FFmpeg availability" } } } }, "/api/errors": { "get": { "tags": [ "System & Health" ], "summary": "List recent system and processing errors", "responses": { "200": { "description": "Errors log" } } } } } }