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

{
    "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:

chat_id (Path Parameter): The ID of the chat.

{
    "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:

{"type": "status", "message": "..."} - General status updates.
{"type": "progress", "value": 0.5, "message": "..."} - Progress bar (0.0 to 1.0).
{"type": "download_ready", "url": "..."} - Final file download URL.
{"type": "text_chunk", "text": "...", "target_lang": "..."} - For real-time text mode.

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 running the NLLB-200-3.3B model. 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 using the loaded GPU model.

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 ~512 tokens recommended.
`target_language_code`	string	Yes	FLORES-200 Language Code (e.g., `hin_Deva` for Hindi, `fra_Latn` for French).
`source_language_code`	string	No	FLORES-200 Language Code (Default: `eng_Latn`).

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": "hin_Deva",
    "source_language_code": "eng_Latn"
}

Example Response (200 OK):

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

Error Responses:

401 Unauthorized: Invalid or missing API Key.
503 Service Unavailable: The Model is not loaded onto the GPU yet.
500 Internal Server Error: CUDA error or Translation failure.

Omni Translator