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 50 MiB each; anything bigger comes back as a 413, and no file in the batch is stored). 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). 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.

Both POST endpoints return 202 Accepted, not a finished file. Image generation returns jobs, with one requestId, status, and statusUrl per image. Video generation returns one requestId and statusUrl. Save these URLs and poll them with the same bearer token every three seconds. GET requires the read scope. Do not repeat POST to check progress: a new POST starts and charges a new job.

Image status is queued, running, done, failed, or cancelled. A done response includes images with the URL and dimensions. Video status is IN_QUEUE, IN_PROGRESS, COMPLETED, or FAILED; COMPLETED includes video. Stop polling on a terminal state. The worker continues after you disconnect, and the saved status URL retrieves the result later. Reference images are not supported by the v1 image endpoint.

Multi-image requests reserve credits for all images together. Each image runs as a separate job; an individual failed job refunds its own reserved share.

Both can return 402, for two different reasons. Without an active plan that includes generation, the request is refused before any work starts. With a plan but too few credits, the response carries the cost and your remaining balance.

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

POST /api/render starts a render job (needs write) and GET /api/render lists your jobs. Poll one by id at a bounded interval for its status and output URL, or DELETE it to cancel. The former /events stream returns 410 Gone; use the single-job status endpoint instead.