{
  "openapi": "3.1.0",
  "info": {
    "title": "Vibeon Language Learning Platform API",
    "description": "Comprehensive language learning platform with unified TTS/STT services, translation, and learning features. Supports 100+ languages including Kinyarwanda with real AI/ML engines.",
    "version": "3.0.0",
    "contact": {
      "name": "Vibeon Support",
      "email": "support@vibeon.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "http://localhost:8000",
      "description": "Development server"
    },
    {
      "url": "https://api.vibeon.com",
      "description": "Production server"
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "User authentication and authorization"
    },
    {
      "name": "Translation",
      "description": "Text, audio, and document translation services"
    },
    {
      "name": "Voice Services",
      "description": "Unified Text-to-Speech (TTS) and Speech-to-Text (STT) services"
    },
    {
      "name": "Language Learning",
      "description": "Vocabulary, quizzes, progress tracking, and spaced repetition"
    },
    {
      "name": "Languages",
      "description": "Language information and capabilities"
    },
    {
      "name": "Health",
      "description": "System health and monitoring"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["Health"],
        "summary": "System Health Check",
        "description": "Comprehensive health check for all services",
        "operationId": "health_check",
        "responses": {
          "200": {
            "description": "System health status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/voice/health": {
      "get": {
        "tags": ["Voice Services"],
        "summary": "Voice Services Health Check",
        "description": "Check health of unified TTS/STT services",
        "operationId": "voice_health_check",
        "responses": {
          "200": {
            "description": "Voice services health status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VoiceHealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/voice/tts": {
      "post": {
        "tags": ["Voice Services"],
        "summary": "Text-to-Speech Generation",
        "description": "Convert text to speech using unified TTS service with multiple engines (gTTS, Edge TTS, Coqui TTS, pyttsx3) and intelligent fallback",
        "operationId": "text_to_speech",
        "security": [{"HTTPBearer": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TTSRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated speech audio",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TTSResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters"
          },
          "401": {
            "description": "Authentication required"
          },
          "500": {
            "description": "TTS generation failed"
          }
        }
      }
    },
    "/api/voice/stt": {
      "post": {
        "tags": ["Voice Services"],
        "summary": "Speech-to-Text Recognition",
        "description": "Convert speech to text using unified STT service with multiple engines (Whisper, Vosk, Speech Recognition) and intelligent fallback",
        "operationId": "speech_to_text",
        "security": [{"HTTPBearer": []}],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/STTRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recognized text",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/STTResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid audio file or parameters"
          },
          "401": {
            "description": "Authentication required"
          },
          "500": {
            "description": "STT recognition failed"
          }
        }
      }
    },
    "/api/voice/engines/status": {
      "get": {
        "tags": ["Voice Services"],
        "summary": "Get Engine Status",
        "description": "Get status of all available TTS and STT engines with their capabilities",
        "operationId": "get_engine_status",
        "security": [{"HTTPBearer": []}],
        "responses": {
          "200": {
            "description": "Engine status information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EngineStatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/voice/languages/{language_code}/engines": {
      "get": {
        "tags": ["Voice Services"],
        "summary": "Get Language Engines",
        "description": "Get available TTS and STT engines for a specific language",
        "operationId": "get_language_engines",
        "security": [{"HTTPBearer": []}],
        "parameters": [
          {
            "name": "language_code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "rw"
            },
            "description": "Language code (e.g., 'rw' for Kinyarwanda, 'en' for English)"
          }
        ],
        "responses": {
          "200": {
            "description": "Available engines for the language",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LanguageEnginesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/voice/tts/batch": {
      "post": {
        "tags": ["Voice Services"],
        "summary": "Batch Text-to-Speech",
        "description": "Convert multiple texts to speech in batch for efficiency",
        "operationId": "batch_text_to_speech",
        "security": [{"HTTPBearer": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchTTSRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch TTS results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchTTSResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/languages": {
      "get": {
        "tags": ["Languages"],
        "summary": "Get Supported Languages",
        "description": "Get all supported languages with their features and capabilities. This is the canonical endpoint for language information across the platform.",
        "operationId": "get_supported_languages",
        "parameters": [
          {
            "name": "include_features",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Whether to include detailed feature information"
          },
          {
            "name": "language_codes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated list of language codes to filter (optional)"
          }
        ],
        "responses": {
          "200": {
            "description": "List of supported languages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LanguagesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/languages/{language_code}": {
      "get": {
        "tags": ["Languages"],
        "summary": "Get Language Information",
        "description": "Get detailed information for a specific language including features, engines, and learning capabilities",
        "operationId": "get_language_info",
        "parameters": [
          {
            "name": "language_code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "rw"
            },
            "description": "ISO 639-1/639-3 language code (e.g., 'rw', 'en', 'es')"
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed language information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LanguageInfo"
                }
              }
            }
          }
        }
      }
    },
    "/api/vibeon/translate": {
      "post": {
        "tags": ["Translation"],
        "summary": "Translate Content",
        "description": "Translate text content for the Vibeon platform with context awareness and platform-specific optimizations",
        "operationId": "translate_content",
        "security": [{"HTTPBearer": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TranslationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Translation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranslationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/vibeon/translate/audio": {
      "post": {
        "tags": ["Translation"],
        "summary": "Translate Audio Content",
        "description": "Translate audio content (speech-to-text + translation) with multiple output formats and audio enhancement",
        "operationId": "translate_audio",
        "security": [{"HTTPBearer": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AudioTranslationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audio translation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioTranslationResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "HTTPBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "TTSRequest": {
        "type": "object",
        "required": ["text", "language"],
        "properties": {
          "text": {
            "type": "string",
            "description": "Text to convert to speech",
            "example": "Muraho, amakuru?"
          },
          "language": {
            "type": "string",
            "description": "Language code (e.g., 'en', 'rw', 'es')",
            "example": "rw"
          },
          "engine": {
            "type": "string",
            "enum": ["gtts", "pyttsx3", "edge-tts", "coqui"],
            "description": "TTS engine to use (auto-select if not specified)",
            "example": "edge-tts"
          },
          "quality": {
            "type": "string",
            "enum": ["low", "medium", "high", "premium"],
            "description": "Voice quality level",
            "default": "medium",
            "example": "high"
          },
          "speed": {
            "type": "number",
            "minimum": 0.5,
            "maximum": 2.0,
            "description": "Speech speed multiplier",
            "default": 1.0,
            "example": 1.2
          },
          "pitch": {
            "type": "number",
            "minimum": 0.5,
            "maximum": 2.0,
            "description": "Voice pitch multiplier",
            "default": 1.0,
            "example": 1.1
          },
          "volume": {
            "type": "number",
            "minimum": 0.0,
            "maximum": 1.0,
            "description": "Voice volume level",
            "default": 1.0,
            "example": 0.8
          },
          "voice_id": {
            "type": "string",
            "description": "Specific voice ID to use",
            "example": "rw-female-1"
          },
          "user_id": {
            "type": "string",
            "description": "User ID for tracking and personalization",
            "example": "user123"
          },
          "session_id": {
            "type": "string",
            "description": "Session ID for tracking",
            "example": "session456"
          }
        }
      },
      "TTSResponse": {
        "type": "object",
        "required": ["success", "audio_base64", "audio_format", "duration", "engine_used", "language", "quality", "processing_time"],
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Whether TTS generation was successful",
            "example": true
          },
          "audio_base64": {
            "type": "string",
            "description": "Base64 encoded audio data",
            "example": "UklGRnoGAABXQVZFZm10IBAAAAABAAEA..."
          },
          "audio_format": {
            "type": "string",
            "description": "Audio format (mp3, wav, etc.)",
            "example": "mp3"
          },
          "duration": {
            "type": "number",
            "description": "Audio duration in seconds",
            "example": 1.6
          },
          "engine_used": {
            "type": "string",
            "description": "TTS engine that was used",
            "example": "edge-tts"
          },
          "language": {
            "type": "string",
            "description": "Language of the generated speech",
            "example": "rw"
          },
          "quality": {
            "type": "string",
            "description": "Quality level used",
            "example": "high"
          },
          "processing_time": {
            "type": "number",
            "description": "Processing time in seconds",
            "example": 0.8
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata about the generation",
            "example": {
              "voice_name": "Rwanda Female",
              "sample_rate": 22050,
              "bit_rate": 128
            }
          }
        }
      },
      "STTRequest": {
        "type": "object",
        "required": ["audio_file"],
        "properties": {
          "audio_file": {
            "type": "string",
            "format": "binary",
            "description": "Audio file to transcribe (WAV, MP3, M4A supported)"
          },
          "language": {
            "type": "string",
            "description": "Expected language of the audio",
            "default": "en",
            "example": "rw"
          },
          "engine": {
            "type": "string",
            "enum": ["whisper", "vosk", "speech_recognition"],
            "description": "STT engine to use (auto-select if not specified)",
            "example": "whisper"
          },
          "quality": {
            "type": "string",
            "enum": ["low", "medium", "high", "premium"],
            "description": "Recognition quality level",
            "default": "medium",
            "example": "high"
          },
          "user_id": {
            "type": "string",
            "description": "User ID for tracking",
            "example": "user123"
          },
          "session_id": {
            "type": "string",
            "description": "Session ID for tracking",
            "example": "session456"
          }
        }
      },
      "STTResponse": {
        "type": "object",
        "required": ["text", "confidence", "language", "engine_used", "processing_time"],
        "properties": {
          "text": {
            "type": "string",
            "description": "Recognized text",
            "example": "Muraho, amakuru? Nimeza, murakoze."
          },
          "confidence": {
            "type": "number",
            "minimum": 0.0,
            "maximum": 1.0,
            "description": "Recognition confidence score",
            "example": 0.95
          },
          "language": {
            "type": "string",
            "description": "Detected language",
            "example": "rw"
          },
          "engine_used": {
            "type": "string",
            "description": "STT engine that was used",
            "example": "whisper"
          },
          "processing_time": {
            "type": "number",
            "description": "Processing time in seconds",
            "example": 2.3
          },
          "alternatives": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Alternative recognition results",
            "example": ["Muraho, amakuru?", "Muraho, amakuru"]
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata about the recognition",
            "example": {
              "audio_duration": 3.2,
              "sample_rate": 16000,
              "model_version": "whisper-1"
            }
          }
        }
      },
      "BatchTTSRequest": {
        "type": "object",
        "required": ["texts", "language"],
        "properties": {
          "texts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "maxItems": 10,
            "description": "List of texts to convert to speech",
            "example": ["Muraho", "Amakuru?", "Murakoze", "Mwirirwe"]
          },
          "language": {
            "type": "string",
            "description": "Language code for all texts",
            "example": "rw"
          },
          "engine": {
            "type": "string",
            "enum": ["gtts", "pyttsx3", "edge-tts", "coqui"],
            "description": "TTS engine to use for all texts",
            "example": "edge-tts"
          },
          "quality": {
            "type": "string",
            "enum": ["low", "medium", "high", "premium"],
            "description": "Voice quality level for all texts",
            "default": "medium",
            "example": "high"
          }
        }
      },
      "BatchTTSResponse": {
        "type": "object",
        "required": ["total_texts", "successful", "failed", "results"],
        "properties": {
          "total_texts": {
            "type": "integer",
            "description": "Total number of texts processed",
            "example": 4
          },
          "successful": {
            "type": "integer",
            "description": "Number of successful TTS generations",
            "example": 4
          },
          "failed": {
            "type": "integer",
            "description": "Number of failed TTS generations",
            "example": 0
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer",
                  "description": "Index of the text in the original request"
                },
                "text": {
                  "type": "string",
                  "description": "Original text"
                },
                "success": {
                  "type": "boolean",
                  "description": "Whether TTS generation was successful"
                },
                "audio_base64": {
                  "type": "string",
                  "description": "Base64 encoded audio (if successful)"
                },
                "error": {
                  "type": "string",
                  "description": "Error message (if failed)"
                }
              }
            },
            "description": "Results for each text"
          }
        }
      },
      "EngineStatusResponse": {
        "type": "object",
        "required": ["status", "tts_engines", "stt_engines", "supported_languages"],
        "properties": {
          "status": {
            "type": "string",
            "description": "Overall status",
            "example": "success"
          },
          "tts_engines": {
            "type": "object",
            "properties": {
              "engines": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "edge-tts"
                    },
                    "engine": {
                      "type": "string",
                      "example": "edge-tts"
                    },
                    "languages": {
                      "type": "integer",
                      "description": "Number of supported languages",
                      "example": 48
                    },
                    "priority": {
                      "type": "integer",
                      "description": "Engine priority (lower = higher priority)",
                      "example": 2
                    },
                    "online": {
                      "type": "boolean",
                      "description": "Whether engine requires internet connection",
                      "example": true
                    },
                    "quality_levels": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": ["medium", "high", "premium"]
                    }
                  }
                }
              }
            }
          },
          "stt_engines": {
            "type": "object",
            "properties": {
              "engines": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "whisper"
                    },
                    "engine": {
                      "type": "string",
                      "example": "whisper"
                    },
                    "languages": {
                      "type": "integer",
                      "description": "Number of supported languages",
                      "example": 49
                    },
                    "priority": {
                      "type": "integer",
                      "description": "Engine priority (lower = higher priority)",
                      "example": 0
                    },
                    "online": {
                      "type": "boolean",
                      "description": "Whether engine requires internet connection",
                      "example": false
                    },
                    "quality_levels": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": ["medium", "high", "premium"]
                    }
                  }
                }
              }
            }
          },
          "supported_languages": {
            "type": "object",
            "properties": {
              "tts": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Languages supported by TTS engines",
                "example": ["en", "rw", "es", "fr", "de"]
              },
              "stt": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Languages supported by STT engines",
                "example": ["en", "rw", "es", "fr", "de"]
              }
            }
          }
        }
      },
      "LanguageEnginesResponse": {
        "type": "object",
        "required": ["language_code", "tts_engines", "stt_engines"],
        "properties": {
          "language_code": {
            "type": "string",
            "description": "Language code",
            "example": "rw"
          },
          "tts_engines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "example": "edge-tts"
                },
                "engine": {
                  "type": "string",
                  "example": "edge-tts"
                },
                "priority": {
                  "type": "integer",
                  "example": 2
                },
                "online": {
                  "type": "boolean",
                  "example": true
                },
                "quality_levels": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": ["medium", "high", "premium"]
                }
              }
            },
            "description": "Available TTS engines for this language"
          },
          "stt_engines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "example": "whisper"
                },
                "engine": {
                  "type": "string",
                  "example": "whisper"
                },
                "priority": {
                  "type": "integer",
                  "example": 0
                },
                "online": {
                  "type": "boolean",
                  "example": false
                },
                "quality_levels": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": ["medium", "high", "premium"]
                }
              }
            },
            "description": "Available STT engines for this language"
          }
        }
      },
      "LanguagesResponse": {
        "type": "object",
        "required": ["languages", "total_count", "last_updated", "version"],
        "properties": {
          "languages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LanguageInfo"
            },
            "description": "List of supported languages"
          },
          "total_count": {
            "type": "integer",
            "description": "Total number of supported languages",
            "example": 20
          },
          "last_updated": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp"
          },
          "version": {
            "type": "string",
            "description": "API version",
            "example": "3.0.0"
          }
        }
      },
      "LanguageInfo": {
        "type": "object",
        "required": ["code", "name", "native_name", "flag_emoji", "features", "models", "tts_engines", "stt_engines", "difficulty_level", "cultural_notes", "sample_phrases"],
        "properties": {
          "code": {
            "type": "string",
            "description": "ISO 639-1/639-3 language code",
            "example": "rw"
          },
          "name": {
            "type": "string",
            "description": "English name of the language",
            "example": "Kinyarwanda"
          },
          "native_name": {
            "type": "string",
            "description": "Native name of the language",
            "example": "Ikinyarwanda"
          },
          "flag_emoji": {
            "type": "string",
            "description": "Flag emoji for the language",
            "example": "🇷🇼"
          },
          "features": {
            "$ref": "#/components/schemas/LanguageFeature"
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Available ML models for this language",
            "example": ["nllb-200", "m2m100"]
          },
          "tts_engines": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Available TTS engines for this language",
            "example": ["edge-tts", "gtts"]
          },
          "stt_engines": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Available STT engines for this language",
            "example": ["whisper", "vosk"]
          },
          "difficulty_level": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "description": "Learning difficulty level (1=easy, 5=hard)",
            "example": 3
          },
          "cultural_notes": {
            "type": "string",
            "description": "Cultural context notes for learning",
            "example": "Kinyarwanda is the official language of Rwanda and is spoken by over 12 million people."
          },
          "sample_phrases": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Sample phrases for learning",
            "example": ["Muraho", "Amakuru?", "Murakoze", "Mwirirwe"]
          }
        }
      },
      "LanguageFeature": {
        "type": "object",
        "required": ["translation", "tts", "stt", "learning", "audio_translation", "real_time"],
        "properties": {
          "translation": {
            "type": "boolean",
            "description": "Text translation support",
            "example": true
          },
          "tts": {
            "type": "boolean",
            "description": "Text-to-speech support",
            "example": true
          },
          "stt": {
            "type": "boolean",
            "description": "Speech-to-text support",
            "example": true
          },
          "learning": {
            "type": "boolean",
            "description": "Language learning features",
            "example": true
          },
          "audio_translation": {
            "type": "boolean",
            "description": "Audio translation support",
            "example": true
          },
          "real_time": {
            "type": "boolean",
            "description": "Real-time translation support",
            "example": true
          }
        }
      },
      "TranslationRequest": {
        "type": "object",
        "required": ["content", "target_language"],
        "properties": {
          "content": {
            "type": "string",
            "minLength": 1,
            "maxLength": 10000,
            "description": "Content to translate",
            "example": "Hello, how are you?"
          },
          "source_language": {
            "type": "string",
            "description": "Source language code (auto-detect if not provided)",
            "example": "en"
          },
          "target_language": {
            "type": "string",
            "minLength": 2,
            "maxLength": 10,
            "description": "Target language code",
            "example": "rw"
          },
          "content_type": {
            "type": "string",
            "enum": ["text", "post", "message", "comment", "bio"],
            "description": "Type of content for context-aware translation",
            "default": "text",
            "example": "message"
          },
          "user_id": {
            "type": "string",
            "description": "User ID for personalization",
            "example": "user123"
          },
          "platform_context": {
            "type": "object",
            "description": "Additional platform context",
            "example": {
              "platform": "vibeon",
              "feature": "chat"
            }
          },
          "priority": {
            "type": "string",
            "enum": ["low", "normal", "high", "urgent"],
            "description": "Translation priority",
            "default": "normal",
            "example": "normal"
          }
        }
      },
      "TranslationResponse": {
        "type": "object",
        "required": ["original_text", "translated_text", "source_language", "target_language", "confidence_score", "processing_time", "quality_metrics"],
        "properties": {
          "original_text": {
            "type": "string",
            "description": "Original input text",
            "example": "Hello, how are you?"
          },
          "translated_text": {
            "type": "string",
            "description": "Translated text",
            "example": "Muraho, amakuru?"
          },
          "source_language": {
            "type": "string",
            "description": "Detected or specified source language",
            "example": "en"
          },
          "target_language": {
            "type": "string",
            "description": "Target language",
            "example": "rw"
          },
          "confidence_score": {
            "type": "number",
            "minimum": 0.0,
            "maximum": 1.0,
            "description": "Translation confidence score",
            "example": 0.95
          },
          "processing_time": {
            "type": "number",
            "description": "Processing time in seconds",
            "example": 0.8
          },
          "quality_metrics": {
            "type": "object",
            "description": "Quality assessment metrics",
            "example": {
              "fluency": 0.9,
              "adequacy": 0.95,
              "overall": 0.92
            }
          },
          "suggestions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Alternative translations or suggestions",
            "example": ["Muraho, uko amakuru?", "Muraho, amakuru yanyu?"]
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata",
            "example": {
              "model_used": "nllb-200",
              "timestamp": "2025-10-04T13:47:00Z"
            }
          }
        }
      },
      "AudioTranslationRequest": {
        "type": "object",
        "required": ["audio_url", "target_language"],
        "properties": {
          "audio_url": {
            "type": "string",
            "description": "URL of the audio file to translate",
            "example": "https://example.com/audio.mp3"
          },
          "source_language": {
            "type": "string",
            "description": "Source language (auto-detect if not provided)",
            "example": "en"
          },
          "target_language": {
            "type": "string",
            "description": "Target language for translation",
            "example": "rw"
          },
          "output_format": {
            "type": "string",
            "enum": ["text", "audio", "both"],
            "description": "Output format",
            "default": "text",
            "example": "both"
          },
          "user_id": {
            "type": "string",
            "description": "User ID for tracking",
            "example": "user123"
          },
          "enhance_audio": {
            "type": "boolean",
            "description": "Whether to enhance audio quality before processing",
            "default": true,
            "example": true
          }
        }
      },
      "AudioTranslationResponse": {
        "type": "object",
        "required": ["original_audio_url", "extracted_text", "translated_text", "source_language", "target_language", "confidence_score", "processing_time"],
        "properties": {
          "original_audio_url": {
            "type": "string",
            "description": "Original audio URL",
            "example": "https://example.com/audio.mp3"
          },
          "extracted_text": {
            "type": "string",
            "description": "Text extracted from audio",
            "example": "Hello, how are you?"
          },
          "translated_text": {
            "type": "string",
            "description": "Translated text",
            "example": "Muraho, amakuru?"
          },
          "source_language": {
            "type": "string",
            "description": "Detected source language",
            "example": "en"
          },
          "target_language": {
            "type": "string",
            "description": "Target language",
            "example": "rw"
          },
          "confidence_score": {
            "type": "number",
            "description": "Overall confidence score",
            "example": 0.92
          },
          "processing_time": {
            "type": "number",
            "description": "Total processing time in seconds",
            "example": 3.5
          },
          "translated_audio_base64": {
            "type": "string",
            "description": "Base64 encoded translated audio (if requested)",
            "example": "UklGRnoGAABXQVZFZm10IBAAAAABAAEA..."
          },
          "audio_encoding": {
            "type": "string",
            "description": "Audio encoding format",
            "example": "base64"
          },
          "audio_mime_type": {
            "type": "string",
            "description": "Audio MIME type",
            "example": "audio/mpeg"
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata",
            "example": {
              "stt_engine": "whisper",
              "tts_engine": "edge-tts",
              "audio_duration": 3.2
            }
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": ["status", "service", "version", "timestamp"],
        "properties": {
          "status": {
            "type": "string",
            "enum": ["healthy", "degraded", "unhealthy"],
            "description": "Overall system health status",
            "example": "healthy"
          },
          "service": {
            "type": "string",
            "description": "Service name",
            "example": "Vibeon Translator API"
          },
          "version": {
            "type": "string",
            "description": "Service version",
            "example": "3.0.0"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Health check timestamp"
          },
          "database": {
            "type": "string",
            "description": "Database connection status",
            "example": "connected"
          },
          "translator": {
            "type": "string",
            "description": "Translation service status",
            "example": "initialized"
          },
          "cache": {
            "type": "string",
            "description": "Cache service status",
            "example": "ready"
          }
        }
      },
      "VoiceHealthResponse": {
        "type": "object",
        "required": ["status", "tts_available", "stt_available", "engines_loaded"],
        "properties": {
          "status": {
            "type": "string",
            "enum": ["healthy", "degraded", "unhealthy"],
            "description": "Voice services health status",
            "example": "healthy"
          },
          "tts_available": {
            "type": "boolean",
            "description": "Whether TTS services are available",
            "example": true
          },
          "stt_available": {
            "type": "boolean",
            "description": "Whether STT services are available",
            "example": true
          },
          "engines_loaded": {
            "type": "object",
            "properties": {
              "tts_engines": {
                "type": "integer",
                "description": "Number of TTS engines loaded",
                "example": 4
              },
              "stt_engines": {
                "type": "integer",
                "description": "Number of STT engines loaded",
                "example": 2
              }
            }
          },
          "supported_languages": {
            "type": "object",
            "properties": {
              "tts": {
                "type": "integer",
                "description": "Number of languages supported by TTS",
                "example": 100
              },
              "stt": {
                "type": "integer",
                "description": "Number of languages supported by STT",
                "example": 100
              }
            }
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Health check timestamp"
          }
        }
      }
    }
  }
}