Control API

FastAPI service that fronts StirVid generation and account state.

The Control API is a FastAPI service that lives at services/api. It is the single HTTP surface the web app and MCP server call.

Endpoints

Method	Path	Purpose
GET	/health	Liveness + upstream reachability.
GET	/v1/characters	List characters. Filters for public / platform-ready.
POST	/v1/projects	Create a project (workspace for a set of jobs).
POST	/v1/projects/{id}/quote	Price a job. Returns cost in credits.
POST	/v1/projects/{id}/jobs	Submit a job. Deducts credits and enqueues generation.
GET	/v1/projects/{id}/jobs	List jobs for a project, with status.
GET	/v1/account	Current user, plan, credit balance.
POST	/v1/characters/{id}/validate	Run character eligibility check (platform-ready gate).

Auth

Production uses signed session tokens. Development supports a bypass header for local runs.

x-stirvid-user is dev-only. It bypasses auth using a user id and must never be enabled in production. Guard it behind NODE_ENV !== "production".

Quote / job flow