Video API

Overview

The Video API turns your video files into streaming-ready, downloadable MP4s. Upload a file, optionally trim it, hide sensitive regions, or combine clips, then download the result. It accepts MP4, MOV, MKV, WebM and most other formats, up to 20 GiB and 8 hours per file.

Video bytes never pass through the API. You upload them directly to storage with short-lived pre-signed URLs, which keeps large uploads fast and reliable.

Authentication

Every request carries your API key as a bearer token:

Authorization: Bearer vpk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Your key is issued to you by the service owner. Treat it like a password: anyone who has it can upload videos as you.
• Each key belongs to one user. You only ever see your own videos; any other video ID answers 404 NOT_FOUND.
• A missing, unknown or revoked key gets 401 UNAUTHORIZED. Revoked keys stop working within a minute.

Accounts and API keys

Sign up in the web app with your email (a 6-digit code is sent to you). Once signed in, create API keys on the Account page. Each key is shown once; you cannot retrieve it again. API keys can also be created programmatically with POST /account/keys when signed in with a session token. Your account shows your plan, usage this month and API keys.

Quickstart

Upload a video, wait for it to process, and download the MP4. Set two environment variables first:

export VIDEO_API="https://api.videopiper.dev/v1"
export VIDEO_API_KEY="vpk_..."   # your key

# Uses jq to read JSON. Files up to 64 MiB are a single part (see Python/JavaScript for any size).
AUTH="Authorization: Bearer $VIDEO_API_KEY"; JSON="Content-Type: application/json"

# 1. Create the video
SIZE=$(wc -c < lesson.mp4 | tr -d ' ')
VIDEO_ID=$(curl -s -X POST "$VIDEO_API/videos" -H "$AUTH" -H "$JSON" \
  -d "{\"fileName\":\"lesson.mp4\",\"sizeBytes\":$SIZE}" | jq -r .videoId)

# 2. Get an upload URL for part 1, and PUT the bytes to it (no Authorization header)
PART_URL=$(curl -s -X POST "$VIDEO_API/videos/$VIDEO_ID/parts" -H "$AUTH" -H "$JSON" \
  -d '{"partNumbers":[1]}' | jq -r '.parts[0].url')
curl -s -T lesson.mp4 "$PART_URL"

# 3. Start processing
curl -s -X POST "$VIDEO_API/videos/$VIDEO_ID/complete" -H "$AUTH" -H "$JSON" -d '{}'

# 4. Wait for SUCCEEDED, then download
until [ "$(curl -s "$VIDEO_API/videos/$VIDEO_ID" -H "$AUTH" | jq -r .status)" != "RUNNING" ]; do sleep 10; done
curl -s "$VIDEO_API/videos/$VIDEO_ID" -H "$AUTH" | jq -r .status          # expect SUCCEEDED
curl -s -o lesson-processed.mp4 "$(curl -s "$VIDEO_API/videos/$VIDEO_ID" -H "$AUTH" | jq -r .downloadUrl)"

# pip install requests. Handles any file size (parts are uploaded in turn).
import os, time, requests

