API Overview
API Overview
Section titled “API Overview”The AutoVio backend exposes a REST API under /api. You can use it to manage projects, works, run the video pipeline (analyze, scenario, generate, export), and manage assets and templates.
Base URL
Section titled “Base URL”When running locally: http://localhost:3001. All endpoints are prefixed with /api.
Authentication
Section titled “Authentication”Most endpoints require authentication:
- Web UI: Uses JWT (access token from login/register). The frontend sends
Authorization: Bearer <accessToken>. - API tokens: For server-to-server or MCP, create an API token in the UI (or via
POST /api/tokens) with scopes (e.g.projects:read,works:write,ai:generate). Send it asAuthorization: Bearer <token>.
See Authentication for login, register, refresh, and token scopes.
Provider headers (AI endpoints)
Section titled “Provider headers (AI endpoints)”For analyze, scenario, and generate endpoints, the client tells the backend which AI provider and key to use via headers:
| Header | Used by | Example |
|---|---|---|
x-vision-provider | Analyze | gemini, claude, openai |
x-llm-provider | Scenario | gemini, claude, openai |
x-image-provider | Generate image | gemini, dalle |
x-video-provider | Generate video | gemini, runway |
x-model-id | Optional model | e.g. gemini-2.0-flash-exp |
x-api-key | Provider API key | (key for the chosen provider) |
The backend forwards the key to the external provider; it does not store provider keys in env.
Main endpoint groups
Section titled “Main endpoint groups”| Group | Description |
|---|---|
| Authentication | Register, login, refresh, me |
| Projects | CRUD projects |
| Works | CRUD works, media (reference, scene image/video) |
| AI Endpoints | Analyze, scenario, generate image/video, export |
| Templates | List, create, get, update, delete, apply templates |
| Assets | List, upload, get, update, delete project assets |
| Providers | List available AI providers (no auth) |
OpenAPI
Section titled “OpenAPI”When the backend is running, OpenAPI documentation is available at /api/docs (Swagger UI or equivalent). Use it for exact request/response schemas and examples.