Skip to main content
[ For developers ]

Put VimeoClip inside your code, agents and workflows

Send a video link through the REST API or MCP, get vertical clips back on a webhook, and carry on in n8n. Every call runs under your own account and credits.

Four ways into the same pipeline

All four run through the backend routes, so permissions, credits and job ownership match the dashboard exactly.

REST API

POST /api/process takes a link or a file. GET /api/status/{job_id} returns progress and the clip list.

See the API

MCP

POST /mcp gives an agent 8 tools: start a job, upload a file, read status, list clips, restyle captions, recut, publish.

See MCP

Webhooks

Pass webhook_url to get one POST when the job ends. Add webhook_secret and the body is signed with HMAC-SHA256.

See webhooks

n8n

Two workflow templates ship with the source in examples/n8n: one takes a link and returns clips, one follows a YouTube channel.

See n8n

From a video link to a clip list

Three steps with curl and jq. BASE is the VimeoClip backend address.

Bash · bash
BASE=http://localhost:8000

# 1. Sign in. The response carries access_token.
TOKEN=$(curl -s -X POST "$BASE/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"YOUR_PASSWORD"}' | jq -r .access_token)

# 2. Start a job. The response carries job_id.
JOB_ID=$(curl -s -X POST "$BASE/api/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","acknowledged":true}' | jq -r .job_id)

# 3. Read the status and the clips.
curl -s "$BASE/api/status/$JOB_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '{status, progress, clips: .result.clips}'

What each route needs

A new account is a member. A route that is not on the member list can only be called by an admin.

What you want to doRouteMinimum role
Start a job, upload a filePOST /api/process, POST /api/uploadsMember
Read status, download your clipsGET /api/status/{job_id}, GET /videos/{job_id}/…Member, job owner
Use an agentPOST /mcpMember
Restyle captions, recut a clipPOST /api/subtitle, POST /api/clip/rerenderAdmin
Publish or schedule a postPOST /api/social/postAdmin

Without a session you get 401. A member calling an admin route gets 403.

What you need before calling

  • A VimeoClip account. The address you call is the host of the dashboard you use.
  • An osk_ API key created on the API access page, or a session token from POST /api/auth/login with your password.
  • Enough credits on the account, because every job reserves credits when it is accepted. A new account can have 0 credits.
  • GEMINI_API_KEY or LLM_BASE_URL on the server, or an X-Gemini-Key header on the request.
  • An admin role if you use MCP, edit clips or publish.

Frequently asked questions

Yes. POST /api/process reserves the account's credits when the job is accepted, admin accounts included. MCP calls that same route, so it is charged the same way. A failed or cancelled job is refunded.

Start with one request

The API page lists the POST /api/process fields, how to read clips and the error codes.

Illustration (stock video), not VimeoClip output · Storyblocks