API Reference#

The backend is a FastAPI application that serves REST APIs.

Interactive API docs#

When the stack is running, FastAPI provides OpenAPI specifications and Swagger UI at http://<HOST_IP>:4172/docs

If you run the backend on a different host and port, edit accordingly.

Route Summary#

The backend defines the following application routes:

Method

Path

Description

GET

/api/health

Returns application health status.

GET

/api/model

Returns the configured LLM model identifier.

POST

/api/chat

Streams chat responses from the RAG pipeline.

POST

/api/embeddings

Creates and stores an embedding in the vector store.

API Endpoints#

GET /api/health#

Returns a simple health payload to confirm that the application is running.

Response

{
  "status": "healthy",
  "message": "Live Video Captioning RAG application is up and running."
}

GET /api/model#

Returns the configured LLM model ID used by the backend.

Response

{
  "status": "Success",
  "llm_model": "<configured-model-id>"
}

POST /api/chat#

Submits a user question to the RAG pipeline and returns a streamed response using Server-Sent Events.

Request body

{
  "input": "What you see in the image?"
}

Success response

  • Content type: text/event-stream

  • Body: streamed output generated by the RAG chain

Validation error

Returned when input is missing or an empty string.

{
  "detail": "Input question is required and cannot be empty."
}

POST /api/embeddings#

Processes caption or image-derived content and stores the resulting embedding in the VDMS vector store.

Request body

{
  "image_data": "<base64-or-caption-payload>",
  "metadata": {
    "result": "The image shows ....<caption_text>",
    "timestamp": 2754121008,
    "timestamp_seconds": 2.75,
    "resolution": {
      "height": 1080,
      "width": 1920
    },
    "frame_id": 101,
    "img_format": "BGR"
  }
}

Success response

{
  "status": "success",
  "message": "Embedding processed and stored successfully.",
  "id": "<embedding-id>"
}

Validation errors

Returned when:

  • image_data is missing, empty, or has whitespace only

  • metadata is not a JSON object

  • the embedding service rejects the payload with a ValueError

Example validation response:

{
  "detail": "Input image data is required and cannot be empty."
}

Server error

If embedding processing fails unexpectedly, the backend returns:

{
  "detail": "Failed to process embedding."
}

Learn More#