Endpoints

All paths are under https://klipeo.com/api/v1 unless noted, and authenticate with a bearer token.

Health

GET /api/v1/health

No auth. Returns { ok: true } and a quick database round-trip time. Use it for uptime checks.

Account

GET /api/v1/me

Returns the user the key belongs to, plus details about the key itself.

Projects

GET /api/v1/projects?limit=25
GET /api/v1/projects/:projectId

List your projects (newest first, limit up to 100), or fetch one by id. Both are scoped to the key's owner.

Uploads

POST /api/v1/uploads

Needs the write scope. Send multipart/form-data with one or more files (up to 512 MB each — anything bigger comes back as a 413). Returns the stored uploads with their ids, urls, and types. This is the same path the phone capture flow uses.

Analysis helpers

POST /api/v1/chapters/detect
POST /api/v1/clips/summarize
POST /api/v1/broll/suggest

Give chapters/detect a transcript and a duration, and it returns chapter boundaries with titles. Give clips/summarize a transcript, and it returns a one-line summary and keywords. Give broll/suggest your subtitles array (plus optional minGapSec and windowSec) and it returns where B-roll would help. All three run off the text you send, with no separate vendor call.

Generation

POST /api/v1/generate/image
POST /api/v1/generate/video

Both need the write scope. generate/image takes a prompt, an optional imageSize, and numImages (1–4), and returns the generated images. Which model runs is your Image model preference from Settings → Skills: Nano Banana Pro by default, or Nano Banana.

generate/video animates a still into a clip. Send a prompt and an imageUrl, plus optional resolution (720p or 1080p), duration (4s, 6s, or 8s), aspectRatio, and generateAudio. It runs on Veo 3.1 Fast.

Vibe

POST /api/vibe/session
POST /api/vibe/orchestrator

Create a Vibe session, then drive it. The orchestrator streams its work back as server-sent events: text as it's written, tools as they run, and patches as the composition changes. This is the same engine behind the Vibe panel in the editor.

Compositions and renders

These sit outside the v1 path but take the same Bearer klipeo_sk_… key, so you can drive a whole edit-and-render loop from your own code.

GET  /api/compositions
POST /api/compositions
GET  /api/compositions/:id
PUT  /api/compositions/:id
DELETE /api/compositions/:id

POST   /api/render
GET    /api/render
GET    /api/render/:jobId
DELETE /api/render/:jobId
GET    /api/render/:jobId/events

POST /api/render starts a render job (needs write) and GET /api/render lists your jobs. Fetch one by id for its status and output url, DELETE it to cancel, or subscribe to /events for a server-sent stream of progress instead of polling.