WizCut API
Programmatically upload, process, and render multicam podcast edits with the WizCut API.
The WizCut API lets you automate multicam podcast editing. Upload your camera angles, let WizCut detect speakers, work out who’s on which camera and generate cuts, optionally review them in a hosted editor, and get a rendered video back via webhook.
The full OpenAPI 3.1 spec lives at https://wizcut.com/openapi.json, for code generators and agent platforms. Want ChatGPT, Claude or your own agent to run edits for you instead? See Use WizCut with ChatGPT, Claude and other AI agents.
Authentication
Create an API key at wizcut.com/settings. Include it in every request:
Authorization: Bearer wc_live_your_key_here
Keys can be revoked at any time from the settings page.
Create a job
POST /api/jobs
{
"sources": [
{ "label": "Camera 1", "kind": "video", "ext": "mp4", "fileSize": 2147483648 },
{ "label": "Camera 2", "kind": "video", "ext": "mp4", "fileSize": 1932735283 },
{ "label": "Mic mix", "kind": "audio", "ext": "wav" }
],
"callbackUrl": "https://your-server.com/webhook",
"review": true,
"autoMap": "confident",
"silence": { "mode": "tighten" }
}
Fields:
| Field | Type | Description |
|---|---|---|
sources | array | Camera angles or audio files, up to 12 per job. A job needs at least two video sources before it can be processed. Each has label, optional kind ("video" or "audio", default "video"), optional ext (mp4, mov, webm, mkv, wav, mp3, m4a or aac; default "mp4" for video, "wav" for audio) and optional fileSize: the file’s exact size in bytes, up to 100 GB (107374182400 bytes) per file. |
title | string | Optional. A name for the job, such as the episode title, up to 200 characters. Without one, the title is made from the source labels and the date. |
callbackUrl | string | Optional. URL to receive webhook notifications — see Webhooks. |
review | boolean | Default true. When true, the job pauses at “ready” for human review of cuts before rendering. When false, rendering starts automatically as soon as the speaker mapping is submitted — by a person, your code, or WizCut itself. |
autoMap | string | Default "confident". Whether WizCut may decide on its own who’s on which camera: "off", "confident" or "always" — see Automatic camera mapping. |
silence | object | Optional. Automatic pause removal — see Silence removal. Omitted means off. |
share | boolean | Default true. Gives the finished video an unlisted share page anyone with the link can open — see Sharing and download links. |
You can’t pass the speaker mapping (tracks) here: source IDs only exist once the job is created, so there’s nothing to point a speaker at yet. A tracks list that names speakers is rejected with 400 and "code": "TRACKS_ON_CREATE". Use autoMap, or map speakers via the API once speaker detection is done.
Pass fileSize for every file you know the size of. Files over 100 MB then get a multipart upload, which lets you upload parts in parallel, retry a single part, and is the only way to upload files larger than 5 GB. Without fileSize, every file gets a single presigned PUT, which storage limits to 5 GB.
fileSize has to be exact, because it’s signed into the upload URLs: a PUT whose body is a different size is rejected. A file over the limit is refused with 400 and "code": "FILE_TOO_LARGE" before the job is created; the response includes maxBytes, the limit in bytes. A fileSize that isn’t a whole number of bytes gets "code": "INVALID_FILE_SIZE". A file that can’t be a recording is refused with 422 and "code": "NOT_A_MEDIA_FILE", also before the job is created: a macOS metadata file (a label, or an optional fileName, starting with ._; the real file has the same name without it) or a fileSize under 32 KB. The response names the file in fileName, says why in reason (macos_metadata or too_small) and gives its sourceIndex.
Response:
{
"jobId": "uuid",
"uploads": {
"source-uuid-1": {
"method": "multipart",
"uploadId": "...",
"key": "sources/uuid/source-uuid-1.mp4",
"partSize": 52428800,
"partCount": 41,
"urls": ["https://presigned-part-1-url...", "https://presigned-part-2-url...", "..."]
},
"source-uuid-3": {
"method": "put",
"url": "https://presigned-upload-url..."
}
},
"audioUploads": { "...": "..." }
}
uploads is keyed by the source IDs WizCut assigned, in the same order as your sources array. You can ignore audioUploads — it’s used by the WizCut apps, which upload an extracted audio track ahead of the video.
Retrying safely with Idempotency-Key
If a request times out or the connection drops, you can’t tell whether the job was created. Retry blindly and you may end up with two jobs. To make retries safe, send an Idempotency-Key header with a value you pick for this job — a UUID works well:
curl -s -X POST https://wizcut.com/api/jobs \
-H "Authorization: Bearer wc_live_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b0d7c1e-8a3f-4f8e-9c51-2f0e6d9b7a14" \
-d '{ "sources": [...] }'
It’s optional, and requests without it work exactly as before. We recommend it for agents and for anything that retries on its own.
- Same key, same body: you get the job the first request created — same
jobId, and for multipart uploads the sameuploadId,key,partSizeandpartCount— with every upload URL freshly signed. The response carriesIdempotent-Replayed: true. No second job is created. - Same key, different body:
422with"code": "IDEMPOTENCY_KEY_MISMATCH". Use a new key for a different request. Bodies are compared as parsed JSON, so key order and whitespace don’t matter. - The first request is still running:
409with"code": "IDEMPOTENCY_IN_PROGRESS". Wait a second and retry. - The job was deleted since:
409with"code": "IDEMPOTENCY_KEY_REUSED". Use a new key.
Keys are 1–255 printable ASCII characters (anything else gets 400 with "code": "INVALID_IDEMPOTENCY_KEY"), belong to your account, and are remembered for 24 hours. A request that’s refused before a job is created — a validation error, or your minutes running out — doesn’t use up its key, so you can fix it and retry with the same one.
Upload files
No auth header is needed for the presigned URLs — they’re self-authenticating.
Upload exactly the bytes you declared. HTTP clients set Content-Length from the body they send, so you don’t need to set it yourself.
"method": "put" — PUT the whole file to url within an hour:
curl -X PUT -T mic-mix.wav "https://presigned-upload-url..."
"method": "multipart" — split the file into partSize-byte chunks (the last one is shorter) and PUT chunk n to the URL for part n. Each part URL only accepts that part’s exact length, and there are exactly partCount parts — asking for a higher part number gets a 400:
-
urlsholds the URLs for the first parts (urls[0]is part 1). Request more as you go — up to 16 per request:POST /api/jobs/{jobId}/sources/{sourceId}/parts{ "uploadId": "...", "partNumbers": [5, 6, 7, 8] }The response maps part numbers to URLs:
{ "urls": { "5": "https://...", "6": "https://..." } }. Part URLs are valid for two hours, so fetch them shortly before you use them. -
Once every part is uploaded, finish the upload:
POST /api/uploads/complete{ "key": "sources/uuid/source-uuid-1.mp4", "uploadId": "..." }
To give up on an upload, send the same body to POST /api/uploads/abort.
WizCut checks each file’s real size once it’s uploaded — when you complete a multipart upload, and again when you start processing. A file over the limit is deleted and the request gets 400 with "code": "FILE_TOO_LARGE"; a file much smaller or larger than its declared fileSize gets "code": "FILE_SIZE_MISMATCH". Upload it again to the same source.
Import files from a link
If the recordings are already online — in Google Drive, Dropbox or OneDrive, on a recording platform’s export link, or attached to a chat with an AI assistant — you can hand WizCut the link instead of uploading the bytes. WizCut downloads the file in the background.
Create the job with "sources": [] (or with the files you do upload), then add one file per call:
POST /api/jobs/{jobId}/sources/from-url
{
"url": "https://drive.google.com/file/d/1AbC.../view?usp=sharing",
"label": "Camera 1",
"kind": "video"
}
| Field | Type | Description |
|---|---|---|
url | string | An https:// link to one video or audio file, up to 4096 characters. |
label | string | A name for the file, such as "Camera 1" or "Host mic", up to 80 characters. |
kind | string | Optional: "video" or "audio". Leave it out and WizCut decides from the file. A file with no video in it is always an audio source. |
Response (202 Accepted):
{ "sourceId": "uuid", "status": "importing" }
The call returns straight away. Send an Idempotency-Key header, as for creating a job, so a retry doesn’t import the file twice: the same key and body return the same sourceId, with Idempotent-Replayed: true.
Which links work:
- Direct download links to the file itself, including signed links from storage services and a recording platform’s export link that points at the file.
- Share links from Google Drive, Dropbox, OneDrive and SharePoint. Share them with “anyone with the link”; WizCut turns them into downloads itself, including Drive’s “can’t scan this file for viruses” step for large files.
- Not: web pages, folders, or pages on YouTube, Vimeo, Riverside or Zoom. WizCut doesn’t read pages to find a video in them. Use the platform’s download link, or upload the file.
The formats are the same as for uploads — MP4, MOV, M4A, WebM, MKV, WAV, MP3 and AAC — and WizCut checks the file’s content, not its name. The 100 GB per-file limit applies too.
Following the import. The source counts as uploading until the import is done, so start processing answers 409 with "code": "SOURCES_PENDING" meanwhile. The status summary lists every file under uploads:
{
"uploads": {
"allUploaded": false,
"files": [
{
"sourceId": "uuid",
"label": "Camera 1",
"kind": "video",
"state": "importing",
"progressPercent": 42,
"import": {
"status": "importing",
"host": "drive.google.com",
"bytes": 1803886592,
"totalBytes": 4294967296,
"error": null
}
}
]
}
}
state goes from importing to imported, or to import_failed with import.error saying why. WizCut keeps only the link’s host, never the link itself.
When an import fails, the job carries on. Remove the file and add a working link or an upload in its place:
DELETE /api/jobs/{jobId}/sources/{sourceId}
If the job has a callbackUrl, WizCut also sends a source_import_failed webhook. The reasons (import.error.code):
| Code | Meaning |
|---|---|
URL_NOT_ALLOWED | Not a public https:// link: a private or local address, a non-standard port, or a username and password in it. |
URL_NOT_REACHABLE | The server couldn’t be reached, or answered with an error such as 404. |
NOT_A_FILE | The link opens a web page or a folder, not one file. |
LOGIN_REQUIRED | The link needs a sign-in. Share it with “anyone with the link”. |
FILE_TOO_LARGE | Over the 100 GB per-file limit. |
UNSUPPORTED_MEDIA_FORMAT | Not a supported video or audio format, or damaged. |
IMPORT_TIMEOUT | The download stalled or took too long. |
IMPORT_FAILED | Something went wrong on WizCut’s side. Try again. |
Refused right away (no import starts): 400 with URL_NOT_ALLOWED or NOT_A_FILE for links WizCut can tell are wrong without fetching them (http://, YouTube); 409 with INVALID_STATUS once processing has started, or JOB_FULL at 12 files; 429 with TOO_MANY_IMPORTS when 6 imports are already running in the job, or IMPORT_RATE_LIMITED after 20 imports in an hour — both with a Retry-After header; 503 with IMPORT_UNAVAILABLE if importing isn’t available right now.
Using n8n, Make or Zapier? This is the easy way in: no file handling, no multipart uploads. Create the job with an HTTP Request node (
"sources": []), add each file with another HTTP Request node pointing at its Drive or Dropbox link, and pass a fixedIdempotency-Keyper file (for example the file’s ID in your drive) so a retried node doesn’t import twice. Then wait — pollGET /api/jobs/{jobId}?view=summaryevery minute untiluploads.allUploadedistrue, or react to thesource_import_failedwebhook — and start processing.
Start processing
POST /api/jobs/{jobId}/process
Call this once every file is uploaded. It kicks off the pipeline: audio sync, speaker detection, proxy rendering, camera mapping and cut generation. The request returns immediately — processing happens asynchronously.
Optional body:
{ "diarizeSourceIds": ["source-uuid-3"] }
diarizeSourceIds picks which sources WizCut listens to for speaker detection. They’re your voice audio: the episode’s sound starts from them too (see the audio mix below). If you leave it out, WizCut uses your audio sources, or the first source if there are none. Pick the sources with the cleanest audio of everyone talking — a camera with a muted or distant mic leads to a job with no cuts.
You can also send silence here, in the same shape as on job creation, for example when the pause setting is picked after the job was created. Leave it out to keep what the job was created with. A title works the same way.
Response:
{ "jobId": "uuid", "status": "syncing" }
List jobs
GET /api/jobs
Returns { "jobs": [...] } with your 50 most recent jobs, newest first. Each has id, title, status, thumbnails, created_at and updated_at.
thumbnails has a small JPEG still (320 px wide) per camera, in camera order, as { source_id, url }. It’s [] until the camera previews are made, a few minutes into processing. The URLs are signed for 6 hours and change on every request, so if you cache the images, cache them by source_id. A camera whose still couldn’t be made returns 404, so show a placeholder for it.
Get job status
GET /api/jobs/{jobId}
Response:
{
"job": {
"id": "uuid",
"status": "complete",
"sources": [...],
"tracks": [...],
"turns": [...],
"cuts": [...],
"removed_ranges": [...],
"camera_map": {...},
"output_url": "https://presigned-download-url...",
"error_message": null
},
"sourceUrls": { "source-uuid-1": "https://..." },
"audioUrl": "https://...",
"downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
"shareUrl": "https://wizcut.com/s/PyuMHl16Tpuhwg1Ob4qbEA1BQblecdp8-ayE20sNcSdQ"
}
The job itself sits under job. Signed URLs in the response (output_url, sourceUrls, audioUrl) are freshly signed on every request, so fetch the job again rather than storing them. downloadUrl and shareUrl are the links you can store — see Sharing and download links.
camera_map is WizCut’s proposal for who’s on which camera — see The camera map. It’s null until it has been computed.
Status values:
| Status | Meaning |
|---|---|
created | Job created, waiting for uploads |
uploading | Waiting for files to finish uploading (e.g. after a failed job is reopened) |
syncing | Aligning audio across sources |
diarizing | Detecting speakers |
mapping | Speakers detected. WizCut is still working out who’s on which camera, or a person (or your agent) needs to confirm it |
ready | Cuts generated, ready for review or rendering |
rendering | Final render in progress |
complete | Render done, output_url available |
approved | Human approved the output |
failed | Something went wrong, see error_message |
Status summary
The full job includes every speaker turn and cut, which gets large. If you only need to know where a job is and what to do next — when polling from an agent or an automation, say — ask for the summary:
GET /api/jobs/{jobId}?view=summary
{
"id": "uuid",
"status": "mapping",
"progress": null,
"nextAction": {
"type": "map_speakers",
"url": "https://wizcut.com/jobs/uuid/edit?reviewToken=...",
"message": "Confirm who is on which camera at the review link, or submit the mapping with POST /api/jobs/uuid/tracks."
},
"outputUrl": null,
"downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
"shareUrl": "https://wizcut.com/s/PyuMHl16Tpuhwg1Ob4qbEA1BQblecdp8-ayE20sNcSdQ",
"share": true,
"error": null,
"failedAtStatus": null,
"updatedAt": "2026-10-10T09:42:17.000Z",
"uploads": null,
"syncWarnings": [],
"syncRecheck": { "running": false, "failed": false, "available": false }
}
progress is the render progress from 0 to 1 while the job is rendering, and null otherwise. error and failedAtStatus match the “failed” webhook. While the job takes files (created, uploading), uploads lists every file and where it is — uploading, uploaded, or for files imported from a link importing, imported or import_failed with the reason — and is null after that. nextAction.message is a plain-English hint you can pass on to a person or an agent; build your logic on nextAction.type:
type | Status | What to do | url |
|---|---|---|---|
upload_files | created, uploading; or failed when the upload stopped | Upload the files, then start processing. If the job failed because its upload stopped (nothing arrived for 24 hours), whoever uploaded can continue it in the WizCut app with the same files; what arrived is kept for a week. | null |
wait | syncing, diarizing, rendering | Nothing — WizCut is working. Check again later or wait for the next webhook. | null |
map_speakers | mapping | Confirm who’s on which camera, in the editor or via the API. | Review link, like the “mapping” webhook’s reviewUrl |
review_or_render | ready | Review the cuts, or start the render. | Review link |
download | complete, approved | Download the video. | Freshly signed render URL (also in outputUrl) |
retry | failed | Call POST /api/jobs/{jobId}/retry. | null |
contact_support | failed | Retrying won’t help — for example the file isn’t a supported format. Start a new job, or get in touch. | mailto: link |
When the sources picked for speaker detection turn out to be silent, type is retry but a plain retry would fail the same way: the message says to retry with a diarizeSourceIds list naming a source with clear speech.
Files WizCut couldn’t line up. WizCut lines your files up by their sound. When a file’s sound doesn’t match any other file’s — often an edited or trimmed export instead of the original recording — WizCut still places it as best it can, but the video may be out of lip sync on it. Such a job doesn’t fail: syncWarnings (in the summary and in the full GET /api/jobs/{jobId}) lists each of those files with its sourceId, label, kind and a reason — unverified (placed, but nothing confirmed it), not_placed (it starts at the beginning), no_audio (no sound to line up with) or unreadable (its sound couldn’t be read, so it wasn’t checked at all). A file that did match can still be drifting: the device that recorded it keeps slightly different time, so it slides out of step over the episode by driftMs (milliseconds, start to end). WizCut lines it up in the middle, so the start and the end are each off by about half of that; it isn’t corrected yet. It’s [] when every file matched, and the map_speakers, review_or_render and download messages name the files too. If it isn’t empty, ask a person to check lip sync before publishing.
Checking the sync again. For an unreadable file, POST /api/jobs/{jobId}/sync-recheck reads every file’s sound again and lines them up anew. Only the placement changes; the status, speakers, mapping and cuts stay. It answers 202 at once, and syncRecheck (in the summary and the full job) says where it is: running while it works (a few minutes for big files), failed when the last check didn’t finish, and available when a check can help now (a file is unreadable, the job is mapping, ready or complete, and none is running). Poll until running is false, then read syncWarnings again, and render after that so the video uses the new placement. Refusals: SYNC_RECHECK_NOT_NEEDED and SYNC_RECHECK_RUNNING (both 409). WizCut already runs one such check by itself right after sync whenever a file is unreadable, so you usually only see running turn false; call it yourself when that one didn’t help (failed).
Rendering with files that aren’t lined up. A not_placed, no_audio or unreadable file sits at the start of the episode, so it’s out of lip sync in a video. POST /api/jobs/{jobId}/render refuses with 409 while that’s the case: SYNC_RECHECK_RUNNING while a check is still lining files up (wait a few minutes and try again), FILES_NOT_SYNCED once nothing more will place them, with files listing them. Send {"allowUnsyncedFiles": true} to render anyway, once a person chose that; the video then carries the FILES_NOT_SYNCED render warning. Jobs created with review: false wait for a running check before they render by themselves, and render with the warning if files still aren’t lined up.
Renders that didn’t come out as asked. Rarely, a render finishes but can’t do everything you asked. The usual two: PROGRAM_AUDIO_FAILED, when WizCut couldn’t mix the episode’s audio from your original files, so the video uses the rough mix from speaker detection, without your audio mix or loudness choice; and AV_DRIFT, when part of the video came out a visible amount longer or shorter than planned, so picture and sound may drift out of lip sync. The job is still “complete”, and renderWarnings (in the summary and the full GET /api/jobs/{jobId}) lists what went wrong, each with a code and a message you can show a person. The download message says it too, and the “complete” webhook carries the same list as warnings. It’s [] when the render came out as asked. Rendering again usually fixes it. A third, FILES_NOT_SYNCED, means it was rendered with allowUnsyncedFiles while some files weren’t lined up; render again once they are.
A job can be retried 5 times an hour. If it failed again after that many retries, POST /api/jobs/{jobId}/retry answers 429 with "code": "RETRY_LIMIT", and retryAfterSeconds (also in the Retry-After header) says when you can try again. Other refusals carry a code too: INVALID_STATUS (409, the job isn’t failed), NOT_RETRYABLE (422, it failed at a stage a retry can’t restart) and INVALID_DIARIZE_SOURCES (400, diarizeSourceIds is empty or names sources the job doesn’t have).
New types may be added later, so treat one you don’t know like wait. Unknown view values return the full job.
Delete a job
DELETE /api/jobs/{jobId}
Deletes the job and every file it stored: uploads, proxies, speaker-detection audio and the render. Works in any status; if a stage is still running, its output is cleaned up when it finishes. Deleting a job does not give back used minutes. Returns { "ok": true }, or 404 if the job doesn’t exist or isn’t yours.
Sharing and download links
A finished video comes with three links. Pick the one that fits what you’re doing with it:
| Field | Works for | Who can open it | Use it for |
|---|---|---|---|
outputUrl | A few hours (a signed file URL) | Anyone with it | Handing the file to another service right now |
downloadUrl | As long as the job exists | You: your API key, or a browser signed in to WizCut | Links you keep in your own tools |
shareUrl | As long as the job exists and sharing is on | Anyone with the link | Sending the video to people, or a stable link for a third party |
All three are in GET /api/jobs/{jobId} (full and ?view=summary) and in the “complete” and “approved” webhooks.
downloadUrl is https://wizcut.com/api/jobs/{jobId}/output. Each request redirects (302) to a freshly signed file URL, so the link itself never goes stale. Send your API key with it; in a browser it works when you’re signed in, and otherwise asks you to sign in first. Add ?download=1 to save the file instead of playing it. Before the render is done it answers 409 with "code": "NOT_RENDERED".
curl -L -H "Authorization: Bearer $WIZCUT_API_KEY" \
-o episode.mp4 "https://wizcut.com/api/jobs/$JOB_ID/output"
shareUrl is an unlisted page (https://wizcut.com/s/…) with a player, the title and a download button. Nobody can find it without the link, and it isn’t indexed by search engines. Add /video.mp4 to the link for the raw file. Before the render is done the page says the episode isn’t ready yet, so you can hand the link out early.
Sharing is on by default for new jobs. Turn it off at creation with "share": false, or change it later:
PATCH /api/jobs/{jobId}
{ "share": false }
| Field | Type | Description |
|---|---|---|
share | boolean | Turns the share page on or off. Off and on again brings back the same link. |
resetShareLink | boolean | true replaces the link with a new one. The old link stops working for good — use it when a link ended up somewhere it shouldn’t. |
Response:
{ "jobId": "uuid", "share": true, "shareUrl": "https://wizcut.com/s/..." }
shareUrl is null while sharing is off. You can also turn sharing on and off, copy the link or make a new one in the WizCut editor, under the finished video.
The share page plays the video for anyone who has the link, so treat it like the video itself. If the episode shows other people, make sure they’re fine with it being shared.
Transcript and captions
Episodes with a transcript have "hasTranscript": true in GET /api/jobs/{jobId} (full and ?view=summary). We’re rolling transcripts out gradually, so most episodes don’t have one yet.
GET /api/jobs/{jobId}/transcript?format=srt
| Parameter | Values | Description |
|---|---|---|
format | txt (default), srt, vtt | Plain text with a paragraph per speaker, their name and the time; or captions as SRT or WebVTT. |
timeline | edit (default), render | edit follows the edit as it is now. render matches the last finished video, for captions next to a file you already downloaded. |
download | 1 | Sends Content-Disposition: attachment, named after the job title. |
The answer is the file itself, not JSON. Times follow the edit: what was cut out of the episode is left out, and everything after it moves up, so the captions line up with the video. The X-WizCut-Timeline header says which edit they follow; it says edit when you asked for render but the video was made before WizCut recorded what a render cuts out.
curl -H "Authorization: Bearer $WIZCUT_API_KEY" \
-o episode.srt "https://wizcut.com/api/jobs/$JOB_ID/transcript?format=srt&timeline=render"
Errors: 404 with "code": "NO_TRANSCRIPT" when the episode has none, 409 with "code": "INVALID_STATUS" before it’s cut, and 409 with "code": "NOT_RENDERED" for timeline=render without a finished video.
Webhooks
When you provide a callbackUrl, WizCut sends a JSON POST request when a job reaches one of the statuses below. WizCut tries each delivery up to three times and waits up to 10 seconds for your endpoint to answer.
Every delivery is signed, so you can check it really came from WizCut — see Verifying webhooks. Poll as a fallback, too, in case a delivery gets lost.
“mapping” webhook (a person needs to confirm who’s on which camera):
{
"jobId": "uuid",
"status": "mapping",
"reviewUrl": "https://wizcut.com/jobs/uuid/edit?reviewToken=...",
"speakers": ["SPEAKER_00", "SPEAKER_01"],
"cameraMap": {
"version": 1,
"speakers": ["SPEAKER_00", "SPEAKER_01"],
"unassignedSpeakers": ["SPEAKER_01"],
"droppedSpeakers": [],
"cameras": [
{ "sourceId": "source-uuid-1", "kind": "closeup", "confidence": "high", "speakers": ["SPEAKER_00"], "...": "..." },
{ "sourceId": "source-uuid-2", "kind": "closeup", "confidence": "low", "speakers": ["SPEAKER_01"], "...": "..." }
]
}
}
Send a human to the reviewUrl to map speakers to camera sources and review cuts, or map them via the API. Review links are valid for 72 hours. speakers lists the detected speakers, most talkative first.
cameraMap is WizCut’s proposal, in the same shape as camera_map on the job — see The camera map. It’s left out when there’s no proposal yet.
When this webhook arrives depends on autoMap:
"confident"or"always"— the job waits in “mapping” without a webhook while WizCut works out the cameras, which takes a few minutes once the proxies are built. Then it either maps the cameras itself, and the next webhook you get is “ready”, or it sends “mapping” with the proposal attached. If WizCut can’t compute a proposal (for example because a proxy failed), “mapping” is sent withoutcameraMap— at the latest about 30 minutes after speaker detection."off"— “mapping” is sent right after speaker detection, usually withoutcameraMap. The proposal shows up inGET /api/jobs/{jobId}a few minutes later.
“ready” webhook (speaker mapping submitted — by a person, your code or WizCut — and cuts generated):
{
"jobId": "uuid",
"status": "ready",
"reviewUrl": "https://wizcut.com/jobs/uuid/edit?reviewToken=..."
}
“complete” webhook (render finished):
{
"jobId": "uuid",
"status": "complete",
"outputUrl": "https://presigned-download-url...",
"downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
"shareUrl": "https://wizcut.com/s/..."
}
“approved” webhook (human approved via review UI):
{
"jobId": "uuid",
"status": "approved",
"outputUrl": "https://presigned-download-url...",
"downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
"shareUrl": "https://wizcut.com/s/..."
}
“failed” webhook (the job failed, at any stage):
{
"jobId": "uuid",
"status": "failed",
"error": "description of what went wrong",
"failedAtStatus": "syncing"
}
error is the same message GET /api/jobs/{jobId} returns as error_message, and failedAtStatus names the stage that failed, such as syncing, diarizing or rendering. For most failures in sync, speaker detection and rendering, WizCut first retries once on its own — so when this webhook arrives, the retry didn’t work either.
The exception is a file WizCut can’t read. Every upload is checked before it’s processed, and anything that isn’t an MP4, MOV, M4A, WebM, MKV, WAV, MP3 or AAC file — whatever its extension says — fails the job straight away, without a retry, since the same file would fail the same way. So does a file that’s damaged or cut short. The error names the file by its label, for example "Camera 2" isn't a supported video or audio format, or the file is damaged. Upload a supported file to a new job.
“source_import_failed” webhook (a file added from a link couldn’t be imported):
{
"jobId": "uuid",
"status": "source_import_failed",
"sourceId": "source-uuid-1",
"code": "LOGIN_REQUIRED",
"error": "That link needs a sign-in. Make the file viewable by anyone with the link, or use a direct download link."
}
This one is about a single file, not the job: the job stays where it was. Remove the source with DELETE /api/jobs/{jobId}/sources/{sourceId} and add a working link or an upload. code is one of the import failure codes. Successful imports don’t send a webhook; check the status summary.
The outputUrl in the “complete” and “approved” webhooks is valid for seven days after the render finishes. GET /api/jobs/{jobId} always returns a freshly signed output_url. To keep a link around, store downloadUrl or shareUrl instead (shareUrl is null when sharing is off) — see Sharing and download links.
Verifying webhooks
WizCut signs every webhook following the Standard Webhooks spec, so the official standardwebhooks libraries can check them for you. Each delivery carries three headers:
| Header | Value |
|---|---|
webhook-id | Unique per event, like msg_2b6f0c…. A retry of the same event carries the same id, so use it to skip duplicates. |
webhook-timestamp | When this attempt was sent, in Unix seconds. |
webhook-signature | One or more signatures, separated by spaces, each v1,<base64>. |
Your signing secret is on the settings page, under “Webhook signing secret”. It looks like whsec_…, and one secret covers all your jobs.
Each signature is the base64-encoded HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}, keyed with your secret’s bytes: the part after whsec_, base64-decoded. To check a delivery:
- Compute the signature over the raw request body, exactly as received — not over JSON you’ve parsed and serialized again.
- Accept the delivery if any
v1signature in the header matches. Compare in constant time. - Reject timestamps more than 5 minutes away from your clock, so a captured delivery can’t be replayed later.
- Keep track of
webhook-ids you’ve handled, and skip repeats.
With the standardwebhooks package (Node):
import express from "express";
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.WIZCUT_WEBHOOK_SECRET); // "whsec_..."
const app = express();
// express.raw: the signature covers the body exactly as sent
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
let event;
try {
// Checks the signature and the 5-minute timestamp window; throws if either fails
event = wh.verify(req.body.toString("utf8"), req.headers);
} catch {
return res.status(400).send("Invalid signature");
}
// event.jobId, event.status, ...
res.sendStatus(200);
});
With plain crypto (Node):
import crypto from "node:crypto";
function verifyWizCutWebhook(rawBody, headers, secret) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 5 * 60) return false;
const key = Buffer.from(secret.slice("whsec_".length), "base64");
const expected = crypto
.createHmac("sha256", key)
.update(`${id}.${timestamp}.${rawBody}`)
.digest();
return signatures.split(" ").some((entry) => {
const [version, signature] = entry.split(",");
if (version !== "v1" || !signature) return false;
const received = Buffer.from(signature, "base64");
return (
received.length === expected.length &&
crypto.timingSafeEqual(received, expected)
);
});
}
Python:
import base64
import hashlib
import hmac
import time
def verify_wizcut_webhook(raw_body: bytes, headers, secret: str) -> bool:
msg_id = headers.get("webhook-id")
timestamp = headers.get("webhook-timestamp")
signatures = headers.get("webhook-signature")
if not (msg_id and timestamp and signatures):
return False
if abs(time.time() - int(timestamp)) > 5 * 60:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{timestamp}.".encode() + raw_body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
for entry in signatures.split(" "):
version, _, signature = entry.partition(",")
if version == "v1" and hmac.compare_digest(signature, expected):
return True
return False
Rolling your secret. “Roll secret” on the settings page creates a new secret. The old one keeps working for 24 hours: during that time every delivery carries two signatures, the new one first, so your server verifies whichever secret it has. Swap in the new secret within those 24 hours. If you roll again before they’re up, the oldest secret stops right away — only the current one and the one just before it ever sign.
If WizCut ever can’t sign a delivery, it sends it anyway, without the signature headers, rather than dropping it. Whether to accept an unsigned delivery is up to you; if you reject it, fetch the job with GET /api/jobs/{jobId} to see what changed.
Speaker mapping and review (human-in-the-loop)
After speaker detection, the job enters “mapping” status. The detected speakers have to be mapped to camera sources — speaker detection identifies when someone speaks but not which camera they’re on.
WizCut tries to work that out for you. People move when they talk — they gesture, nod, lean in — so WizCut compares each speaker’s talking with the movement on each camera and proposes who’s on which one. How much it decides on its own is up to you, with autoMap.
When a person is needed, WizCut sends the “mapping” webhook. It includes a reviewUrl — a signed link to the WizCut editor. Send a human there. In the editor, they:
- Check which speaker is on which camera (the cameras WizCut is sure about are already selected)
- Preview and edit the auto-generated cuts
- Click “Render” when satisfied (if
review: true, the default) - Optionally click “Approve” after reviewing the rendered output
With review: false, rendering starts automatically as soon as the speaker mapping is submitted — the human doesn’t get to review cuts before rendering.
Automatic camera mapping
Set autoMap when you create the job:
| Mode | What WizCut does | Pick it when |
|---|---|---|
"off" | Never maps the cameras on its own. Sends “mapping” right after speaker detection; the proposal shows up on the job a few minutes later for a person or your agent to use. | A person always reviews the mapping anyway. |
"confident" | Default. Maps the cameras itself when it’s sure it has found a close-up of every speaker, then moves on to “ready”. Otherwise sends “mapping” with the proposal attached. A wide or two-shot is used in the edit but never counts as a speaker’s own camera. | Most integrations. You only hear from WizCut when it needs help. |
"always" | Doesn’t wait for a person. Uses the answers it’s sure about, then its likely answers, and places anyone left over on the remaining cameras by talk time. Only if it can’t compute a proposal at all (for example because a proxy failed) does it send “mapping”. | Fully unattended pipelines that would rather get a guessed edit than a stalled job. |
“Sure about every speaker” means: everyone with at least a minute of speech is on a camera WizCut answered with high confidence. Cameras it isn’t sure about get no speakers, so the edit doesn’t cut to them — fix that in the editor if you want them used.
Be ready for “confident” to ask a person fairly often. It holds back on footage where the movement doesn’t follow one speaker: TV studios with switched feeds, events, handheld or operated cameras. It also needs about 20 minutes of conversation to be sure, so short clips usually end up in “mapping”. In our tests so far, WizCut hasn’t put a speaker on the wrong camera when it said it was sure — but the sample is still small.
Combined with review: false, "confident" and "always" mean a job can render without anyone looking at it. That’s the point for unattended pipelines; if you want a person to see every edit, keep review: true.
The camera map
The proposal is on the job as camera_map (and in the “mapping” webhook as cameraMap). It’s null until computed — a few minutes after the proxies are built. Here’s one for a two-person show with a close-up of each person and a two-shot:
{
"version": 1,
"computedAt": "2026-10-01T09:42:17.000Z",
"speakers": ["SPEAKER_00", "SPEAKER_01"],
"unassignedSpeakers": [],
"droppedSpeakers": ["SPEAKER_02"],
"cameras": [
{
"sourceId": "source-uuid-1",
"kind": "closeup",
"confidence": "high",
"speakers": ["SPEAKER_00"],
"z": { "SPEAKER_00": 11.5, "SPEAKER_01": 0.9 },
"lagErrorS": { "SPEAKER_00": 0.1, "SPEAKER_01": 41.6 }
},
{
"sourceId": "source-uuid-2",
"kind": "closeup",
"confidence": "high",
"speakers": ["SPEAKER_01"],
"z": { "SPEAKER_01": 12.4, "SPEAKER_00": 1.3 },
"lagErrorS": { "SPEAKER_01": 0.2, "SPEAKER_00": 63.0 }
},
{
"sourceId": "source-uuid-3",
"kind": "twoshot",
"confidence": "high",
"speakers": ["SPEAKER_01", "SPEAKER_00"],
"positions": { "left": "SPEAKER_01", "right": "SPEAKER_00" },
"z": { "SPEAKER_00": 6.8, "SPEAKER_01": 5.2 },
"lagErrorS": { "SPEAKER_00": 0.3, "SPEAKER_01": 0.4 }
}
]
}
Per camera:
| Field | Description |
|---|---|
sourceId | One of the job’s video sources. |
kind | What the camera shows: closeup (one person), twoshot (two people side by side), wide (three people), multi (several people, one after another — usually an operated or switched camera) or unknown. |
confidence | high (WizCut is sure), low (a likely answer, not certain) or none (no answer). |
speakers | Who the camera shows. Empty when confidence is none. For two-shots and wides, from left to right. |
positions | Two-shots and wides only: who’s on the left, middle and right of the frame. |
reason | Set to no_motion when a camera couldn’t be analysed at all. |
z, lagErrorS | Diagnostic numbers per speaker: how strongly the camera’s movement follows that person’s talking, and how many seconds off the best match landed. Handy for debugging, not something to build on. |
Top level:
| Field | Description |
|---|---|
speakers | The speakers WizCut judged: everyone with at least a minute of speech. |
unassignedSpeakers | Judged speakers who aren’t on any high camera. If this isn’t empty, “confident” leaves the decision to a person. |
droppedSpeakers | Speakers with too little speech to judge — usually a stray label or a short interjection. WizCut doesn’t place them on a camera. |
To accept the proposal as it is, turn each camera you trust into a track — its sourceId and speakers — and submit it.
Map speakers via the API
If you already know who sits in front of which camera, or your agent has checked the proposal, submit the mapping yourself while the job is in “mapping” status:
POST /api/jobs/{jobId}/tracks
{
"tracks": [
{ "sourceId": "source-uuid-1", "speakers": ["SPEAKER_00"] },
{ "sourceId": "source-uuid-2", "speakers": ["SPEAKER_01"] }
]
}
Use the speaker names from the “mapping” webhook (or the turns in GET /api/jobs/{jobId}) and your video source IDs. A camera can show more than one speaker. WizCut then generates the cuts, moves the job to “ready”, sends the “ready” webhook, and — with review: false — starts the render. The response contains the new cuts.
Every sourceId has to be one of the job’s video sources; anything else gets a 400 with "code": "UNKNOWN_SOURCE". You can submit while WizCut is still working out the cameras — whichever comes first wins. If the mapping was already submitted, for example automatically, you get a 409 with "code": "INVALID_STATUS".
Advanced: correcting a mapping after cuts exist. Once the job is “ready” or “complete”, the same endpoint can still change the mapping, but it no longer generates cuts for you: send the corrected cuts along with tracks (and optionally removedRanges), or you get a 400 with "code": "CUTS_REQUIRED". WizCut saves both together, so a later recut uses the corrected mapping. Any stretch of a cut that falls outside its camera’s file (one that starts late or stops early) moves to a camera that has footage then; the response’s cuts are what was saved. It doesn’t send a webhook or start a render — trigger one if you need a new output. The WizCut editor does all of this for you when someone fixes a mapping there.
Silence removal
WizCut can automatically shorten or remove long pauses before generating cuts. This happens first, so camera switching is decided on the tightened conversation — you never get a cut to a camera that immediately loses most of its screen time to a removed pause.
Enable it with the silence field when creating a job:
{ "silence": { "mode": "tighten" } }
Modes:
| Mode | Behavior |
|---|---|
off | Keep all pauses as recorded (default when silence is omitted). |
tighten | Shorten long pauses to a natural beat (~0.7s). Recommended — keeps the conversation feeling human. |
remove | Cut long pauses out almost entirely, leaving just enough padding to avoid clipped words. |
Optional tuning knobs (defaults work well for most recordings):
| Field | Default | Range | Description |
|---|---|---|---|
minPauseSec | 1.5 | 0.3–10 | Only pauses longer than this are touched. |
keepPauseSec | 0.7 | 0–3 | The beat left in place of a tightened pause (tighten mode only). |
paddingSec | 0.25 | 0–1 | Safety margin kept around speech at every removed range. |
Detection is conservative: a pause is only removed where speaker detection and an audio energy analysis both agree it’s quiet, so laughter and other non-speech moments survive.
The job object (GET /api/jobs/{jobId}) includes removed_ranges — the removed spans in source time as { startMs, endMs } — alongside cuts. The final render skips these ranges; the review editor shows them as restorable hatched sections.
Change it after processing with the recut endpoint:
POST /api/jobs/{jobId}/recut
{ "silence": { "mode": "remove", "minPauseSec": 1.0 } }
Recut regenerates cuts and removed ranges from the already-detected speakers — no reprocessing, so it returns immediately with the new cuts, removedRanges, and savedMs (how much shorter the output gets). Pass { "mode": "off" } to turn silence removal off again; omit silence entirely to keep the job’s stored setting. The cut pace works the same way: add "presetId" ("relaxed", "balanced" or "dynamic") to change it, or leave it out to keep the job’s current pace.
Billing note: usage is measured in input minutes (the footage you upload), so silence removal doesn’t change what a job costs — it just makes the output tighter.
Advanced: programmatic cut control
For fully automated pipelines that skip the UI entirely, let WizCut map the cameras or map speakers via the API, then manage cuts and rendering yourself. These endpoints work while the job is “ready” or “complete”:
Update cuts:
PATCH /api/jobs/{jobId}/cuts
{
"cuts": [
{ "startMs": 0, "endMs": 5000, "sourceId": "source-uuid-1" },
{ "startMs": 5000, "endMs": 12000, "sourceId": "source-uuid-2" }
]
}
The same endpoint also accepts removedRanges (array of { startMs, endMs }) to directly edit the silence-removal spans — for example to restore a pause the automatic pass removed. You can send cuts, removedRanges, or both.
Every cut has to name one of the job’s video sources (its cameras). An audio file has no picture, so a cut on one gets a 422 with "code": "CUT_NOT_ON_CAMERA" and the offending ids in sourceIds. Audio files still go into the episode’s sound.
Trigger render:
POST /api/jobs/{jobId}/render
Works from “ready”, or from “complete” to render again after editing cuts. Returns { "jobId": "uuid", "status": "rendering" }, or a 409 with "code": "NO_CUTS" if the job has no cuts to render, or "code": "NO_CAMERA" if only audio files are left.
Approve output:
POST /api/jobs/{jobId}/approve
Only works once the job is “complete”. Moves it to “approved” and sends the “approved” webhook.
Audio
WizCut mixes the soundtrack from your original audio files at full quality. By default it uses the files you picked for speaker detection, as recorded. Two things change that.
Loudness. Pass loudness when you start the render:
POST /api/jobs/{jobId}/render
{ "loudness": "podcast" }
"original" leaves the level as recorded (the default), "podcast" brings the episode to −16 LUFS, "youtube" to −14 LUFS, both with peaks kept under −1 dBTP. It’s one gain for the whole episode, so quiet and loud passages keep their balance. Leave it out to keep the job’s last choice. To set the choice without rendering, send { "loudness": "podcast" } to PUT /api/jobs/{jobId}/audio-mix (below); the editor does that as soon as you pick a level. The job’s output_loudness says how loud the last render came out.
The mix. Read it with:
GET /api/jobs/{jobId}/audio-mix
{
"jobId": "uuid",
"audioMix": {
"balance": true,
"duck": { "enabled": true, "depthDb": -12, "fadeMs": 150, "padMs": 250 },
"tracks": {}
},
"tracks": [
{
"sourceId": "source-uuid-3",
"label": "guest-mic.wav",
"hasAudio": true,
"inMix": true,
"loudnessLufs": -26.9,
"balanceDb": 5.5,
"levelDb": 0,
"gainDb": 5.5,
"speaker": "SPEAKER_01",
"speakerChosen": false,
"centered": false,
"role": { "kind": "own", "speakers": ["SPEAKER_01"], "speechToNoiseDb": 31 }
}
],
"speakers": [{ "label": "SPEAKER_01", "name": "Maya" }],
"canBalance": true,
"canDuck": true,
"loudness": { "target": "original", "lastRender": null },
"usingDefault": false,
"defaultMix": { "sourceIds": ["source-uuid-3"], "duck": false, "reason": "picks" }
}
tracks shows each file as the next render plays it: whether it’s in the mix and its final gainDb (balanceDb from Balance voices plus your own levelDb). speaker is whose mic it is, which WizCut works out from the levels after speaker detection. centered is true when a file’s left and right carried different sound (a mic on one side only, or one on each side): WizCut plays both channels on both sides, so nobody ends up in one ear. It’s set automatically during processing.
role is what the file hears, worked out from its levels after speaker detection: own (one person’s mic, 6 dB or more louder for them than for anyone else), group (a few people at about the same level) or everyone (a room mic or a wide camera). A speechToNoiseDb under 15 sounds noisy. Until you set anything (usingDefault), the mix is defaultMix, chosen by role: everyone’s own mic, one per person, from any of your files, with mics turned down between turns (ownMics); else, from your diarizeSourceIds, when every pick hears everyone, the cleanest one on its own (cleanest); else your picks as they are (picks). A track you leave out of tracks in a PUT goes back to this default.
Change it with:
PUT /api/jobs/{jobId}/audio-mix
{
"balance": true,
"duck": { "enabled": true },
"tracks": {
"source-uuid-3": { "gainDb": 2, "muted": false },
"source-uuid-4": { "gainDb": 0, "muted": false, "speaker": null }
}
}
Only the fields you send change. duck is merged field by field; tracks replaces the whole per-track map, so send every track you want set.
| Field | What it does |
|---|---|
balance | Balance voices: raises quieter mics to the loudest one’s level (one gain per track, at most +18 dB). |
duck.enabled | Turns each mic down while its person isn’t talking, so the other voices it picks up don’t make the mix sound hollow. depthDb (−40 to −3, default −12), fadeMs (20–1000, default 150) and padMs (0–1000, default 250, how early it opens before its person speaks) fine-tune it. |
tracks.<sourceId>.gainDb | Your level for that file, −24 to +12 dB, on top of Balance voices. |
tracks.<sourceId>.muted | true leaves the file out of the soundtrack. |
tracks.<sourceId>.speaker | Whose mic it is: a speaker label, or null for nobody’s (a room mic or camera, never turned down). Leave it out to use WizCut’s guess. |
Works in any status. The mix applies to the next render, so call the render endpoint again to hear it in the video. A malformed field, or a speaker that isn’t one of the episode’s, returns 400 with "code": "INVALID_AUDIO_MIX".
Error responses
All endpoints return errors in this format:
{ "error": "Description of what went wrong" }
Some errors also carry a machine-readable code:
| Code | HTTP | Meaning |
|---|---|---|
TRACKS_ON_CREATE | 400 | POST /api/jobs got a speaker mapping. Leave tracks out and use autoMap, or set the mapping later. |
FILE_TOO_LARGE | 400 | A file is over the size limit — declared in fileSize, or found once uploaded. maxBytes gives the limit. |
INVALID_FILE_SIZE | 400 | fileSize isn’t a whole number of bytes. |
NOT_A_MEDIA_FILE | 422 | A file can’t be a recording: a macOS metadata file (its name starts with ._) or a fileSize under 32 KB. fileName and reason say which and why. Send the camera and audio files themselves. |
FILE_SIZE_MISMATCH | 400 | The uploaded file is much smaller or larger than its fileSize. Upload it again. |
UNKNOWN_SOURCE | 400 | A track names a sourceId that isn’t one of the job’s video sources. |
CUTS_REQUIRED | 400 | Changing the mapping after cuts exist needs the updated cuts too. |
CUT_NOT_ON_CAMERA | 422 | A cut names something that isn’t one of the job’s video sources, such as an audio file (no picture). sourceIds lists them. |
NOT_ENOUGH_VIDEOS | 400 | The job needs at least two video sources to be processed. |
EMPTY_MAPPING | 400 | The speaker mapping puts nobody on any camera. Assign at least one speaker. |
INVALID_IDEMPOTENCY_KEY | 400 | The Idempotency-Key header isn’t 1–255 printable ASCII characters. |
URL_NOT_ALLOWED | 400 | Import from a link: not a public https:// link. |
NOT_A_FILE | 400 | Import from a link: a YouTube or Vimeo page, not a file. |
QUOTA_EXCEEDED | 403 | You’ve used up your minutes. |
SOURCES_PENDING | 409 | /process was called while some files are still uploading or importing, or a file’s import failed. pendingSourceIds lists them (importingSourceIds and importFailedSourceIds say which are imports); finish those uploads, and remove files whose import failed. |
INVALID_STATUS | 409 | The job isn’t in a status that allows this — for example, its mapping was already submitted. |
NO_CUTS | 409 | There are no cuts to render. |
NO_CAMERA | 409 | The job has no video source left, only audio files, so there’s no picture to render. |
SOURCES_DELETED | 409 | The job’s original files were deleted, because originals are only kept for a limited time, depending on the plan. Open it in the editor and upload the same files again, then render. |
NOT_RENDERED | 409 | There’s no finished video yet — downloadUrl works once the job is complete or approved. |
IDEMPOTENCY_IN_PROGRESS | 409 | A request with the same Idempotency-Key is still being processed. Retry in a moment. |
IDEMPOTENCY_KEY_REUSED | 409 | The job (or the imported file) this Idempotency-Key created has been deleted. Use a new key. |
JOB_FULL | 409 | Import from a link: the job already has 12 files. |
IDEMPOTENCY_KEY_MISMATCH | 422 | This Idempotency-Key was already used with a different request body. |
TOO_MANY_IMPORTS | 429 | Import from a link: 6 imports are already running in this job. Wait for Retry-After. |
IMPORT_RATE_LIMITED | 429 | Import from a link: 20 imports in the last hour. Wait for Retry-After, or upload the files. |
IMPORT_UNAVAILABLE | 503 | Import from a link isn’t available right now. Upload the file instead. |
Common HTTP status codes:
| Code | Meaning |
|---|---|
| 400 | Invalid request (e.g. fewer than two video sources when processing) |
| 401 | Missing or invalid API key |
| 403 | Quota exceeded, or the upload belongs to another account |
| 404 | Job not found or not owned by you |
| 409 | Invalid status transition (e.g. rendering a job that isn’t ready), or a request with the same Idempotency-Key still running |
| 422 | An Idempotency-Key reused with a different request body |
| 429 | Too many imports from links at once, or in the last hour |
| 500 | Server error |
| 502 | A processing service rejected the job or failed to start |
| 503 | Service not available |
Complete flow
Here’s the full happy path for an AI agent or automation:
# 1. Create a job with two cameras (files up to 5 GB each — pass
# fileSize to get multipart uploads for larger files, up to 100 GB)
JOB=$(curl -s -X POST https://wizcut.com/api/jobs \
-H "Authorization: Bearer wc_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"sources": [
{"label": "Camera 1", "kind": "video"},
{"label": "Camera 2", "kind": "video"}
],
"callbackUrl": "https://your-server.com/webhook"
}')
JOB_ID=$(echo $JOB | jq -r '.jobId')
# 2. Upload video files to the presigned URLs
curl -X PUT -T camera1.mp4 "$(echo $JOB | jq -r '.uploads | to_entries[0].value.url')"
curl -X PUT -T camera2.mp4 "$(echo $JOB | jq -r '.uploads | to_entries[1].value.url')"
# 3. Start processing
curl -s -X POST "https://wizcut.com/api/jobs/$JOB_ID/process" \
-H "Authorization: Bearer wc_live_your_key"
# 4. Wait for the next webhook. With the default autoMap ("confident"):
# - { status: "ready", reviewUrl: "..." } — WizCut mapped the cameras itself
# - { status: "mapping", reviewUrl: "...", speakers: [...], cameraMap: {...} }
# — it wasn't sure. Send a human to reviewUrl to confirm the cameras
# (or POST the mapping to /api/jobs/$JOB_ID/tracks yourself)
# 5. Human reviews and edits cuts → clicks Render in the editor
# Wait for webhook: { status: "complete", outputUrl: "..." }
# 6. Download the rendered video from outputUrl
Fully unattended (autoMap: "always", review: false):
# Same as above, but add "autoMap": "always" and "review": false to step 1
# WizCut maps the cameras itself, even when it isn't sure,
# and starts rendering right after — no person involved
# You'll get: { status: "ready", ... }, then { status: "complete", outputUrl: "..." }
Integrations
Prefer no-code? You can drive the WizCut API from automation platforms without writing any of the requests above.
n8n
We maintain an official n8n integration — the verified community node @wizcut/n8n-nodes-wizcut. Install it from Settings → Community Nodes in n8n (it’s verified, so it’s also available on n8n Cloud).
It ships two nodes:
- WizCut — actions for Create Job, Get Job, Start Processing, Start Render, and Approve.
- WizCut Trigger — a webhook trigger that starts your workflow whenever a job changes status (mapping, ready, complete, approved).
The nodes don’t import from links yet: for files already in a cloud drive, add them with an HTTP Request node as described in Import files from a link.
Point the trigger’s webhook URL at your job’s callbackUrl and you get a fully event-driven pipeline — for example, ping Slack when WizCut needs someone to confirm who’s on which camera, auto-start the render when cuts are ready, and post the download link when the episode is done. Both nodes also work as tools for n8n AI agents.
Want a head start? Grab the ready-made template: Notify and manage podcast edit status with WizCut and Slack.
More platforms
Make.com and Zapier integrations are on the roadmap. Building on a different platform, or want a workflow template for your exact setup? Reach out to WizCut support — feature requests are welcome.