API, KEY = os.environ["VIDEO_API"], os.environ["VIDEO_API_KEY"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {KEY}"

def call(method, path, **kwargs):
    response = session.request(method, API + path, timeout=60, **kwargs)
    if not response.ok:
        error = response.json()
        raise RuntimeError(f"{response.status_code} {error['error']}: {error['message']} (request {error['requestId']})")
    return response.json()

path = "lesson.mp4"
size = os.path.getsize(path)
video = call("POST", "/videos", json={"fileName": os.path.basename(path), "sizeBytes": size, "maxHeight": 1080})
video_id, part_size, part_count = video["videoId"], video["partSize"], video["partCount"]

with open(path, "rb") as source:
    for first in range(1, part_count + 1, 100):                      # up to 100 URLs per request
        numbers = list(range(first, min(first + 100, part_count + 1)))
        for part in call("POST", f"/videos/{video_id}/parts", json={"partNumbers": numbers})["parts"]:
            source.seek((part["partNumber"] - 1) * part_size)
            requests.put(part["url"], data=source.read(part["sizeBytes"]), timeout=600).raise_for_status()

call("POST", f"/videos/{video_id}/complete", json={})

while (status := call("GET", f"/videos/{video_id}"))["status"] in ("SUBMITTED", "RUNNING"):
    time.sleep(10)
if status["status"] != "SUCCEEDED":
    raise RuntimeError(f"Processing ended with {status['status']}")
with requests.get(status["downloadUrl"], stream=True, timeout=600) as download, open("lesson-processed.mp4", "wb") as out:
    for chunk in download.iter_content(1 << 20):
        out.write(chunk)

// Node.js 18+ (built-in fetch). Handles any file size (parts are uploaded in turn).
import { open, stat } from "node:fs/promises";

const API = process.env.VIDEO_API, KEY = process.env.VIDEO_API_KEY;

async function call(method, path, body) {
  const response = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const data = await response.json();
  if (!response.ok) throw new Error(`${response.status} ${data.error}: ${data.message} (request ${data.requestId})`);
  return data;
}

const path = "lesson.mp4";
const { size } = await stat(path);
const { videoId, partSize, partCount } = await call("POST", "/videos", { fileName: "lesson.mp4", sizeBytes: size });

const file = await open(path);
for (let first = 1; first <= partCount; first += 100) {          // up to 100 URLs per request
  const partNumbers = Array.from({ length: Math.min(100, partCount - first + 1) }, (_, i) => first + i);
  const { parts } = await call("POST", `/videos/${videoId}/parts`, { partNumbers });
  for (const part of parts) {
    const bytes = Buffer.alloc(part.sizeBytes);
    await file.read(bytes, 0, part.sizeBytes, (part.partNumber - 1) * partSize);
    const put = await fetch(part.url, { method: "PUT", body: bytes });   // no Authorization header
    if (!put.ok) throw new Error(`Part ${part.partNumber} failed: ${put.status}`);
  }
}
await file.close();

await call("POST", `/videos/${videoId}/complete`, {});

let status;
do {
  await new Promise((r) => setTimeout(r, 10_000));
  status = await call("GET", `/videos/${videoId}`);
} while (["SUBMITTED", "RUNNING"].includes(status.status));
console.log(status.status, status.downloadUrl);

Short videos are usually ready within a minute or two of complete; long videos are processed in parallel chunks.

Concepts

Video lifecycle

Priority processing

Paid plans get priority. Videos from paid plans are scheduled ahead of free-tier videos when capacity is contended, so paid customers never wait behind a free-tier backlog. Plan changes take effect within ~60 seconds.

Conventions

• IDs: videoId is 32 lowercase hex characters.
• Times are seconds (decimals allowed). An end of null means "to the end".
• Positions on screen (x, y, w, h) are fractions of the frame from 0 to 1, so they work at every quality level.
• Strict input: unknown fields are refused with 400 INVALID_REQUEST, so a typo can't be silently ignored.
• Results: each finished video has an MP4 (H.264/AAC, with fast start for streaming playback).

Uploading videos

1. Create the video with its file name and exact size: POST /videos. You get a videoId, a partSize (64 MiB) and a partCount.
2. Get part URLs: POST /videos/{videoId}/parts with up to 100 partNumbers per call. Each URL is valid for 15 minutes, so request them shortly before use.
3. Upload each part with PUT <url>. Part n is the byte range starting at (n − 1) × partSize, exactly sizeBytes long. Send no Authorization header. Parts can upload in parallel (4–8 at a time works well) and in any order.
4. Complete: POST /videos/{videoId}/complete, optionally with processing options. Processing starts.

POST /videos
{ "fileName": "lesson.mp4", "sizeBytes": 734003200, "maxHeight": 1080 }

201 Created
{ "videoId": "3f1c0a9e5b7d4c2a8e6f1b0d9c7a5e3f", "partSize": 67108864, "partCount": 11,
  "status": "UPLOADING", "statusPath": "/videos/3f1c0a9e5b7d4c2a8e6f1b0d9c7a5e3f" }

POST /videos/3f1c…/parts
{ "partNumbers": [1, 2, 3] }

200 OK
{ "parts": [ { "partNumber": 1, "sizeBytes": 67108864, "url": "https://…" }, … ], "expiresInSeconds": 900 }

• Retries: if a part fails or its URL expires, request a new URL for that part number and upload it again. complete is safe to call more than once: it never starts a second job.
• Abandoned uploads (never completed) are deleted automatically after 2 days. To discard one sooner, call POST /videos/{videoId}/abort.
• Incomplete uploads: complete answers 409 UPLOAD_INCOMPLETE if a part is missing or the wrong size.

Import from a URL

Instead of uploading a file, send a public HTTPS URL and the API downloads it. The file is checked once it arrives and processed immediately, just like an upload. Processing options (trim, redactions, deleteOriginal) go in the request.

The URL must be HTTPS and resolve only to public internet addresses. The file size limit is the same as uploads (20 GiB by default). The server must answer 200 with the file (at most 3 redirects, each re-checked); Dropbox share links need ?dl=1, and presigned S3 links work fine.

POST /videos
{ "sourceUrl": "https://example.com/videos/tutorial.mp4", "fileName": "tutorial.mp4", "maxHeight": 1080 }

201 Created
{ "videoId": "3f1c0a9e5b7d4c2a8e6f1b0d9c7a5e3f", "status": "SUBMITTED",
  "fileName": "tutorial.mp4", "statusPath": "/videos/3f1c0a9e5b7d4c2a8e6f1b0d9c7a5e3f" }

Unlike an upload, there is no parts step or complete call. Dry runs (?dryRun=true) validate the URL without downloading. While the download is in progress the video record has no sourceVersionId; it fills in from the receipt once the file arrives. The download is retried once on network errors; 4xx and size-limit errors are permanent.

AUTH="Authorization: Bearer $VIDEO_API_KEY"; JSON="Content-Type: application/json"

# Create the video from a URL
VIDEO_ID=$(curl -s -X POST "$VIDEO_API/videos" -H "$AUTH" -H "$JSON" \
  -d '{"sourceUrl":"https://example.com/videos/tutorial.mp4","fileName":"tutorial.mp4","maxHeight":1080}' | jq -r .videoId)

# Poll status until ready
until [ "$(curl -s "$VIDEO_API/videos/$VIDEO_ID" -H "$AUTH" | jq -r .status)" != "RUNNING" ]; do sleep 10; done

# Download
curl -s -o tutorial-processed.mp4 "$(curl -s "$VIDEO_API/videos/$VIDEO_ID" -H "$AUTH" | jq -r .downloadUrl)"

import os, time, requests

API, KEY = os.environ["VIDEO_API"], os.environ["VIDEO_API_KEY"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {KEY}"

video = session.request("POST", API + "/videos", json={
    "sourceUrl": "https://example.com/videos/tutorial.mp4",
    "fileName": "tutorial.mp4",
    "maxHeight": 1080
}, timeout=60).json()
video_id = video["videoId"]

status = {"status": "SUBMITTED"}
while status["status"] in ("SUBMITTED", "RUNNING"):
    time.sleep(10)
    status = session.request("GET", API + f"/videos/{video_id}", timeout=60).json()

if status["status"] != "SUCCEEDED":
    raise RuntimeError(f"Processing ended with {status['status']}")

with requests.get(status["downloadUrl"], stream=True) as download, open("tutorial-processed.mp4", "wb") as out:
    for chunk in download.iter_content(1024*1024):
        out.write(chunk)

Limits and errors

• URL format: must be HTTPS, 1–2,048 characters, with no username or password embedded.
• Redirects: at most 3; each destination is checked the same way (HTTPS, public internet).
• Content-Length: checked up front; if the declared size exceeds the limit, the import fails immediately.
• Network errors: retried once (e.g. timeout, connection reset). Other errors are permanent: 404, size limit hit, empty file, DNS failure, private address.
• No camera / streaming: imports work only with single files. Use regular uploads for screen + camera or upload-while-recording.
• Idempotency: `Idempotency-Key` works the same way as for uploads and edits.

Uploads from a browser

To let your users upload from your web app without exposing your key, split the work between your backend and the browser:

1. The browser tells your backend the file name and size.
2. Your backend calls POST /videos and POST /videos/{id}/parts, and returns only the videoId, the partSize and the part URLs.
3. The browser PUTs each slice (file.slice(start, start + sizeBytes)) straight to its URL. Storage accepts cross-origin PUTs, and exposes the ETag header.
4. The browser tells your backend it's done; your backend calls complete.

// Browser: upload the slices your backend signed
for (const part of parts) {
  const start = (part.partNumber - 1) * partSize;
  const response = await fetch(part.url, { method: "PUT", body: file.slice(start, start + part.sizeBytes) });
  if (!response.ok) throw new Error(`Part ${part.partNumber} failed`);
}

For playback or download in the browser, pass the downloadUrl from a status response to the page. It's valid for 15 minutes.

Warm-up for faster processing

Request parts progressively as you upload (e.g., every few parts) rather than requesting all parts at once from the beginning. When you request the last few parts (within 192 MiB from the end of the file), the API automatically starts the processing container early so it boots while those final parts upload. This can cut total processing time nearly in half.

This happens automatically—no extra API calls needed. Asking for all parts at once, starting from part 1, skips warm-up (unless the whole file is ≤192 MiB). The web UI and example code already request parts progressively, so you get this benefit by default.

Screen + camera

Upload a screen recording and a camera recording together. The result shows the camera in the bottom-right corner of the screen, with both audio tracks mixed. Record both in the same session so they line up.

POST /videos
{ "fileName": "screen.webm", "sizeBytes": 209715200,
  "layout": "pip", "camera": { "fileName": "camera.webm", "sizeBytes": 52428800 } }

The response adds camera.partSize and camera.partCount. Request the camera's part URLs with "file": "camera", upload both files, then call complete once.

Processing options

Send these in the body of complete (and of reprocess). maxHeight is set on create.

POST /videos/3f1c…/complete
{
  "trim": { "start": 4.5, "end": 312 },
  "redactions": [
    { "type": "box",  "x": 0.05, "y": 0.04, "w": 0.30, "h": 0.06, "start": 0, "end": null },
    { "type": "blur", "shape": "ellipse", "x": 0.62, "y": 0.55, "w": 0.20, "h": 0.30, "start": 12.5, "end": 20 }
  ]
}

Redaction fields

Following moving content

For something that moves, like a face walking across the frame, give the region a track of keyframes instead of x, y, w, h. It glides smoothly between them, resizing as it goes:

{ "type": "blur", "shape": "ellipse", "start": 4, "end": 12,
  "track": [ { "time": 4,  "x": 0.10, "y": 0.30, "w": 0.15, "h": 0.25 },
             { "time": 8,  "x": 0.45, "y": 0.28, "w": 0.18, "h": 0.30 },
             { "time": 12, "x": 0.80, "y": 0.30, "w": 0.15, "h": 0.25 } ] }

Add a keyframe wherever the motion changes direction or speed. Up to 50 keyframes per region.

Trim, stitch & splice

An edit makes a new video from clips of your finished videos (status SUCCEEDED). Send POST /videos with an edit instead of a file. There's nothing to upload; poll the new video's status as usual.

Also accepted: fileName, maxHeight, and redactions (on the edit's own timeline). Up to 50 clips. The first clip sets the frame size; differently shaped clips are letterboxed.

Recipes

// Cut 1:00–1:30 out of a video
{ "edit": { "clips": [ { "videoId": "AAAA…", "end": 60 }, { "videoId": "AAAA…", "start": 90 } ] } }

// Stitch an intro, a lesson and an outro, with soft joins
{ "fileName": "Lesson 1", "edit": { "clips": [
  { "videoId": "INTRO…" },
  { "videoId": "LESSON…", "transition": { "type": "fade", "seconds": 0.75 } },
  { "videoId": "OUTRO…",  "transition": { "type": "fadeblack", "seconds": 1 } } ] } }

// Splice a clip into another at 2:00
{ "edit": { "clips": [
  { "videoId": "MAIN…", "end": 120 },
  { "videoId": "INSERT…", "transition": { "type": "fadeblack", "seconds": 0.5 } },
  { "videoId": "MAIN…", "start": 120, "transition": { "type": "fadeblack", "seconds": 0.5 } } ] } }

201 Created
{ "videoId": "9a8b…", "status": "SUBMITTED", "clips": 3, "statusPath": "/videos/9a8b…" }

A clip from someone else's video gets 404 NOT_FOUND; a video still processing gets 409 EDIT_SOURCE_NOT_READY. To trim a new upload, use the trim option on complete instead: it's faster.

Status & download

GET /videos/3f1c…
{
  "videoId": "3f1c…",
  "status": "SUCCEEDED",
  "startedAt": 1790903142.5,
  "readyAt": 1790903205.0,
  "progress": { "planned": true, "chunksTotal": 4, "chunksDone": 4, "audioDone": true,
                "videoSeconds": 312.4, "topRendition": "1080p" },
  "downloadUrl": "https://…/download.mp4?…",
  "downloadExpiresInSeconds": 900
}

• Poll every 5–15 seconds while the status is SUBMITTED or RUNNING. Don't poll faster than once a second per video.
• downloadUrl is valid for 15 minutes. Fetch the status again for a fresh link, and don't store the link.
• posterUrl is a still frame (JPEG) for thumbnails, also valid for 15 minutes.
• progress shows chunks encoded out of the total, plus audio; videoSeconds is the result's length.
• Processing time is readyAt − startedAt (Unix seconds).
• edit / trim (when used) echo exactly how the video was cut, so you can check what was requested.

Streaming (Pro and Scale)

On Pro and Scale, finished videos also have adaptive streaming copies (HLS), and the status includes a link any standard player can play. The player picks the quality that suits each viewer's connection.

"streamUrl": "https://…/stream/3f1c…/1790925000/9b2e…/master.m3u8",
"streamExpiresAt": 1790925000

• The link is valid for 6 hours (streamExpiresAt, Unix seconds). Fetch the status again for a fresh one when you load a player; don't store it.
• It works in Safari and iOS natively, and anywhere else with hls.js, video.js, Shaka or ExoPlayer, including on your own website.
• Streaming copies count toward your plan's storage. On other plans, videos get the download only.

<!-- hls.js where the browser can't play HLS itself -->
<video id="player" controls playsinline></video>
<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
<script>
  const video = document.getElementById("player"), url = STREAM_URL;  // from GET /videos/{id}
  if (video.canPlayType("application/vnd.apple.mpegurl")) video.src = url;
  else { const hls = new Hls(); hls.loadSource(url); hls.attachMedia(video); }
</script>

Listing your videos

GET /videos?limit=25
{ "videos": [ { "videoId": "9a8b…", "fileName": "Lesson 1", "createdAt": 1790903100, "state": "SUBMITTED", "clips": 3 }, … ],
  "nextToken": "eyJ2…" }

The newest videos come first. Pass nextToken back to get the next page. state only tells uploading from submitted; call GET /videos/{id} for the live status.

Uploading while recording (advanced)

For live recordings, upload while the recording is still being made, so the result is ready moments after it stops:

1. Create with "streaming": true (no sizeBytes). Add "prestart": true to have processing ready and waiting.
2. Request each part's URL with its exact size: {"parts": [{"partNumber": 4, "sizeBytes": 8388608}]}. Every part except the last must be at least 5 MiB.
3. With prestart, send POST /videos/{id}/heartbeat every ~10 seconds while recording. If heartbeats stop for 2 minutes, the waiting job gives up.
4. When recording ends, call complete with the totals: {"source": {"sizeBytes": …, "partCount": …}}. To cancel instead, call abort.

Usage and billing

Each user's usage is metered by month for billing. Call GET /usage?month=YYYY-MM to fetch processing and storage totals:

GET /usage?month=2026-10
{
  "month": "2026-10",
  "complete": true,
  "processing": {
    "videos": 5,
    "outputMinutes": 126.45,
    "billableMinutes": 158.60
  },
  "storage": {
    "gbMonths": 4.237,
    "storedGb": 1.506,
    "note": "download MP4s, posters and originals; streaming (HLS) copies are not billed"
  },
  "delivery": {
    "gb": null,
    "note": "not metered yet"
  }
}

Billing rules

• Processing: billable minutes per video = max(60 seconds, ceil(output seconds)) / 60 × quality multiplier. Quality multiplier: ≤1080p ×1, 1440p ×2, 4K ×4. Counted when the video finishes. Each upload, reprocess and edit that completes counts as one.
• Storage: GB-months = bytes kept × days kept / (1e9 × days in month). Includes download MP4s, posters and original uploads. HLS streaming copies are metered but not billed. Videos deleted in the past still contribute to the month's total up to their deletion date.
• Pricing: free plans have no overage. Paid plans charge $0.09/minute and $0.15/GB-month for anything over the plan's included limits.
• Delivery: download bandwidth is not metered yet.

Deleting videos

Call DELETE /videos/{id} to remove a video permanently. It cancels any running processing, removes all outputs and work files, and stops billing the video's storage immediately. Usage records stay forever as billing history. The response includes how many bytes were freed.

DELETE /videos/3f1c…
200 OK
{ "videoId": "3f1c…", "deleted": true, "originalDeleted": true, "freedBytes": 1234567890 }

Irreversible: deleted videos can't be reprocessed. If you reprocessed from the same original, it's still kept for other videos that need it.

Account and API keys

Sign up by sending your email to POST /auth/start, which emails a 6-digit code (5 attempts, 10 minute expiry). Verify it with POST /auth/verify, accepting the terms on your first sign-in, to get a sessionToken. Sessions last 30 days and are stored just like API keys but marked as temporary; use the token as a bearer token the same way.

When signed in (session token) or with your API key, you can:

• GET /account for your email, plan name, limits, and this month's usage (minutes, storage).
• GET /account/keys to list your API keys (never the keys themselves; they're shown once at creation).
• POST /account/keys {label} to create a new key. Must be signed in with a session token.
• DELETE /account/keys/{keyId} to revoke a key. Must be signed in with a session token.
• POST /auth/signout to end the session (session tokens only).

Plan limits your maximum quality output, processing minutes and storage per month. Free-plan limits reset on the 1st of the month (UTC). Once your free-plan limit is hit, POST /videos returns 403 PLAN_LIMIT_REACHED. Paid plans continue and the overage is billed at your plan's rate. Usage details are available at GET /account.

Webhooks

Get notified when videos finish or fail, and when you're approaching your plan's limits. Set up a webhook endpoint (URL) in the web app on your Account → Webhooks page, or with the API:

• GET /webhook — your current configuration.
• PUT /webhook {url, events?, enabled?} — save or update an endpoint.
• DELETE /webhook — remove the endpoint.
• POST /webhook/rotate — generate a new signing secret (keep the URL).
• POST /webhook/test — send a test event and report the result immediately.
• GET /webhook/deliveries — the last 30 days of delivery attempts.

Events

Each account has one endpoint that receives events for all types it's subscribed to. The possible events are:

Webhook envelope

Every event arrives as JSON with metadata about the event:

{
  "id": "evt_a1b2c3d4e5f6g7h8",
  "type": "video.ready",
  "createdAt": "2025-01-15T14:30:45Z",
  "data": { event-specific data }
}

Signature verification (Standard Webhooks)

Each delivery includes headers webhook-id, webhook-timestamp and webhook-signature that implement the Standard Webhooks specification, so libraries for any language can verify them:

// npm install standardwebhooks
import { Webhook } from "standardwebhooks";

const wh = new Webhook(webhookSecret);  // your secret from the account page
try {
  const payload = wh.verify(body, {
    "webhook-id": req.headers["webhook-id"],
    "webhook-timestamp": req.headers["webhook-timestamp"],
    "webhook-signature": req.headers["webhook-signature"],
  });
  // payload is the parsed event; proceed
} catch (err) {
  res.status(401).send("Unauthorized");
}

# pip install svix
from svix.webhooks import Webhook

wh = Webhook(webhook_secret)  # your secret from the account page
try:
  payload = wh.verify(body, {
    "webhook-id": headers["webhook-id"],
    "webhook-timestamp": headers["webhook-timestamp"],
    "webhook-signature": headers["webhook-signature"],
  })
  # payload is the parsed event; proceed
except Exception as e:
  return {"error": "Unauthorized"}, 401

// Manual verification (no library needed)
import crypto from "crypto";

const id = req.headers["webhook-id"];
const timestamp = req.headers["webhook-timestamp"];
const signature = req.headers["webhook-signature"];
const body = /* raw request body as string */;

// Extract the base64 part of the secret (after "whsec_")
const secretBytes = Buffer.from(webhookSecret.slice(6), "base64");

// Sign: HMAC-SHA256 of "id.timestamp.body"
const signed = crypto
  .createHmac("sha256", secretBytes)
  .update(`${id}.${timestamp}.${body}`)
  .digest("base64");

// The header is "v1,"
const expected = `v1,${signed}`;
if (signature !== expected) {
  res.status(401).send("Unauthorized");
} else {
  // Valid; parse and process the event
}

Reliability and delivery

• Respond 2xx within 10 seconds. Your endpoint must be HTTPS and reachable from the public internet. Redirects (3xx) are not followed.
• Retry policy: if you don't answer 2xx or timeout, delivery is retried after 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours and 12 hours (8 attempts over ~22 hours).
• At-least-once delivery: events may arrive more than once. Deduplicate using the webhook-id header (unique per event). Events may arrive out of order; use timestamps if order matters.
• Delivery log: check GET /webhook/deliveries to see recent attempts, their status codes, response bodies and errors (kept for 30 days).

URL safety

Webhook URLs must be HTTPS and resolve only to public internet addresses. Private addresses (like 10.0.0.1, 192.168.1.x, 127.0.0.1, localhost or cloud-internal networks) are rejected when you save the URL or on every delivery attempt. This protects you from SSRF attacks. Redirects are never followed; the URL you set is the URL we connect to.

Validation & dry runs

Requests are checked before anything is created or started, against the real lengths of your videos where they're known. That includes trims past the end, clips that don't fit their video, transitions longer than their clips, redaction boxes outside the frame, and times after a video ends. Unknown fields (typos) are refused, never ignored.

Every problem is reported at once in details, each with its field path:

400
{
  "message": "edit.clips[0].end: 80s is past the end of video 3f1c…, which is 60.0s (1:00); use null for \"to the end\" (and 1 more problem)",
  "error": "INVALID_REQUEST",
  "requestId": "…",
  "details": [
    { "field": "edit.clips[0].end", "message": "80s is past the end of video 3f1c…, which is 60.0s (1:00); use null for \"to the end\"" },
    { "field": "redactions[0].w",   "message": "must be a fraction of the frame from 0 to 1; got 1.2 (pixels? divide by the frame size)" }
  ]
}

Dry run

Add ?dryRun=true to POST /videos (an upload or an edit), POST /videos/{id}/complete or POST /videos/{id}/reprocess to check a request without creating or starting anything. It doesn't count toward your daily video limit. A valid request answers 200 with "valid": true; an edit also tells you its resulting length:

POST /videos?dryRun=true
{ "edit": { "clips": [ { "videoId": "3f1c…", "end": 30 },
                       { "videoId": "9a8b…", "transition": { "type": "fade", "seconds": 1 } } ] } }

200 OK
{ "valid": true, "dryRun": true, "fileName": "Edit of 2 clips", "durationSeconds": 49.0, "duration": "49.0s (0:49)", "clips": [ … ] }

Use dry runs to validate user input in your app (for example, an edit timeline a user built) before submitting it.

Idempotency

Send an Idempotency-Key header with requests that create or start something (POST /videos, POST /videos/{id}/complete, POST /videos/{id}/reprocess

How it works

First request
POST /videos HTTP/1.1
Idempotency-Key: my-lesson-upload-20250101-abc123
Content-Type: application/json

{ "fileName": "lesson.mp4", "sizeBytes": 1048576 }

200 OK
{ "videoId": "3f1c0a9e5b7d4c2a8e6f1b0d9c7a5e3f", "partSize": 67108864, … }

Retry with same key (e.g., connection dropped)
POST /videos HTTP/1.1
Idempotency-Key: my-lesson-upload-20250101-abc123

200 OK (same response as first time)
Idempotent-Replayed: true
{ "videoId": "3f1c0a9e5b7d4c2a8e6f1b0d9c7a5e3f", "partSize": 67108864, … }