Clipkiln Open Clipkiln

Clipkiln API

Turn videos into captioned short clips, make narrated story videos, and post them — from your own code. Everything the website does with a video, the API does too.

Two ways to use it

  • A Clipkiln plan (Base, Pro, Max). The API uses your plan's monthly minutes, exactly like the website.
  • A pay-as-you-go API account. No plan and no monthly fee: top up credit and pay 5p a minute of video (£3 an hour). Every job — whether you start it from the API or the website — is paid from the credit, and a job that fails is refunded in full. When the credit runs out, new jobs are refused with 402 until you top up; nothing is ever billed afterwards. API accounts get Pro's features (no watermark, high-quality sources, the editing pack). The monthly AI extras of the plans (AI b-roll, upscaling, dubbing, the AI Producer) are not included.

Create an API account: clipkiln.com/?account=api. Then open Account → Developers to top up (£10–£500 at a time; VAT included), make API keys and add webhooks.

GET /api/api-account
  → { "credit": "£12.34", "credit_pence": 1234.0, "minutes_left": 246,
      "pence_per_minute": 5, ... }

Webhooks

Instead of polling, give Clipkiln an https:// address (Account → Developers, or POST /api/webhooks {"url": "https://…"}) and it calls it when work finishes. You get a signing secret once; keep it.

EventWhendata
clips.readyA video's moments are foundjob_id, clip_count
clips.failedA video could not be processedjob_id
clip.exportedA clip finished renderingjob_id, clip_id, download_path
clip.failedA clip's render failedjob_id, clip_id, error
story.done / story.failedA story video finished / failedstory_id
post.published / post.failedA post went out / did notpost_id, platform
webhook.testYou pressed "Send test"message

Every call is a POST with a JSON body {"id", "type", "created", "data"} and a header Clipkiln-Signature: t=<unix time>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>.<raw body>" with your secret. Check it, and ignore anything older than five minutes. Answer with any 2xx; anything else is retried after 30 seconds, 5 minutes, 30 minutes and 2 hours, then given up. Use the event id to ignore repeats. Up to 20 addresses per account.

To receive only some events, add them when you create the address: POST /api/webhooks {"url": "https://…", "events": ["clip.exported", "clip.failed"]}. DELETE /api/webhooks/{id} removes one. These work with an API key as well as a login, which is how Zapier, Make and n8n subscribe for you.

import hashlib, hmac, time

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = int(parts["t"]), parts["v1"]
    if abs(time.time() - t) > 300:
        return False
    mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, v1)
const crypto = require("crypto");
function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(parts.v1));
}

Stories API (v1)

Programmatic access to the story-video pipeline: send a script, get a narrated video with subtitles over stock footage — no browser needed. Paid plans and API accounts.

1. Get a key

Log in, then create a key (from the dashboard, or directly):

POST /api/keys           Authorization: Bearer <your-login-JWT>
     { "name": "my integration" }
  → 201 { "id": "...", "prefix": "ck_live_ab12…7f9c", "secret": "ck_live_…" }

The secret is shown once and is unrecoverable. Store it safely. Only its hash is kept.

  • GET /api/keys — list your keys (prefixes, created/last-used; never the secret).
  • DELETE /api/keys/{id} — revoke. Takes effect immediately (next call 401s).

2. Authenticate

Send the key as a bearer token on every /api/v1 call:

Authorization: Bearer ck_live_…

A JWT also works, but a key is what you'd use for automation. Free-plan accounts get 403 plan_not_eligible.

3. Make a video

POST /api/v1/stories
     { "script": "...", "voice": "af_heart", "background": "lava_lamp" }
  → 201 { "id": "st_…", "status": "pending" }

Optional fields (with defaults): max_part_seconds (180), subtitle_font ("Anton"), subtitle_font_size (64), speech_speed (1.1), background_speed (1.0), background_music_track (""), background_music_volume (0.15). Voices: GET /api/stories/voices. Backgrounds: GET /api/stories/backgrounds.

POST /api/v1/stories/{id}/render      → { "status": "synthesizing" }
GET  /api/v1/stories/{id}             ← poll every few seconds
  → { "status": "done", "parts": [ { "part_number": 1, ... } ] }

status goes pending → synthesizing → rendering → done (or failed, with error_message).

GET  /api/v1/stories/{id}/parts/{n}/download    → the finished .mp4

GET /api/v1/stories lists all your stories.

