What Is the LLM Router in the FastAPI Backend of Pixelle-Video?

The llm router in Pixelle-Video's FastAPI backend exposes the Large Language Model service as a RESTful /llm/chat endpoint, allowing external clients to generate AI text without accessing internal service plumbing.

The llm router serves as the critical gateway between external HTTP requests and Pixelle-Video's core language model capabilities. Located in api/routers/llm.py, this router transforms the complex LLM service into a simple, standardized API that front-end applications, automation scripts, and third-party services can consume directly.

How the LLM Router Handles HTTP Requests

The llm router's primary responsibility is request routing and delegation. When a client sends a POST request to /llm/chat, the router performs three essential operations: validates the incoming payload against the LLMChatRequest schema, retrieves a fully initialized PixelleVideoCore instance through FastAPI's dependency injection system, and forwards the parameters to the underlying LLM service.

Request Validation with Pydantic Models

The router strictly enforces type safety through LLMChatRequest, defined in api/schemas/llm.py. This Pydantic model expects three key parameters: prompt (the text input), temperature (sampling randomness, 0.0–1.0), and max_tokens (response length limit).

from api.schemas.llm import LLMChatRequest

# Example request structure validated by the router

example_request = LLMChatRequest(
    prompt="Explain neural networks in simple terms",
    temperature=0.7,
    max_tokens=200
)

Dependency Injection for Core Access

The llm router never instantiates services directly. Instead, it relies on PixelleVideoDep from api/dependencies.py, which FastAPI injects at runtime. This dependency provides a ready-to-use PixelleVideoCore instance with all services initialized, including the LLM client from pixelle_video/services/llm_service.py.

from fastapi import APIRouter, Depends
from api.dependencies import PixelleVideoDep
from api.schemas.llm import LLMChatRequest, LLMChatResponse

router = APIRouter(prefix="/llm", tags=["llm"])

@router.post("/chat", response_model=LLMChatResponse)
async def llm_chat(
    request: LLMChatRequest,
    pixelle_video: PixelleVideoDep  # Injected dependency

):
    # Delegates to core LLM service

    result = await pixelle_video.llm(
        prompt=request.prompt,
        temperature=request.temperature,
        max_tokens=request.max_tokens
    )
    return LLMChatResponse(
        success=True,
        message="Success",
        content=result["content"],
        tokens_used=result.get("tokens_used")
    )

Calling the LLM Router Endpoint

External clients interact with the llm router through standard HTTP POST requests. The endpoint returns structured JSON wrapped in LLMChatResponse, providing both the generated content and metadata about the operation status.

cURL Example for Direct API Access

curl -X POST https://your-host/api/llm/chat \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "Summarize the plot of *Inception* in 2 sentences.",
        "temperature": 0.6,
        "max_tokens": 150
      }'

Expected response structure:

{
  "success": true,
  "message": "Success",
  "content": "A thief who enters dreams to steal secrets must perform an impossible inception: planting an idea instead of stealing one. He leads a team through nested dream levels where time dilates and reality becomes increasingly uncertain.",
  "tokens_used": null
}

Python Client Integration with httpx

import httpx

async def generate_text(prompt: str, temperature: float = 0.7, max_tokens: int = 200):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://your-host/api/llm/chat",
            json={
                "prompt": prompt,
                "temperature": temperature,
                "max_tokens": max_tokens
            }
        )
        response.raise_for_status()
        data = response.json()
        return data["content"]

# Usage

import asyncio
result = asyncio.run(generate_text("Explain quantum superposition simply"))
print(result)

Internal Reuse: Bypassing the HTTP Layer

The llm router's clean separation of concerns enables direct service reuse from other FastAPI routes. By importing PixelleVideoDep and calling the core's llm method directly, internal code avoids HTTP overhead while maintaining identical functionality.

from fastapi import APIRouter, Depends
from api.dependencies import PixelleVideoDep
from api.schemas.llm import LLMChatRequest

router = APIRouter()

@router.post("/relay")
async def relay_chat(request: LLMChatRequest, pv: PixelleVideoDep):
    """
    Internal route that reuses the LLM service directly
    without making an HTTP call to /llm/chat.
    """
    answer = await pv.llm(
        prompt=request.prompt,
        temperature=request.temperature,
        max_tokens=request.max_tokens,
    )
    return {
        "answer": answer["content"],
        "internal": True  # Marker showing direct service usage

    }

This pattern demonstrates how the llm router's architecture—delegating to an injectable core—supports both external API consumption and efficient internal service composition.

Key Files Supporting the LLM Router

File	Purpose
api/routers/llm.py	Declares the /llm/chat endpoint, handles request validation, and delegates to the core LLM service
api/dependencies.py	Provides PixelleVideoDep, the FastAPI dependency that injects a configured PixelleVideoCore instance
api/schemas/llm.py	Defines LLMChatRequest and LLMChatResponse Pydantic models for type-safe request/response handling
pixelle_video/services/llm_service.py	Core LLM client implementation using an OpenAI-compatible SDK, managing model selection, parameter processing, and structured output

Summary

The llm router in Pixelle-Video's FastAPI backend serves as the authoritative HTTP gateway to the platform's Large Language Model capabilities:

• Primary endpoint: /llm/chat accepts structured requests with prompt, temperature, and max_tokens parameters
• Type safety: Pydantic models (LLMChatRequest, LLMChatResponse) enforce validation at the API boundary
• Clean architecture: FastAPI dependency injection (PixelleVideoDep) decouples the router from service instantiation
• Implementation delegation: All LLM logic routes through pixelle_video/services/llm_service.py, an OpenAI-compatible client
• Dual usage pattern: Supports both external HTTP clients and internal direct service calls from other FastAPI routes

Frequently Asked Questions

What endpoint does the LLM router expose?

The llm router exposes a single POST endpoint at /llm/chat. This endpoint accepts a JSON body matching the LLMChatRequest schema and returns a structured LLMChatResponse containing the generated text and operation status.

How does the LLM router validate incoming requests?

Request validation occurs through Pydantic models defined in api/schemas/llm.py. The LLMChatRequest model enforces type constraints on prompt (string), temperature (float), and max_tokens (integer), automatically rejecting malformed requests with descriptive HTTP 422 errors before they reach business logic.

Can other parts of the application use the LLM service without calling the HTTP endpoint?

Yes. The architecture supports direct service reuse through FastAPI's dependency injection system. Other routes can import PixelleVideoDep from api/dependencies.py and call pv.llm() directly, bypassing HTTP overhead while utilizing identical LLM functionality. This pattern is demonstrated in internal relay routes that process LLM requests programmatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}