WizCut
Éditeur Web
← Back to docs

WizCut API

Automatise l'édition de podcasts multicam avec l'API WizCut — upload, traitement et render par programmation.

L’API WizCut te permet d’automatiser l’édition de podcasts multicam. Tu uploades tes angles de caméra, WizCut détecte les intervenants et génère les coupes, tu peux optionnellement les relire dans un éditeur en ligne, et tu récupères la vidéo rendue via webhook.

Authentification

Crée une clé API sur wizcut.com/settings. Inclus-la dans chaque requête :

Authorization: Bearer wc_live_your_key_here

Les clés peuvent être révoquées à tout moment depuis la page de paramètres.

Créer un job

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
}

Champs :

ChampTypeDescription
sourcesarrayAngles de caméra ou fichiers audio. Chaque entrée a un label, un kind optionnel ("video" ou "audio", par défaut "video"), et un ext optionnel (par défaut "mp4").
tracksarrayAssociations intervenant-source. Passe speakers: [] pour laisser WizCut faire l’assignation automatique après l’analyse.
callbackUrlstringURL qui reçoit les notifications webhook lors des changements de statut.
reviewbooleanPar défaut true. Quand true, le job se met en pause à « ready » pour qu’un humain relise les coupes avant le render. Quand false, le render démarre automatiquement dès que le mapping des intervenants est soumis.

Réponse :

{
  "jobId": "uuid",
  "uploadUrls": {
    "source-uuid-1": "https://presigned-upload-url...",
    "source-uuid-2": "https://presigned-upload-url..."
  }
}

Uploader les fichiers

Envoie tes fichiers vidéo en PUT vers chaque URL présignée de la réponse. Pas besoin d’en-tête d’auth — l’URL est auto-authentifiante.

curl -X PUT -T camera1.mp4 "https://presigned-upload-url..."
curl -X PUT -T camera2.mp4 "https://presigned-upload-url..."

Lancer le traitement

POST /api/jobs/{jobId}/process

Ça démarre le pipeline : sync audio, détection des intervenants, génération des coupes et render proxy. La requête répond immédiatement — le traitement se fait en asynchrone.

Réponse :

{ "jobId": "uuid", "status": "syncing" }

Vérifier le statut d’un job

GET /api/jobs/{jobId}

Retourne l’objet job complet avec le statut actuel, les sources, les turns et les coupes.

Valeurs de statut :

StatutSignification
createdJob créé, en attente des uploads
syncingAlignement audio entre les sources
diarizingDétection des intervenants
mappingEn attente du mapping intervenant-source
readyCoupes générées, prêtes pour la relecture ou le render
renderingRender final en cours
completeRender terminé, output_url disponible
approvedOutput validé par un humain
failedQuelque chose s’est mal passé, voir error_message

Webhooks

Si tu fournis un callbackUrl, WizCut envoie des requêtes POST lors des transitions de statut :

Webhook « mapping » (intervenants détectés, mapping humain requis) :

{
  "jobId": "uuid",
  "status": "mapping",
  "reviewUrl": "https://wizcut.com/jobs/uuid/edit?reviewToken=..."
}

Envoie quelqu’un sur la reviewUrl pour mapper les intervenants aux sources caméra et relire les coupes.

Webhook « ready » (mapping terminé, coupes générées) :

{
  "jobId": "uuid",
  "status": "ready",
  "reviewUrl": "https://wizcut.com/jobs/uuid/edit?reviewToken=..."
}

Webhook « complete » (render terminé) :

{
  "jobId": "uuid",
  "status": "complete",
  "outputUrl": "https://presigned-download-url..."
}

Webhook « approved » (output validé via l’UI de relecture) :

{
  "jobId": "uuid",
  "status": "approved",
  "outputUrl": "https://presigned-download-url..."
}

Webhook « failed » :

{
  "jobId": "uuid",
  "status": "failed",
  "error": "description of what went wrong"
}

Mapping des intervenants et relecture (human-in-the-loop)

Après la détection des intervenants, le job passe en statut « mapping ». Un humain doit associer les intervenants détectés aux sources caméra — la diarization identifie quand quelqu’un parle, mais pas sur quelle caméra il est.

Le webhook « mapping » inclut une reviewUrl — un lien signé vers l’éditeur WizCut. Envoie quelqu’un là-bas. Dans l’éditeur, il peut :

  1. Associer chaque intervenant détecté à une source caméra
  2. Prévisualiser et modifier les coupes générées automatiquement
  3. Cliquer sur « Render » quand c’est bon (si review: true, le comportement par défaut)
  4. Cliquer optionnellement sur « Approve » après avoir relu l’output rendu

Avec review: false, le render démarre automatiquement dès que le mapping des intervenants est soumis — l’humain ne relit pas les coupes avant le render.

Avancé : contrôle programmatique des coupes

Pour les pipelines entièrement automatisés qui contournent l’UI, tu peux gérer les coupes et le render via l’API :

Modifier les coupes :

PATCH /api/jobs/{jobId}/cuts

{
  "cuts": [
    { "startMs": 0, "endMs": 5000, "sourceId": "source-uuid-1" },
    { "startMs": 5000, "endMs": 12000, "sourceId": "source-uuid-2" }
  ]
}

Déclencher le render :

POST /api/jobs/{jobId}/render

Valider l’output :

POST /api/jobs/{jobId}/approve

Réponses d’erreur

Tous les endpoints retournent les erreurs dans ce format :

{ "error": "Description of what went wrong" }

Codes HTTP courants :

CodeSignification
401Clé API manquante ou invalide
403Quota dépassé
404Job introuvable ou qui ne t’appartient pas
409Transition de statut invalide (ex. render d’un job qui n’est pas « ready »)
500Erreur serveur
503Service indisponible

Déroulement complet

Voilà le chemin nominal complet pour un agent IA ou une automatisation :

# 1. Create a job with two cameras
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 '.uploadUrls | to_entries[0].value')"
curl -X PUT -T camera2.mp4 "$(echo $JOB | jq -r '.uploadUrls | to_entries[1].value')"

# 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 webhook: { status: "mapping", reviewUrl: "..." }
#    Send a human to reviewUrl to map speakers and review cuts

# 5. Human maps speakers → edits cuts → clicks Render in the editor
#    Wait for webhook: { status: "complete", outputUrl: "..." }

# 6. Download the rendered video from outputUrl

Avec render automatique après mapping (review: false) :

# Same as above, but add "review": false to step 1
# Human still maps speakers at the reviewUrl (step 4)
# But rendering starts automatically after mapping — no cut review step
# You'll get: { status: "complete", outputUrl: "..." }
WizCut API – WizCut Docs