API Reference

The Recut API is the programmatic surface behind Social Media Clipper. Import a video, transcribe it, find clips, edit by editing text, and render — all over a plain REST API you can drive with curl, any HTTP client, or an AI agent.

Base URL: https://api.socialmediaclipper.comJSON in, JSON out. Errors are always { "error": "…" }.

Authentication

Every request authenticates with an API key sent as a bearer token. Create one in Settings → API keys — the rk_live_… value is shown once, so store it safely. The recut CLI reads the same key from RECUT_API_KEY.

Most endpoints accept an API key or a browser session interchangeably. A few — /api/keys (manage keys) and onboarding — are session-only and return 401 with just a key.

curl -H "Authorization: Bearer rk_live_xxxx" \
  https://api.socialmediaclipper.com/api/projects

Endpoints

The API is self-describing — hit the index for a live list:

curl https://api.socialmediaclipper.com/api

GET/api/me

Your profile and this month's usage.

curl -H "Authorization: Bearer $RECUT_API_KEY" \
  https://api.socialmediaclipper.com/api/me

POST/api/ingest

Create a project from a video URL (e.g. YouTube). Body: { url, name? } → { id }.

curl -X POST https://api.socialmediaclipper.com/api/ingest \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

POST/api/projects

Create a project by uploading a small file (multipart, field file) → { id }. This path is capped at ~4.5 MB; for real videos use the presigned upload flow below.

curl -X POST https://api.socialmediaclipper.com/api/projects \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -F "file=@/path/to/video.mp4"

POST/api/uploads/presign → /api/projects/from-upload

Large-file upload (no 4.5 MB limit): get a presigned S3 URL, PUT the bytes straight to storage, then create the project from the returned key → { id }.

# 1. presign  →  { url, key }
PRESIGN=$(curl -s -X POST https://api.socialmediaclipper.com/api/uploads/presign \
  -H "Authorization: Bearer $RECUT_API_KEY" -H "Content-Type: application/json" \
  -d '{"filename":"talk.mp4","contentType":"video/mp4"}')
URL=$(echo "$PRESIGN" | jq -r .url); KEY=$(echo "$PRESIGN" | jq -r .key)

# 2. upload bytes straight to S3 (the URL is pre-signed — no auth header)
curl -X PUT -H "Content-Type: video/mp4" --upload-file talk.mp4 "$URL"

# 3. create the project  →  { id }
curl -s -X POST https://api.socialmediaclipper.com/api/projects/from-upload \
  -H "Authorization: Bearer $RECUT_API_KEY" -H "Content-Type: application/json" \
  -d "{\"key\":\"$KEY\"}"

GET/api/projects

List your projects, newest first.

curl -H "Authorization: Bearer $RECUT_API_KEY" \
  https://api.socialmediaclipper.com/api/projects

GET/api/projects/{id}

Fetch a project with its transcript, edit state, and render stats → { project, stats }.

curl -H "Authorization: Bearer $RECUT_API_KEY" \
  https://api.socialmediaclipper.com/api/projects/prj_abc123

POST/api/projects/{id}/transcribe

Transcribe the source media. Optional body: { windowStart?, windowEnd? } → { ok, words }.

curl -X POST https://api.socialmediaclipper.com/api/projects/prj_abc123/transcribe \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

POST/api/projects/{id}/edit

Apply an edit op. Body: { op, ...args }. Ops: removeWords, fillers, phrase, ai, retakes, gaps, reset → { edit, stats, note }.

curl -X POST https://api.socialmediaclipper.com/api/projects/prj_abc123/edit \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"fillers"}'

POST/api/projects/{id}/agent

AI co-editor: send a plain-language { message } and it interprets the intent, runs the matching edit (or finds clips / generates b-roll), and replies → { reply, action, edit, stats, broll, clips }.

curl -X POST https://api.socialmediaclipper.com/api/projects/prj_abc123/agent \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"cut every um and trim silences over 1s"}'

POST/api/projects/{id}/clips

AI clip finder. Body: { instruction? } → { clips } (resolved time ranges).

curl -X POST https://api.socialmediaclipper.com/api/projects/prj_abc123/clips \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Find the 3 most viral hooks, 15-45s."}'

POST/api/projects/{id}/clip

Render one sub-clip. Body: { start, end } (seconds) → { url }.

curl -X POST https://api.socialmediaclipper.com/api/projects/prj_abc123/clip \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start":42.1,"end":78.6}'

POST/api/projects/{id}/render

Render the full edited video. Optional body: { captions? } → { url, segments, overlays, captions }.

curl -X POST https://api.socialmediaclipper.com/api/projects/prj_abc123/render \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"captions":true}'

GET/api/projects/{id}/media

Stream or download media (range-enabled). Query: ?out=1 (output), ?clip=NAME, ?thumb=1. Use -L to follow the presigned redirect.

curl -L -H "Authorization: Bearer $RECUT_API_KEY" \
  "https://api.socialmediaclipper.com/api/projects/prj_abc123/media?out=1" -o output.mp4

POST · PUT/api/projects/{id}/broll

Generate animated b-roll overlays (POST, body { instruction? } → { broll }), then save your chosen set (PUT, body { broll }). A later /render bakes them in. Overlays are static (one settled frame each) in the exported mp4.

curl -X POST https://api.socialmediaclipper.com/api/projects/prj_abc123/broll \
  -H "Authorization: Bearer $RECUT_API_KEY" -H "Content-Type: application/json" \
  -d '{"instruction":"highlight every stat and product name"}'

GET / POST / DELETE/api/keys

Manage your API keys. Session-only — call these signed in through the web app, not with an API key. POST returns the plaintext key exactly once; GET lists key prefixes; DELETE ?id=<keyId> revokes one. Or just use the Settings → API keys page.

GET/api/download/{target}

Public (no auth) — redirects to the latest clipper binary for a platform: darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64.

curl -L https://api.socialmediaclipper.com/api/download/darwin-arm64 -o clipper

End-to-end workflow

Import a YouTube video, transcribe it, find the best clip, render it, and download — copy-paste ready.

export RECUT_API_KEY=rk_live_xxxx
export BASE=https://api.socialmediaclipper.com

# 1. Import from a URL → get a project id
ID=$(curl -s -X POST $BASE/api/ingest \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}' | jq -r .id)

# 2. Transcribe
curl -s -X POST $BASE/api/projects/$ID/transcribe \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" -d '{}' | jq

# 3. Find clip-worthy moments
CLIP=$(curl -s -X POST $BASE/api/projects/$ID/clips \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"The single most viral hook, 15-45s."}' | jq '.clips[0]')
START=$(echo "$CLIP" | jq -r .start)
END=$(echo "$CLIP" | jq -r .end)

# 4. Render that clip
URL=$(curl -s -X POST $BASE/api/projects/$ID/clip \
  -H "Authorization: Bearer $RECUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"start\":$START,\"end\":$END}" | jq -r .url)

# 5. Download it
curl -L "$URL" -o clip.mp4

Ready to start? Create an API key and make your first request.