Notes

  • Quota: every render counts against your plan minutes (or, for an API account, its credit at 5p a minute), same as the website — the API cannot bypass limits.
  • Errors are JSON { "detail": { "code": "...", "message": "..." } }. Codes include auth_invalid (bad/revoked key), plan_not_eligible (upgrade needed), too_many_keys, file_too_large (413 — the source exceeds the plan's per-file cap; the payload also carries limit_mb, actual_mb and upgrade_to, the cheapest plan that would accept the file, or null when no plan would).
  • Scope: v1 covers stories, clip extraction and posting to your own connected accounts (below).

Example (bash)

KEY=ck_live_...
ID=$(curl -s -X POST https://clipkiln.com/api/v1/stories -H "Authorization: Bearer $KEY" \
     -H 'content-type: application/json' \
     -d '{"script":"Three facts about octopuses...","background":"lava_lamp"}' | jq -r .id)
curl -s -X POST https://clipkiln.com/api/v1/stories/$ID/render -H "Authorization: Bearer $KEY" >/dev/null
until [ "$(curl -s https://clipkiln.com/api/v1/stories/$ID -H "Authorization: Bearer $KEY" | jq -r .status)" = done ]; do sleep 5; done
curl -s https://clipkiln.com/api/v1/stories/$ID/parts/1/download -H "Authorization: Bearer $KEY" -o video.mp4

Clip API (v1)

Turn a video link into short clips, programmatically. This is the surface the Clipkiln MCP server drives, and it exists so an assistant can hold a conversation about the selection rather than handing over whatever it found.

Open to every account, free included. All you need is a key (or a login). A free account's monthly minutes, watermark and Twitch restriction all still apply — they are enforced on the same code path the website uses, so this gives reach, not extra allowance. (The stories API above is still paid-only.)

Same meter. Minutes are reserved through the same code path the website uses, at the same point — once the source has downloaded and its real duration is known. There is no second ledger and no free mode.

Check the balance first

GET /api/v1/usage
  → { "plan": "pro", "unlimited": false, "minutes_used": 41.2,
      "minutes_limit": 300, "minutes_remaining": 258.8,
      "period_resets_at": "2026-09-24T09:11:02+00:00" }

Submit

POST /api/v1/clips
     { "url": "https://youtu.be/…",
       "scorer": "clipkiln",              // or "external" — see below
       "options": { "category": "funny", "topic": "", "min_clip_seconds": 30 } }
  → 201 { "id": "…", "status": "fetching", "estimated_minutes": 62.4,
          "minutes_reserved": 0.0, "clip_count": 0 }

options is the same payload the website's settings panel posts to /api/jobs/{id}/process — every subtitle, hook, logo and framing default is available and validated identically.

options.spoken_language is the language SPOKEN in the video: "auto" (the default) detects it across the whole audio, or a code (en, es, fr, de, it, pt, nl, ru, ja, ko, zh, ar, he, el, th, tr, pl, cs, hu, ro, vi, hi, bn, ta, te, mr, ur) is used as-is. It is not the caption language — default_subtitle_language translates the captions. An unknown code is a 422.

options.gaming (default false) marks gameplay: the free on-server scan watches the kill feed and on-screen alerts, and kills, multi-kills and victories rank higher. options.game_type narrows it: "shooter", "battle_royale", "moba" or "other" (the default). It never adds AI vision calls and costs no extra minutes. Any other value is a 422.

estimated_minutes is what it is expected to cost, from the link's metadata. Nothing is charged yet: minutes_reserved stays 0 until the file is on disk. A link that lies about its length cannot overcharge anyone, and one that never downloads costs nothing.

The download and processing start by themselves — there is no separate /process call.

Limits: 20 submissions per hour and 3 jobs in flight, both per account. A job waiting for you to choose moments is not "in flight"; it is consuming nothing.

Poll

GET /api/v1/clips/{id}
  → { "status": "transcribing", "progress": 0.42, "minutes_reserved": 62.4, … }
GET /api/v1/clips?limit=20      // your recent jobs, newest first

status is fetching → transcribing → scoring → ready, or awaiting_moments when you are the scorer, or failed with a plain-English error_message. Extraction takes 10–20 minutes.

Choose the moments yourself

Submit with "scorer": "external" and the job transcribes, then stops at awaiting_moments — no candidate generation runs, which is the dominant variable cost of a job.

GET /api/v1/clips/{id}/transcript
  → { "sentence_count": 412,
      "sentences": [{ "id": 0, "start": 0.0, "end": 4.2, "text": "…" }, …] }

These are the exact numbered sentences Clipkiln's own scorer is shown, so a span chosen against them means what one of ours means.

POST /api/v1/clips/{id}/moments
     { "moments": [{ "start_id": 12, "end_id": 19, "title": "the pricing rant",
                     "reason": "clean setup and payoff" }] }     // up to 30
  → 202 { "status": "scoring", … }        then poll until "ready"

Boundaries land on sentence edges. A span whose opener reads as a continuation ("and then he said…") pulls in the preceding sentence, so a clip may start slightly earlier than the id you named — the same mechanical repair our own picks get. Ids outside the transcript are a 400 bad_span straight away, not a failed job twenty seconds later.

Change your mind

POST /moments again. It replaces the clips nobody exported and leaves any already rendered alone — the takes you kept are yours; the ones you argued out are the ones replaced. It costs no minutes, because the source and the transcript are already paid for.

Legal from awaiting_moments or ready. Refused with 409 render_in_progress while a clip is mid-render.

Works on jobs we scored too: read the transcript, disagree, post your own spans.

Read, export, download

GET  /api/v1/clips/{id}/moments        // best first; virality_score 0-100 or null
POST /api/v1/clips/{id}/export         // { "clip_ids": ["…"] } — omit for all
GET  /api/v1/clips/{id}/downloads      // absolute signed links, ~12h

Externally-scored clips do not render on arrival — they are a proposal, and encoding fifteen takes before anyone has looked at them wastes machine time on the twelve about to be replaced. Name the ones you want. (A clipkiln-scored job has already started rendering by the time it is ready; calling export is then harmless — the queue skips anything already made or being made.)

An externally-chosen clip has no rubric score — nothing scored it, and score is therefore 0.0 rather than an invented number. virality_score is the rated one, and is what GET /moments sorts by.

virality_score is a prediction from the transcript, not a measurement. An LLM rates the clip's words against six fixed factors and those ratings are combined with fixed weights; it never sees the video, and it has never been calibrated against real view counts. It is absolute — the same clip gets the same score regardless of what else was scored alongside it, so a threshold means the same thing for every video — but do not present it to an end user as a forecast of reach. null means the clip was not rated (scoring is best-effort); that is distinct from a low score and must not be treated as one.