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}/partsand{"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.completealso takesstartandend(seconds) to process only part of the video; only that part is charged.- Lists (
GET /v1/videos) returndownload_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.
| Code | Status | Meaning |
|---|---|---|
invalid_api_key | 401 | The key is missing, malformed, unknown or revoked. |
paid_plan_required | 403 | The API is for paid plans only (a plan in force, or any minute pack ever bought). |
rate_limited | 429 | Too many requests. Wait Retry-After seconds. |
invalid_request | 400 | A field is wrong; field names it. Also 413 when the request body exceeds 64 KiB. |
insufficient_minutes | 402 | Not enough minutes; needed and available are in minutes. |
video_too_long | 400 | The video is longer than your plan allows. |
file_too_large | 413 | The file is over the size limit. |
too_many_uploads | 429 | Too many open uploads. Finish or cancel one. |
uploads_paused | 503 | Uploads are paused for now. Try again later. |
shorts_unavailable | 503 | Shorts are unavailable right now. |
not_found | 404 | No such video, upload or job in your account. |
source_expired | 410 | The saved source was deleted, so nothing more can be rendered from it. |
idempotency_key_reused | 409 | That Idempotency-Key was used with a different request body. |
internal_error | 500 | Our 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
| Endpoint | What it does |
|---|---|
GET /v1/account | { minutes_available, plan } |
POST /v1/uploads | Start an upload (201). Body: file_name, size_bytes, optional duration_sec, and one of reframe / shorts. |
POST /v1/uploads/{id}/parts | Fresh part URLs. |
POST /v1/uploads/{id}/complete | Charge 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}/reframes | More 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}/shorts | A 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 }] } // shortsA 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-SignatureandCropus-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);
}