API Introduction

Welcome to the API documentation for the Omni AI Translator & Chatbot system. This API allows you to manage users, conduct AI chat sessions with RAG (Retrieval Augmented Generation), and perform high-performance document translation.

Base URL: http://your-server-ip:8000

Authentication

The API uses two types of authentication:

Type Header Key Description
Bearer Token Authorization: Bearer <token> Used for client-facing endpoints (Login, Chat, Profile). Obtained via /api/login.
Internal API Key X-Internal-API-Key Used strictly for the GPU Translation Server communication.

Status Codes

Code Status Description
200 OK Request was successful.
201 Created Resource was successfully created.
400 Bad Request Invalid parameters or missing fields.
401 Unauthorized Missing or invalid authentication token.
403 Forbidden You do not have permission to access this resource (e.g., Banned user).
503 Service Unavailable Database or GPU Model is not loaded/connected.

User Authentication

POST /api/register

Register a new user account.

{
    "fullName": "John Doe",
    "email": "john@example.com",
    "password": "securepassword123",
    "phoneNo": "1234567890",
    "country": "USA"
    "status": "active"  
}

POST /api/login

Authenticate a user and receive a JWT Bearer token.

{
    "email": "john@example.com",
    "password": "securepassword123"
}
Response: 
{
    "message": "Login successful!",
    "token": "eyJhbGciOiJIUzI1NiIsIn...",
    "role": "user"
}

GET /api/user/profile

Retrieve details of the currently logged-in user.

Headers: Authorization: Bearer <token>

PATCH /api/user/profile

Update user details. All fields are optional.

{
    "fullName": "John Updated",
    "phoneNo": "9876543210"
}

Chat & AI Module

POST /api/chats

Start a new chat session.

{
    "title": "Project Discussion"
}

POST /api/chats/{chat_id}/messages/stream

Send a message to the AI and receive a streamed response using Server-Sent Events (SSE).

Note: This endpoint returns Content-Type: text/event-stream. The client must listen for data chunks.

Parameters:

{
    "content": "Analyze the attached PDF file and summarize it."
}
Stream Data Format: 
data: {"type": "text", "data": "Sure, I can help..."}

data: {"type": "text", "data": " with that summary."}

POST /api/chats/{chat_id}/upload

Upload a document (PDF, TXT, DOCX) to the chat context (RAG).

Content-Type: multipart/form-data

Key Type Description
file File The document file to be analyzed.

Translation Orchestrator (WebSocket)

The translation process is handled via WebSocket for real-time progress updates.

WS /ws/translate?token={jwt_token}

Connection: Connect to this endpoint with the user's JWT token in the query parameter.

1. Request: Start File Translation

{
    "type": "start_file_translation",
    "target_languages": ["Spanish", "French"],
    "output_format": "pdf",
    "gcs_path": "translation_staging/user_id/file.docx",
    "content_type": "application/vnd.openxmlformats..."
}

2. Request: Real-time Text Translation

{
    "type": "realtime_text",
    "content": "Hello world",
    "target_languages": ["Hindi"],
    "source_language": "auto"
}

Response Events

The server sends JSON objects with a type field:

POST /api/translate/upload

Stage a file for translation before sending the WebSocket command.

Returns: A gcs_path to be used in the WebSocket request.

Internal GPU Translation Server

This section documents the separate GPU-based microservice acting as a Multi-Model Switchboard. It dynamically routes translation requests across MADLAD-400 (10B), IndicTrans2 (1B), and NLLB-200 (3.3B) models based on the target language. This service is internal and requires an API Key.

Technology Stack: Python, FastAPI, PyTorch, HuggingFace Transformers.

Hardware Requirement: NVIDIA GPU (CUDA).

POST /translate

Perform a direct synchronous translation. The server automatically cleans and maps the provided language codes to route the request to the most optimal model (IndicTrans2 for Indian languages, NLLB for supported African/global dialects, and MADLAD for general fallbacks/forced requests).

Authentication:

Header: X-Internal-API-Key: {your_env_api_key}

Request Body (JSON):

Parameter Type Required Description
text string Yes The raw text to translate. Max length restricted to 1024 tokens.
target_language_code string Yes The target language code. Accepts standard ISO codes (e.g., hi), FLORES-200 codes (e.g., hin_Deva), or explicit MADLAD tags (e.g., <2fr>).
source_language_code string No The source language code. Accepts standard ISO or FLORES-200 codes. (Default: en).

Example Request:

POST /translate
Headers:
  Content-Type: application/json
  X-Internal-API-Key: my_secret_key

Body:
{
    "text": "Hello, how are you?",
    "target_language_code": "hi",
    "source_language_code": "en"
}

Example Response (200 OK):

{
    "translated_text": "नमस्ते, आप कैसे हैं?"
}

Error Responses: