Skip to main content
[ REST API ]

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.

Request · bash
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"}'
Response · json
{
  "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.

Request · bash
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"
  }'
Response · json
{ "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.

File · bash
# 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.

FieldValuesMeaning
urlStringPublic video link. Use url, file or upload_id.
upload_idStringA slot already filled through POST /api/uploads.
acknowledgedtrueConfirms you may process the content. Required.
target_clips1 to 30How many clips to aim for. You can get fewer if the video lacks good moments.
clip_min_seconds0 to 895Minimum clip length.
clip_max_seconds10 to 900Maximum clip length.
analysis_start_seconds, analysis_end_secondsSeconds, sent togetherAnalyze only one part of the source. Credits follow this window.
output_formatauto, vertical, horizontal, square, portraitClip aspect.
layoutsauto, split, screencast, speaker_cut, punch_in, noneA JSON array or a comma-separated string.
captionstrue, falseWhether captions are burned into the clip.
caption_presetFor example auto, tiktok, reels, minimalCaption look.
source_language, caption_languageISO 639-1 code or autoSpoken language and caption language.
auto_hook, auto_hook_styletrue; classic, dark, yellow, red, outline, outline_yellowThe hook line on the clip. REST only turns it on when you send auto_hook: true.
moment_hintStringA topic or quote to prefer.
clip_workflowbest, coverage, findfind needs moment_hint. coverage needs clip_lenses set to content.
clip_lensesarc, chunk, stitch, seamA comma-separated string. Each extra lens is another AI call.
test_modetrueRuns all the analysis and skips the render. AI cost matches a real job and no webhook fires.
force_low_qualitytrueContinue after a low-resolution warning.
webhook_url, webhook_secretStringGet 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.

Request · bash
# 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"
Trimmed response · json
{
  "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.

Bash · bash
# 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.

402 · json
{
  "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.

CodeWhenWhat to do
200, needs_confirmationThe source is below QUALITY_GATE_MIN_HEIGHT, 720p by default. No job yet.Ask the user, then resend with force_low_quality: true.
400No 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.
401Missing or invalid token.Sign in again.
402Not enough credits.Add credits or ask an admin to grant them.
403An 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.
404The job does not exist or belongs to another account.Check job_id and the account.
503The 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.

Drop the polling loop

Pass webhook_url and get one signed POST when the job ends.

Illustration (stock video), not VimeoClip output · Storyblocks