WizCut
Web-Editor
← Back to docs

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
}

Felder:

FeldTypBeschreibung
sourcesarrayKamerawinkel oder Audiodateien. Jeder Eintrag hat ein label, optionales kind ("video" oder "audio", Standard: "video") und optionales ext (Standard: "mp4").
tracksarrayZuordnung von Sprechern zu Quellen. Mit leerem speakers-Array [] weist WizCut die Sprecher nach der Analyse automatisch zu.
callbackUrlstringURL, an die Webhook-Benachrichtigungen bei Statusänderungen gesendet werden.
reviewbooleanStandard: 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.

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:

StatusBedeutung
createdJob angelegt, wartet auf Uploads
syncingAudio-Synchronisation zwischen den Quellen
diarizingSprechererkennung läuft
mappingSpeaker-to-Source-Zuordnung erforderlich
readySchnitte generiert, bereit zur Prüfung oder zum Rendering
renderingFinales Rendering läuft
completeRendering abgeschlossen, output_url verfügbar
approvedAusgabe von einem Menschen bestätigt
failedFehler 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 – die Diarisierung bestimmt 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:

  1. Jeden erkannten Sprecher einer Kameraquelle zuordnen
  2. Die automatisch generierten Schnitte in der Vorschau prüfen und bearbeiten
  3. Auf „Render” klicken, wenn alles stimmt (bei review: true, dem Standard)
  4. 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.

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" }
  ]
}

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:

CodeBedeutung
401Fehlender oder ungültiger API-Key
403Kontingent überschritten
404Job nicht gefunden oder nicht in deinem Besitz
409Ungültiger Statusübergang (z. B. Rendering eines Jobs, der noch nicht „ready” ist)
500Serverfehler
503Dienst 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: "..." }
WizCut API – WizCut Docs