Skip to main content

​
Base URL

The API server runs on: 
http://localhost:8000
All API endpoints are prefixed with /api/ except for the health check endpoint.

​
CORS Configuration

The API is configured to accept requests from the following origins:
  • http://localhost:5173
  • http://127.0.0.1:5173
CORS settings:
  • Credentials: Allowed
  • Methods: All methods (*)
  • Headers: All headers (*)

​
Authentication

Currently, the API does not require authentication. All endpoints are publicly accessible.

​
Common Response Patterns

​
Success Response

Successful requests return a JSON response with a status field: 
{
  "status": "success",
  "message": "Operation completed successfully",
  // Additional data fields...
}

​
Error Response

Failed requests return an HTTP error status code with a detail message: 
{
  "detail": "Error message describing what went wrong"
}

​
Common Status Codes

Status CodeDescription
200OK - Request succeeded
206Partial Content - Range request succeeded (video streaming)
404Not Found - Resource doesn’t exist
416Range Not Satisfiable - Invalid range header
500Internal Server Error - Server-side error occurred

​
Error Handling

The API uses FastAPI’s HTTPException for error handling. Errors include:
  • 404 Not Found: When a generation ID, video file, or resource doesn’t exist
  • 416 Range Not Satisfiable: When an invalid Range header is provided for video streaming
  • 500 Internal Server Error: When video generation or processing fails
Error responses include a detail field with a descriptive error message: 
{
  "detail": "Generation ID not found"
}

​
Rate Limiting

The API does not currently implement rate limiting. Consider implementing rate limiting in production environments to prevent abuse.

​
Real-Time Progress Updates

The API provides Server-Sent Events (SSE) for real-time progress tracking during video generation. See the Progress endpoint for details.

​
Video Streaming

The API implements RFC 7233 Range Requests for efficient video streaming. This allows:
  • Seeking within videos
  • Resumable downloads
  • Bandwidth-efficient partial content delivery
See the Video endpoint for implementation details.

​
Available Endpoints

​
Generation Endpoints

  • POST /api/generate - Start a new video generation
  • GET /api/progress/{generation_id} - Stream real-time progress via SSE
  • GET /api/status/{generation_id} - Get current generation status
  • GET /api/video/{filename} - Stream generated video file

​
Data Retrieval Endpoints

  • GET /api/content/{generation_id} - Get generated presentation content structure
  • GET /api/script/{generation_id} - Get generated narration scripts

​
System Endpoints

  • GET /health - Health check endpoint

​
Health Check

A health check endpoint is available at /health: 
curl http://localhost:8000/health
Response: 
{
  "status": "healthy"
}

​
Generation Status

Check the status of a video generation without using SSE: 
curl http://localhost:8000/api/status/your-topic-name
Response: 
{
  "status": "generating_audio",
  "progress": 45,
  "message": "🎤 Generating audio for slide 2/5...",
  "timestamp": "14:23:45"
}

​
Content and Script Retrieval

After generation completes, retrieve the structured content and scripts: 
curl http://localhost:8000/api/content/your-topic-name
These endpoints return the JSON data structures used during generation, useful for debugging or building custom frontends.

Build docs developers (and LLMs) love

Get started for freeTalk to us