Start jobs and fetch clips over the REST API
Sign in for a token, send a link to POST /api/process, then read clips from GET /api/status/{job_id}. The dashboard uses these same routes.
Before you call the API
- A VimeoClip account with a password. A member can call /api/process and /api/uploads and read their own jobs.
- Enough credits. A new account can have 0 credits, and then POST /api/process returns 402.
- GEMINI_API_KEY or LLM_BASE_URL on the server. Without those, send your own key in the X-Gemini-Key header.
- You own the content or hold the rights to process it. The request must carry acknowledged: true.
Get a token
POST /api/auth/login returns access_token. Send it in an Authorization: Bearer header on every later request. The token expires after 30 days, and changing the password invalidates old tokens.
BASE=http://localhost:8000
curl -s -X POST "$BASE/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"YOUR_PASSWORD"}'{
"ok": true,
"access_token": "eyJhbGciOi...",
"token_type": "bearer",
"user": { "...": "..." }
}Start a job from a link
You need url and acknowledged. Everything else is optional. With the same Idempotency-Key, sending the request again returns the earlier answer instead of creating a second job.
curl -s -X POST "$BASE/api/process" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: podcast-42" \
-d '{
"url": "https://www.youtube.com/watch?v=VIDEO_ID",
"acknowledged": true,
"target_clips": 5,
"clip_min_seconds": 30,
"clip_max_seconds": 90,
"output_format": "vertical",
"captions": true,
"auto_hook": true,
"webhook_url": "https://hooks.example.com/openshorts",
"webhook_secret": "change-me"
}'{ "job_id": "2f6c0a1e-...", "status": "queued" }Start a job from a file
Send the file in one multipart request, or reserve a slot with POST /api/uploads and PUT the raw bytes. The default file limit is 2048 MB (MAX_FILE_SIZE_MB). POST /api/uploads returns upload_id, upload_url, max_mb and expires_in.
# Multipart upload in one request
curl -s -X POST "$BASE/api/process" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@video.mp4" \
-F "acknowledged=true"
# Or reserve a slot, PUT the bytes, then pass upload_id
curl -s -X POST "$BASE/api/uploads" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"filename":"video.mp4"}'
curl -T video.mp4 "$BASE/api/uploads/UPLOAD_ID" \
-H "Authorization: Bearer $TOKEN"
curl -s -X POST "$BASE/api/process" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"upload_id":"UPLOAD_ID","acknowledged":true}'Common POST /api/process fields
Send JSON, or send the same field names as form fields when you upload a file.
| Field | Values | Meaning |
|---|---|---|
| url | String | Public video link. Use url, file or upload_id. |
| upload_id | String | A slot already filled through POST /api/uploads. |
| acknowledged | true | Confirms you may process the content. Required. |
| target_clips | 1 to 30 | How many clips to aim for. You can get fewer if the video lacks good moments. |
| clip_min_seconds | 0 to 895 | Minimum clip length. |
| clip_max_seconds | 10 to 900 | Maximum clip length. |
| analysis_start_seconds, analysis_end_seconds | Seconds, sent together | Analyze only one part of the source. Credits follow this window. |
| output_format | auto, vertical, horizontal, square, portrait | Clip aspect. |
| layouts | auto, split, screencast, speaker_cut, punch_in, none | A JSON array or a comma-separated string. |
| captions | true, false | Whether captions are burned into the clip. |
| caption_preset | For example auto, tiktok, reels, minimal | Caption look. |
| source_language, caption_language | ISO 639-1 code or auto | Spoken language and caption language. |
| auto_hook, auto_hook_style | true; classic, dark, yellow, red, outline, outline_yellow | The hook line on the clip. REST only turns it on when you send auto_hook: true. |
| moment_hint | String | A topic or quote to prefer. |
| clip_workflow | best, coverage, find | find needs moment_hint. coverage needs clip_lenses set to content. |
| clip_lenses | arc, chunk, stitch, seam | A comma-separated string. Each extra lens is another AI call. |
| test_mode | true | Runs all the analysis and skips the render. AI cost matches a real job and no webhook fires. |
| force_low_quality | true | Continue after a low-resolution warning. |
| webhook_url, webhook_secret | String | Get a POST when the job ends. |
This table is not exhaustive. process_endpoint in backend/app.py takes many more caption and hook styling fields.
Read the status
status is queued, processing, completed, failed or cancelled. Polling every 30 to 60 seconds is enough. Add summary=true for a compact reply with status, generation, progress, eta_seconds, error and clip_count.
# Full response
curl -s "$BASE/api/status/$JOB_ID" -H "Authorization: Bearer $TOKEN"
# Compact response for polling
curl -s "$BASE/api/status/$JOB_ID?summary=true" -H "Authorization: Bearer $TOKEN"{
"status": "completed",
"generation": 1,
"progress": 100,
"eta_seconds": null,
"logs": ["..."],
"result": {
"clips": [
{
"start": 312.4,
"end": 368.9,
"video_url": "/videos/JOB_ID/FILE_NAME.mp4",
"predicted_score": 81,
"video_title_for_youtube_short": "...",
"video_description_for_tiktok": "...",
"video_description_for_instagram": "..."
}
]
},
"settings": { "...": "..." },
"error": null
}Read and download clips
result.clips puts the strongest clip first. video_url is a path on the same host. predicted_score is the raw score used for ranking. Paths under /videos need the job owner's token.
# Clip paths, best clip first
curl -s "$BASE/api/status/$JOB_ID" -H "Authorization: Bearer $TOKEN" \
| jq -r '.result.clips[].video_url'
# One clip. /videos needs the same token.
curl -L -H "Authorization: Bearer $TOKEN" \
-o clip-1.mp4 "$BASE/videos/$JOB_ID/FILE_NAME.mp4"
# Every primary clip as a ZIP. indices=0,2 picks specific ones.
curl -L -H "Authorization: Bearer $TOKEN" \
-o clips.zip "$BASE/api/jobs/$JOB_ID/download-all"Credits are reserved per job
When a job is accepted, reserve_job_credits holds 1 credit per minute of source length, rounded up, with a minimum of 1. If you send analysis_start_seconds and analysis_end_seconds, the length is that window. If the server cannot measure the length at submit time, it holds 1 credit.
When the job finishes, the charge is settled against the real length. A failed or cancelled job is refunded. The same rule applies to admin accounts.
An account on the free plan gets a watermark burned into its clips.
When credits run out
POST /api/process returns 402 and creates no job.
{
"detail": {
"error": "quota_exceeded",
"minutes_required": 42,
"minutes_remaining": 10,
"message": "Insufficient credits (10 available, 42 required). Please add credits or upgrade your plan."
}
}Responses to handle
Errors are JSON with a detail field.
| Code | When | What to do |
|---|---|---|
| 200, needs_confirmation | The source is below QUALITY_GATE_MIN_HEIGHT, 720p by default. No job yet. | Ask the user, then resend with force_low_quality: true. |
| 400 | No source, no acknowledged, a value out of range, an invalid webhook_url, or a link shorter than MIN_SOURCE_SECONDS (45 seconds by default). | Read detail and fix the request. |
| 401 | Missing or invalid token. | Sign in again. |
| 402 | Not enough credits. | Add credits or ask an admin to grant them. |
| 403 | An admin-only route, a member choosing a custom AI endpoint, or a browser Origin outside the allowlist. | Use an admin account, or ask the admin to add the origin to the allowlist. |
| 404 | The job does not exist or belongs to another account. | Check job_id and the account. |
| 503 | The server is handing jobs over during an update. | Retry after the time in Retry-After. |
Frequently asked questions
Yes. Create an osk_ key on the API access page and send it in an Authorization: Bearer or X-API-Key header. The key carries the account's own permissions and credits, does not expire, and can be revoked at any time. Session tokens from POST /api/auth/login still work, but live only 30 days.
A member account can only call routes reviewed for members. Restyling captions, recutting clips and publishing need an admin account.
Not in AI cost. Transcription, scoring and the review passes still run. The job only skips the render.
Call GET /api/me with the token. The response has credits_balance, plan and role.
Drop the polling loop
Pass webhook_url and get one signed POST when the job ends.
Illustration (stock video), not VimeoClip output · Storyblocks




