Developers

Cropus API

Upload a video, reframe it or cut it into shorts, and download the results from your own code. The API is available on paid plans. Create a key at /app/api. The machine-readable description is the OpenAPI 3.1 document. Prefer to work from a chat? Connect Cropus to ChatGPT or Claude instead.

Quickstart

Every path below is relative to https://cropus.io/api, so /v1/account is https://cropus.io/api/v1/account. JSON is snake_case, timestamps are ISO 8601 UTC, durations are in seconds and minutes are decimals.

export CROPUS_API=https://cropus.io/api
export CROPUS_KEY=crp_live_...

# 1. Start an upload. Send exactly one of "reframe" and "shorts".
curl -s $CROPUS_API/v1/uploads \
  -H "Authorization: Bearer $CROPUS_KEY" \
  -H "Idempotency-Key: my-upload-1" \
  -d '{"file_name":"talk.mp4","size_bytes":52428800,"duration_sec":600,
       "reframe":{"formats":["9:16","1:1"],"mode":"smart"}}'
# -> {"id":"3f1c2d9e-7a4b-4c58-9e0d-6b1f2a8c5d47","part_size":16777216,"part_count":4,
#     "parts":[{"n":1,"url":"https://..."}, ...],"expires_at":"..."}

# 2. PUT each part to its URL and keep the ETag response header.
#    (part_size bytes per part; the last one is smaller.)
curl -s -D - -o /dev/null -T talk.mp4 "<url of part 1>"      # a single-part file
dd if=talk.mp4 bs=16777216 skip=1 count=1 2>/dev/null \
  | curl -s -D - -o /dev/null -T - "<url of part 2>"          # part n: skip=n-1
# -> ETag: "9b2cf535f27731c974343645a3985328"

# 3. Complete the upload with every part number and its ETag. Minutes are charged now.
curl -s $CROPUS_API/v1/uploads/<id>/complete \
  -H "Authorization: Bearer $CROPUS_KEY" \
  -d '{"parts":[{"n":1,"etag":"\"9b2c...\""},{"n":2,"etag":"\"4e1a...\""}]}'
# -> 201 the video, with its job

# 4. Poll until the job's status is "completed" or "failed" (or use a webhook).
curl -s $CROPUS_API/v1/videos/<video id> -H "Authorization: Bearer $CROPUS_KEY"

# 5. Download: each output has a download_url, valid 2 hours.
curl -L -o talk-9x16.mp4 "<download_url>"
  • Part URLs are valid 1 hour. For a large file or a slow link, get fresh ones with POST /v1/uploads/{id}/parts and {"parts":[3,4]} (up to 50 per call). The upload stays reserved while its handed-out URLs are valid. An upload not completed within 24 hours is aborted.
  • DELETE /v1/uploads/{id} cancels an upload and deletes the parts stored so far.
  • complete also takes start and end (seconds) to process only part of the video; only that part is charged.
  • Lists (GET /v1/videos) return download_url: null. Fetch one video or job for links.

Authentication

Send Authorization: Bearer crp_live_... on every request. A key has full access to its account and is shown once, when you create it at /app/api; you can have up to 10 active keys, and revoking one takes effect on the next request. Only the /v1/openapi.json document needs no key. If the account stops being on a paid plan, every request answers 403 paid_plan_required.

Every response carries X-Request-Id (req_...). Quote it when you write to support: the request log on /app/api shows it, kept 30 days.

Errors

Errors have the body {"error":{"code","message","request_id", ...}}. Branch on code, not on the message.

CodeStatusMeaning
invalid_api_key401The key is missing, malformed, unknown or revoked.
paid_plan_required403The API is for paid plans only (a plan in force, or any minute pack ever bought).
rate_limited429Too many requests. Wait Retry-After seconds.
invalid_request400A field is wrong; field names it. Also 413 when the request body exceeds 64 KiB.
insufficient_minutes402Not enough minutes; needed and available are in minutes.
video_too_long400The video is longer than your plan allows.
file_too_large413The file is over the size limit.
too_many_uploads429Too many open uploads. Finish or cancel one.
uploads_paused503Uploads are paused for now. Try again later.
shorts_unavailable503Shorts are unavailable right now.
not_found404No such video, upload or job in your account.
source_expired410The saved source was deleted, so nothing more can be rendered from it.
idempotency_key_reused409That Idempotency-Key was used with a different request body.
internal_error500Our side failed. Retry with the same Idempotency-Key and quote the request id to support.

Idempotency

