WizCut API
Multicam-Podcast-Schnitt programmatisch steuern: Dateien hochladen, verarbeiten und rendern mit der WizCut API.
Die WizCut API ermöglicht die vollständige Automatisierung des Multicam-Podcast-Schnitts. Du lädst deine Kameraaufnahmen hoch, WizCut erkennt die Sprecher und generiert Schnitte, du kannst diese optional in einem gehosteten Editor prüfen – und erhältst anschließend das fertige Video per Webhook.
Authentifizierung
Erstell einen API-Key unter wizcut.com/settings und füge ihn in jede Anfrage ein:
Authorization: Bearer wc_live_your_key_here
Keys lassen sich jederzeit auf der Einstellungsseite widerrufen.
Job anlegen
POST /api/jobs
{
"sources": [
{ "label": "Camera 1", "kind": "video", "ext": "mp4" },
{ "label": "Camera 2", "kind": "video", "ext": "mp4" }
],
"tracks": [
{ "sourceId": "auto", "speakers": [] }
],
"callbackUrl": "https://your-server.com/webhook",
"review": true,
"silence": { "mode": "tighten" }
}
Felder:
| Feld | Typ | Beschreibung |
|---|---|---|
sources | array | Kamerawinkel oder Audiodateien. Jeder Eintrag hat ein label, optionales kind ("video" oder "audio", Standard: "video") und optionales ext (Standard: "mp4"). |
tracks | array | Zuordnung von Sprechern zu Quellen. Mit leerem speakers-Array [] weist WizCut die Sprecher nach der Analyse automatisch zu. |
callbackUrl | string | URL, an die Webhook-Benachrichtigungen bei Statusänderungen gesendet werden. |
review | boolean | Standard: true. Bei true pausiert der Job im Status „ready”, damit ein Mensch die Schnitte vor dem Render prüfen kann. Bei false startet das Rendering automatisch, sobald das Speaker-Mapping abgeschlossen ist. |
silence | object | Optional. Automatisches Entfernen von Pausen, siehe Pausen entfernen. Ohne Angabe ist die Funktion deaktiviert. |
Antwort:
{
"jobId": "uuid",
"uploadUrls": {
"source-uuid-1": "https://presigned-upload-url...",
"source-uuid-2": "https://presigned-upload-url..."
}
}
Dateien hochladen
Lade deine Videodateien per PUT-Anfrage an die jeweiligen presigned URLs aus der Antwort. Ein Auth-Header ist nicht erforderlich – die URLs sind selbst-authentifizierend.
curl -X PUT -T camera1.mp4 "https://presigned-upload-url..."
curl -X PUT -T camera2.mp4 "https://presigned-upload-url..."
Verarbeitung starten
POST /api/jobs/{jobId}/process
Dieser Aufruf startet die Pipeline: Audio-Sync, Sprechererkennung, Schnittgenerierung und Proxy-Rendering. Die Anfrage kehrt sofort zurück – die Verarbeitung läuft asynchron.
Antwort:
{ "jobId": "uuid", "status": "syncing" }
Job-Status abfragen
GET /api/jobs/{jobId}
Gibt das vollständige Job-Objekt zurück, einschließlich aktuellem Status, Quellen, Turns und Schnitten.
Statuswerte:
| Status | Bedeutung |
|---|---|
created | Job angelegt, wartet auf Uploads |
syncing | Audio-Synchronisation zwischen den Quellen |
diarizing | Sprechererkennung läuft |
mapping | Speaker-to-Source-Zuordnung erforderlich |
ready | Schnitte generiert, bereit zur Prüfung oder zum Rendering |
rendering | Finales Rendering läuft |
complete | Rendering abgeschlossen, output_url verfügbar |
approved | Ausgabe von einem Menschen bestätigt |
failed | Fehler aufgetreten, Details in error_message |
Webhooks
Wenn du eine callbackUrl angibst, sendet WizCut POST-Anfragen bei Statusübergängen:
Webhook „mapping” (Sprecher erkannt, Zuordnung erforderlich):
{
"jobId": "uuid",
"status": "mapping",
"reviewUrl": "https://wizcut.com/jobs/uuid/edit?reviewToken=..."
}
Schick einen Menschen zur reviewUrl, um Sprecher den Kameraquellen zuzuordnen und die Schnitte zu prüfen.
Webhook „ready” (Speaker-Mapping abgeschlossen, Schnitte generiert):
{
"jobId": "uuid",
"status": "ready",
"reviewUrl": "https://wizcut.com/jobs/uuid/edit?reviewToken=..."
}
Webhook „complete” (Rendering abgeschlossen):
{
"jobId": "uuid",
"status": "complete",
"outputUrl": "https://presigned-download-url..."
}
Webhook „approved” (Mensch hat die Ausgabe über das Review-UI bestätigt):
{
"jobId": "uuid",
"status": "approved",
"outputUrl": "https://presigned-download-url..."
}
Webhook „failed”:
{
"jobId": "uuid",
"status": "failed",
"error": "description of what went wrong"
}
Speaker-Mapping und Review (Human-in-the-loop)
Nach der Sprechererkennung wechselt der Job in den Status „mapping”. Ein Mensch muss die erkannten Sprecher den Kameraquellen zuordnen, denn die Sprechererkennung bestimmt zwar, wann jemand spricht, aber nicht, auf welcher Kamera die Person zu sehen ist.
Der Webhook „mapping” enthält eine reviewUrl – ein signierter Link zum WizCut-Editor. Schick einen Menschen dorthin. Im Editor nimmt er folgende Schritte vor:
- Jeden erkannten Sprecher einer Kameraquelle zuordnen
- Die automatisch generierten Schnitte in der Vorschau prüfen und bearbeiten
- Auf „Render” klicken, wenn alles stimmt (bei
review: true, dem Standard) - Optional auf „Approve” klicken, nachdem die gerenderte Ausgabe geprüft wurde
Bei review: false startet das Rendering automatisch, sobald das Speaker-Mapping abgeschickt wird – eine Prüfung der Schnitte vor dem Render entfällt.
Pausen entfernen
WizCut kann lange Pausen automatisch straffen oder entfernen, bevor die Schnitte generiert werden. Das passiert zuerst, damit die Kamerawechsel auf dem bereits gestrafften Gespräch entschieden werden. So bekommst du nie einen Schnitt auf eine Kamera, die sofort den Großteil ihrer Bildzeit an eine entfernte Pause verliert.
Aktivieren lässt sich das über das silence-Feld beim Anlegen eines Jobs:
{ "silence": { "mode": "tighten" } }
Modi:
| Modus | Verhalten |
|---|---|
off | Alle Pausen bleiben wie aufgenommen erhalten (Standard, wenn silence weggelassen wird). |
tighten | Lange Pausen werden auf einen natürlichen Beat gekürzt (~0,7 s). Empfohlen: Das Gespräch bleibt menschlich. |
remove | Lange Pausen werden fast vollständig herausgeschnitten, nur so viel Padding bleibt, dass keine Wörter abgeschnitten werden. |
Optionale Feinjustierung (die Standardwerte funktionieren für die meisten Aufnahmen gut):
| Feld | Standard | Bereich | Beschreibung |
|---|---|---|---|
minPauseSec | 1.5 | 0.3–10 | Nur Pausen, die länger sind, werden bearbeitet. |
keepPauseSec | 0.7 | 0–3 | Der Beat, der anstelle einer gestrafften Pause stehen bleibt (nur im Modus tighten). |
paddingSec | 0.25 | 0–1 | Sicherheitsabstand, der bei jedem entfernten Bereich um die Sprache herum erhalten bleibt. |
Die Erkennung arbeitet konservativ: Eine Pause wird nur entfernt, wenn sowohl die Sprechererkennung als auch eine Audio-Energieanalyse übereinstimmend „still” ergeben. Lachen und andere nicht-sprachliche Momente bleiben dadurch erhalten.
Das Job-Objekt (GET /api/jobs/{jobId}) enthält neben cuts auch removed_ranges: die entfernten Bereiche in der Quellzeit als { startMs, endMs }. Das finale Rendering überspringt diese Bereiche, im Review-Editor erscheinen sie als wiederherstellbare, schraffierte Abschnitte.
Nachträglich ändern lässt sich das über den Recut-Endpunkt:
POST /api/jobs/{jobId}/recut
{ "silence": { "mode": "remove", "minPauseSec": 1.0 } }
Recut generiert Schnitte und entfernte Bereiche aus den bereits erkannten Sprechern neu, ohne erneute Verarbeitung. Die Antwort kommt daher sofort zurück, mit den neuen Werten für cuts, removedRanges und savedMs (wie viel kürzer die Ausgabe dadurch wird). Übergib { "mode": "off" }, um die Stille-Entfernung wieder zu deaktivieren. Lässt du silence ganz weg, bleibt die gespeicherte Einstellung des Jobs erhalten.
Hinweis zur Abrechnung: Die Nutzung wird in Input-Minuten gemessen (dem hochgeladenen Material). Die Stille-Entfernung ändert also nichts an den Kosten eines Jobs, sie macht nur die Ausgabe kompakter.
Erweitert: Schnitte programmatisch steuern
Für vollständig automatisierte Pipelines, die das UI komplett umgehen, lassen sich Schnitte und Rendering über die API steuern:
Schnitte aktualisieren:
PATCH /api/jobs/{jobId}/cuts
{
"cuts": [
{ "startMs": 0, "endMs": 5000, "sourceId": "source-uuid-1" },
{ "startMs": 5000, "endMs": 12000, "sourceId": "source-uuid-2" }
]
}
Derselbe Endpunkt akzeptiert außerdem removedRanges (ein Array aus { startMs, endMs }), um die Stille-Entfernungs-Bereiche direkt zu bearbeiten, zum Beispiel um eine Pause wiederherzustellen, die der automatische Durchlauf entfernt hat. Du kannst cuts, removedRanges oder beides senden.
Render auslösen:
POST /api/jobs/{jobId}/render
Ausgabe bestätigen:
POST /api/jobs/{jobId}/approve
Fehlerantworten
Alle Endpunkte liefern Fehler in diesem Format:
{ "error": "Description of what went wrong" }
Häufige HTTP-Statuscodes:
| Code | Bedeutung |
|---|---|
| 401 | Fehlender oder ungültiger API-Key |
| 403 | Kontingent überschritten |
| 404 | Job nicht gefunden oder nicht in deinem Besitz |
| 409 | Ungültiger Statusübergang (z. B. Rendering eines Jobs, der noch nicht „ready” ist) |
| 500 | Serverfehler |
| 503 | Dienst nicht verfügbar |
Vollständiger Ablauf
Der komplette Happy-Path für einen KI-Agenten oder eine Automatisierung:
# 1. Job mit zwei Kameras anlegen
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. Videodateien an die presigned URLs hochladen
curl -X PUT -T camera1.mp4 "$(echo $JOB | jq -r '.uploadUrls | to_entries[0].value')"
curl -X PUT -T camera2.mp4 "$(echo $JOB | jq -r '.uploadUrls | to_entries[1].value')"
# 3. Verarbeitung starten
curl -s -X POST "https://wizcut.com/api/jobs/$JOB_ID/process" \
-H "Authorization: Bearer wc_live_your_key"
# 4. Auf Webhook warten: { status: "mapping", reviewUrl: "..." }
# Einen Menschen zur reviewUrl schicken, um Sprecher zuzuordnen und Schnitte zu prüfen
# 5. Mensch ordnet Sprecher zu → bearbeitet Schnitte → klickt im Editor auf Render
# Auf Webhook warten: { status: "complete", outputUrl: "..." }
# 6. Fertig gerendetes Video von outputUrl herunterladen
Mit automatischem Render nach dem Mapping (review: false):
# Wie oben, aber "review": false in Schritt 1 ergänzen
# Der Mensch ordnet weiterhin Sprecher unter der reviewUrl zu (Schritt 4)
# Das Rendering startet jedoch automatisch nach dem Mapping – keine Schnittprüfung
# Ergebnis: { status: "complete", outputUrl: "..." }
Integrationen
Lieber ohne Code? Die WizCut API lässt sich auch über Automatisierungsplattformen steuern, ohne dass du die oben beschriebenen Anfragen selbst schreiben musst.
n8n
Wir pflegen eine offizielle n8n-Integration mit dem verifizierten Community-Node @wizcut/n8n-nodes-wizcut. Installieren lässt er sich in n8n unter Settings → Community Nodes. Da er verifiziert ist, steht er auch in n8n Cloud zur Verfügung.
Der Node kommt in zwei Varianten:
- WizCut: Aktionen für Create Job, Get Job, Start Processing, Start Render und Approve.
- WizCut Trigger: ein Webhook-Trigger, der deinen Workflow startet, sobald sich der Job-Status ändert (mapping, ready, complete, approved).
Du verbindest die Webhook-URL des Triggers mit der callbackUrl deines Jobs und erhältst eine vollständig ereignisgesteuerte Pipeline. Zum Beispiel: Slack-Benachrichtigung beim Erkennen der Sprecher, automatischer Render-Start sobald die Schnitte bereit sind, und Download-Link, wenn die Episode fertig ist. Beide Nodes lassen sich außerdem als Tools für n8n-KI-Agenten einsetzen.
Für den schnellen Einstieg gibt es eine fertige Vorlage: Podcast-Schnittstatus mit WizCut und Slack automatisch verwalten.
Weitere Plattformen
Make.com- und Zapier-Integrationen sind in Planung. Du arbeitest mit einer anderen Plattform oder brauchst eine Workflow-Vorlage für dein konkretes Setup? WizCut-Support kontaktieren. Funktionswünsche sind willkommen.