API Routes
Handlers live in src/app/api/<...>/route.ts. Most JSON responses go through
src/lib/* helpers; planner reads/writes use Prisma and
@/lib/planner-session rather than ad-hoc fs for session state.
Below is a grouped index. For a full list, search the tree:
find src/app/api -name route.ts (from the veyra app root).
Audio & projects
| Route | Methods | Purpose |
|---|---|---|
/api/audio-files | GET | List projects (folders under public/projects/ with a mix file). |
/api/analyze-audio | POST | Song structure: segments (sections), beat/downbeat hints, no_beat_regions when present. Consumed by the Audio Analysis pane for grouping lyrics. |
/api/beat-grid | POST | Proxy to beat service beat grid. |
/api/audio-staging | GET, POST | Read/write per-project audio staging document. |
/api/tap-grids | GET, POST | Tap grid calibration. |
/api/tap-grids/quantize | POST | Quantize tap input. |
Lyrics
| Route | Methods | Purpose |
|---|---|---|
/api/lyrics | GET, POST | Lyrics fetch / job kickoff. |
/api/lyrics-staging | GET, POST | Staged / edited lyrics. |
/api/lyrics-status | GET | Poll long jobs. |
/api/lyrics-stem | POST | Re-stem or bypass cache. |
/api/lyrics-vs-reference | POST | Align pasted reference lyrics with persisted transcript segments for the planner compare UI (DP pairing; body: reference text + segments). |
Planner (Video Plan)
All under /api/planner/… — session, inputs, and one route per
major step. Examples:
| Route | Methods | Purpose |
|---|---|---|
/api/planner/session | GET, POST, … | Load or persist the planner session. |
/api/planner/inputs | … | Step: inputs / upload. |
/api/planner/song-read | … | Song read / early narrative. |
/api/planner/concept | … | Concept step. |
/api/planner/acts | … | Acts. |
/api/planner/locations | … | Locations. |
/api/planner/audio-analysis | … | Hook analysis into the session. |
/api/planner/environment-prompt | … | Environment prompt. |
/api/planner/environment-chat | … | Environment chat. |
/api/planner/filming-style | … | Global filming style. |
/api/planner/prompts | … | Per-shot prompts. |
/api/planner/scaffold | … | Shot scaffold. |
/api/planner/generate-notes | … | Project-wide generate notes. |
/api/planner/generate-chat | … | Render-help chat on the Generate step. |
(Exact method lists live next to each route.ts.)
Generation & assets
| Route | Methods | Purpose |
|---|---|---|
/api/generate-image | POST | Stills (Gemini / catalog in src/config/gemini-image-models.ts). |
/api/generate-video | POST | Video (Veo / fal, etc. — src/config/video-models.ts). |
/api/shot-assets | GET | List generated assets for a shot. |
/api/shot-assets/stream | GET | Stream asset bytes where applicable. |
/api/lip-sync-video | POST | Lip-sync post-process. |
/api/render-timeline | POST | Composites shots + mix to exports/*.mp4. Body: mixSrc, includeStills?, burnSubtitles?, exportSubtitlesZip?. When burning lyrics, prefers ASS (writeAssKaraokeFromLyrics, same per-word windowing as the client) via subtitles=filename=…; fallbacks: precomposed RGBA line overlay, SRT+force_style, or mov_text soft-mux. With exportSubtitlesZip, a sidecar .en.srt is written when a transcript exists and the streamed done URL points at a *.zip (MP4 + .en.srt inside). See src/app/api/render-timeline/route.ts file header. |
/api/project-image-index | … | Project image library index. |
/api/project-still-lock | POST | Promote a still to generated/<shot>.jpg. Gallery strip sends imageBase64 (thumbnail pixels). See Gallery hero strip. |
/api/refs/resolve | … | Resolve ref URLs. |
Dashboard
| Route | Methods | Purpose |
|---|---|---|
/api/dashboard | GET | Dashboard payload; ?refresh=1 bypasses in-memory cache. |
/api/dashboard/invalidate | POST | Clear dashboard cache. |
Conventions
- Handlers return JSON; Gemini errors are normalised in
src/lib/gemini-api-error.tswhere used. - Long work (lyrics, transcoding) uses async jobs and poll endpoints.
dynamic = "force-dynamic"/revalidate = 0are common on routes that must reflect DB and disk on every request.