Add Idempotency-Key: <unique string, up to 255 characters> to any POST. If a request times out, send it again with the same key and body: you get the first response back (same status and body) and minutes are charged once. The same key with a different body answers 409 idempotency_key_reused. Only POST requests use the header.

  • The stored response is replayed for 24 hours.
  • An upload, shorts job or reframe job made with a key stays tied to that key after that too: the same key on the same endpoint returns that video or job again instead of making a new one. Use a new key for new work; never reuse one for something else.
  • 4xx answers are stored and replayed like any other, including 402 insufficient_minutes: after topping up, send the request with a new key. 5xx answers are not stored, so retry those with the same key.

Rate limits

120 requests per 60 seconds per key. X-RateLimit-Limit and X-RateLimit-Remaining are on every authenticated response. Over the limit you get 429 rate_limited with Retry-After in seconds. Prefer a webhook to polling.

Resources

EndpointWhat it does
GET /v1/account{ minutes_available, plan }
POST /v1/uploadsStart an upload (201). Body: file_name, size_bytes, optional duration_sec, and one of reframe / shorts.
POST /v1/uploads/{id}/partsFresh part URLs.
POST /v1/uploads/{id}/completeCharge and queue (201 video). Repeating it returns the same video, charged once.
DELETE /v1/uploads/{id}Cancel (204).
GET /v1/videos?cursor={ data: [video], next_cursor }, newest first, no download URLs.
GET /v1/videos/{id}A video with its jobs and download links.
DELETE /v1/videos/{id}Delete (204); unfinished work is refunded.
POST /v1/videos/{id}/reframesMore formats from the saved source (201 video), added free to the newest reframe job. Body: formats, mode. A video with no reframe job (uploaded for shorts) gets a new one, charged like an upload; optional start, end (seconds) pick a segment for it, the whole video by default.
POST /v1/videos/{id}/shortsA new shorts job (201 video). Body: optional start, end, options.
GET /v1/videos/{id}/jobs/{job_id}One job with download links.

Shapes

video: { id, file_name, duration_sec, width, height, created_at, expires_at, files_deleted,
         jobs: [job] }                       // newest first
job:   { id, kind: "reframe" | "shorts",
         status: "queued" | "processing" | "completed" | "failed",
         progress: { done, total }, error, segment: { start_sec, end_sec } | null,
         minutes_charged, minutes_refunded, created_at, finished_at,
         outputs: [{ id, format, mode, status, download_url, download_expires_at }],   // reframe
         clips:   [{ id, rank, status, start_sec, end_sec, duration_sec, title,
                     description, hashtags, download_url, download_expires_at }] }     // shorts

A job is completed when everything is finished and at least one result succeeded, and failed when nothing did. Files are deleted at expires_at (files_deleted); then no download links are given.

Options

  • reframe.formats: any of "9:16", "4:5", "1:1", "16:9" (default ["9:16"]). reframe.mode: "smart" or "center".
  • shorts.count: 1 to 10 (default 5). shorts.length: "15-30", "30-60", "60-90" seconds (default "30-60"). shorts.captions: true or false (default true). shorts.style: "bold", "box", "clean" (default "bold"). shorts.wish: what the clips should be about, up to 200 characters.

Webhooks

Configure one https endpoint on /app/api; you get a secret whsec_..., can rotate it and send a test event. Cropus POSTs job.completed or job.failed when a job settles (and test from the button). If more formats are added to a settled job, it fires again with a new event id. Events are created only for jobs that settle after the endpoint is saved: there is no replay of history. They cover all of the account's jobs.

{ "id": "evt_...", "type": "job.completed", "created_at": "2026-11-16T14:09:03.000Z",
  "data": { "video_id": "...", "job": { ...job, download_url null }, "source": "api", "api_key_id": "..." } }

source is api for jobs created with an API key and web otherwise. Jobs started from the MCP connector also show as web. The job has no download links: GET it for fresh ones.

Delivery

  • Headers: Cropus-Signature and Cropus-Event-Id (the event id, stable across retries).
  • Answer with any 2xx within 10 seconds. Redirects are not followed.
  • Failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h; after the 7th failed attempt the event is marked failed. Delivery is at least once: dedupe on id.
  • The delivery log (with Resend) is on /app/api, kept 30 days. The URL must be https and resolve to a public address.

Verify the signature

Cropus-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Use the raw body, not re-serialized JSON, and reject timestamps older than 5 minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, rawBody, header, toleranceS = 300) {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceS) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const given = Buffer.from(parts.v1 ?? "", "hex");
  const want = Buffer.from(expected, "hex");
  return given.length === want.length && timingSafeEqual(given, want);
}