WizCut API
Automatise le montage de podcasts multicam avec l'API WizCut : envoi, traitement et rendu par programmation.
L’API WizCut te permet d’automatiser le montage de podcasts multicam. Tu envoies tes angles de caméra, WizCut détecte les intervenants, trouve qui est sur quelle caméra 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.
La spec OpenAPI 3.1 complète est disponible sur https://wizcut.com/openapi.json, pour les générateurs de code et les plateformes d’agents. Tu préfères que ChatGPT, Claude ou ton propre agent s’occupe des montages à ta place ? Lis Utiliser WizCut avec ChatGPT, Claude et d’autres agents IA.
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", "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" }
}
Champs :
| Champ | Type | Description |
|---|---|---|
sources | array | Angles de caméra ou fichiers audio, 12 maximum par job. Il faut au moins deux sources vidéo pour qu’un job puisse être traité. Chaque entrée a un label, un kind optionnel ("video" ou "audio", par défaut "video"), un ext optionnel (mp4, mov, webm, mkv, wav, mp3, m4a ou aac ; par défaut "mp4" pour la vidéo, "wav" pour l’audio) et un fileSize optionnel : la taille exacte du fichier en octets, 100 Go (107374182400 octets) maximum par fichier. |
title | string | Optionnel. Un nom pour le job, par exemple le titre de l’épisode, 200 caractères maximum. Sans lui, le titre reprend les noms des sources et la date. |
callbackUrl | string | Optionnel. URL qui reçoit les notifications webhook : voir Webhooks. |
review | boolean | Par 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, que ce soit par une personne, par ton code ou par WizCut lui-même. |
autoMap | string | Par défaut "confident". Indique si WizCut a le droit de décider seul qui est sur quelle caméra : "off", "confident" ou "always". Voir Mapping automatique des caméras. |
silence | object | Optionnel. Suppression automatique des pauses : voir la section Suppression des silences. Si absent, c’est désactivé. |
share | boolean | Par défaut true. Donne à la vidéo terminée une page de partage non listée, que toute personne qui a le lien peut ouvrir : voir Liens de partage et de téléchargement. |
Tu ne peux pas passer le mapping des intervenants (tracks) ici : les IDs de source n’existent qu’une fois le job créé, donc il n’y a encore rien à quoi rattacher un intervenant. Une liste tracks qui nomme des intervenants est rejetée avec un 400 et "code": "TRACKS_ON_CREATE". Utilise autoMap, ou mappe les intervenants via l’API une fois la détection terminée.
Passe fileSize pour chaque fichier dont tu connais la taille. Les fichiers de plus de 100 Mo passent alors en upload multipart : tu peux envoyer les parties en parallèle, retenter une partie isolée, et c’est la seule façon d’envoyer des fichiers de plus de 5 Go. Sans fileSize, chaque fichier part en un seul PUT présigné, et le stockage plafonne ce type d’envoi à 5 Go.
fileSize doit être exact, parce qu’il est signé dans les URL d’upload : un PUT dont le corps n’a pas la même taille est rejeté. Un fichier au-dessus de la limite est refusé avec un 400 et "code": "FILE_TOO_LARGE" avant même que le job soit créé. La réponse contient maxBytes, la limite en octets. Si fileSize n’est pas un nombre entier d’octets, tu obtiens "code": "INVALID_FILE_SIZE". Un fichier qui ne peut pas être un enregistrement est refusé avec un 422 et "code": "NOT_A_MEDIA_FILE", lui aussi avant la création du job : un fichier de métadonnées macOS (un label ou un fileName facultatif qui commence par ._ ; le vrai fichier porte le même nom sans ._) ou un fileSize sous 32 Ko. La réponse donne le fichier dans fileName, la raison dans reason (macos_metadata ou too_small) et son sourceIndex.
Réponse :
{
"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 est indexé par les IDs de source attribués par WizCut, dans le même ordre que ton tableau sources. Tu peux ignorer audioUploads : c’est utilisé par les apps WizCut, qui envoient une piste audio extraite avant la vidéo.
Retenter sans risque avec Idempotency-Key
Si une requête expire ou que la connexion saute, tu ne sais pas si le job a été créé. Si tu retentes à l’aveugle, tu risques de te retrouver avec deux jobs. Pour pouvoir retenter sans crainte, envoie un en-tête Idempotency-Key avec une valeur que tu choisis pour ce job, par exemple un UUID :
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": [...] }'
C’est optionnel, et sans cet en-tête tout marche comme avant. On le recommande pour les agents et pour tout ce qui retente tout seul.
- Même clé, même corps : tu récupères le job créé par la première requête, avec le même
jobIdet, pour les uploads multipart, les mêmesuploadId,key,partSizeetpartCount. Toutes les URL d’upload sont signées à nouveau. La réponse porte l’en-têteIdempotent-Replayed: true, et aucun second job n’est créé. - Même clé, corps différent :
422avec"code": "IDEMPOTENCY_KEY_MISMATCH". Prends une nouvelle clé pour une requête différente. Les corps sont comparés une fois le JSON parsé, donc l’ordre des clés et les espaces n’ont aucune importance. - La première requête tourne encore :
409avec"code": "IDEMPOTENCY_IN_PROGRESS". Attends une seconde et retente. - Le job a été supprimé entre-temps :
409avec"code": "IDEMPOTENCY_KEY_REUSED". Prends une nouvelle clé.
Une clé fait de 1 à 255 caractères ASCII imprimables (sinon, tu reçois un 400 avec "code": "INVALID_IDEMPOTENCY_KEY"), elle est liée à ton compte et WizCut s’en souvient 24 heures. Une requête refusée avant la création du job, à cause d’une erreur de validation ou parce que tes minutes sont épuisées, ne consomme pas sa clé : tu corriges et tu retentes avec la même.
Uploader les fichiers
Pas besoin d’en-tête d’auth pour les URL présignées : elles s’authentifient toutes seules.
Envoie exactement les octets que tu as déclarés. Les clients HTTP calculent Content-Length à partir du corps qu’ils envoient, donc inutile de le fixer toi-même.
"method": "put" : envoie le fichier entier en PUT vers url, dans l’heure qui suit :
curl -X PUT -T mic-mix.wav "https://presigned-upload-url..."
"method": "multipart" : découpe le fichier en morceaux de partSize octets (le dernier est plus court) et envoie le morceau n en PUT vers l’URL de la partie n. Chaque URL de partie n’accepte que la longueur exacte de sa partie, et il y a exactement partCount parties : demander un numéro plus élevé renvoie un 400 :
-
urlscontient les URL des premières parties (urls[0]correspond à la partie 1). Demande les suivantes au fur et à mesure, 16 maximum par requête :POST /api/jobs/{jobId}/sources/{sourceId}/parts{ "uploadId": "...", "partNumbers": [5, 6, 7, 8] }La réponse associe les numéros de partie à des URL :
{ "urls": { "5": "https://...", "6": "https://..." } }. Les URL de partie sont valables deux heures, donc récupère-les juste avant de t’en servir. -
Une fois toutes les parties envoyées, termine l’upload :
POST /api/uploads/complete{ "key": "sources/uuid/source-uuid-1.mp4", "uploadId": "..." }
Pour abandonner un upload, envoie le même corps à POST /api/uploads/abort.
WizCut vérifie la taille réelle de chaque fichier une fois envoyé, quand tu termines un upload multipart, puis à nouveau quand tu lances le traitement. Un fichier au-dessus de la limite est supprimé et la requête reçoit un 400 avec "code": "FILE_TOO_LARGE". Un fichier beaucoup plus petit ou plus gros que son fileSize déclaré donne "code": "FILE_SIZE_MISMATCH". Renvoie-le sur la même source.
Importer des fichiers depuis un lien
Si tes enregistrements sont déjà en ligne (dans Google Drive, Dropbox ou OneDrive, sur le lien d’export d’une plateforme d’enregistrement, ou en pièce jointe d’une discussion avec un assistant IA), donne le lien à WizCut au lieu d’envoyer les octets. WizCut télécharge le fichier en arrière-plan.
Crée le job avec "sources": [] (ou avec les fichiers que tu envoies toi-même), puis ajoute un fichier par appel :
POST /api/jobs/{jobId}/sources/from-url
{
"url": "https://drive.google.com/file/d/1AbC.../view?usp=sharing",
"label": "Camera 1",
"kind": "video"
}
| Champ | Type | Description |
|---|---|---|
url | string | Un lien https:// vers un seul fichier vidéo ou audio, 4096 caractères maximum. |
label | string | Un nom pour le fichier, par exemple "Camera 1" ou "Host mic", 80 caractères maximum. |
kind | string | Optionnel : "video" ou "audio". Sans lui, WizCut décide d’après le fichier. Un fichier sans vidéo est toujours une source audio. |
Réponse (202 Accepted) :
{ "sourceId": "uuid", "status": "importing" }
L’appel répond tout de suite. Envoie un en-tête Idempotency-Key, comme pour créer un job, pour qu’un retry n’importe pas le fichier deux fois : même clé et même corps, tu récupères le même sourceId, avec Idempotent-Replayed: true.
Les liens qui marchent :
- Les liens de téléchargement direct vers le fichier lui-même, y compris les liens signés des services de stockage et le lien d’export d’une plateforme d’enregistrement quand il pointe sur le fichier.
- Les liens de partage Google Drive, Dropbox, OneDrive et SharePoint. Partage-les avec « toute personne disposant du lien » ; WizCut les transforme lui-même en téléchargements, y compris l’étape « impossible d’analyser ce fichier à la recherche de virus » de Drive pour les gros fichiers.
- Ceux qui ne marchent pas : les pages web, les dossiers, et les pages YouTube, Vimeo, Riverside ou Zoom. WizCut ne lit pas les pages pour y chercher une vidéo. Prends le lien de téléchargement de la plateforme, ou envoie le fichier.
Les formats sont les mêmes que pour les uploads : MP4, MOV, M4A, WebM, MKV, WAV, MP3 et AAC. WizCut vérifie le contenu du fichier, pas son nom. La limite de 100 Go par fichier s’applique aussi.
Suivre l’import. Tant que l’import n’est pas terminé, la source compte comme en cours d’envoi : lancer le traitement répond donc 409 avec "code": "SOURCES_PENDING" en attendant. Le résumé du statut liste chaque fichier sous 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 passe de importing à imported, ou à import_failed avec import.error qui dit pourquoi. WizCut ne garde que l’hôte du lien, jamais le lien lui-même.
Quand un import échoue, le job continue. Retire le fichier, puis ajoute à sa place un lien qui marche ou un upload :
DELETE /api/jobs/{jobId}/sources/{sourceId}
Si le job a un callbackUrl, WizCut envoie aussi un webhook source_import_failed. Les raisons (import.error.code) :
| Code | Signification |
|---|---|
URL_NOT_ALLOWED | Ce n’est pas un lien https:// public : adresse privée ou locale, port non standard, ou identifiant et mot de passe dans le lien. |
URL_NOT_REACHABLE | Le serveur est injoignable, ou il a répondu par une erreur comme un 404. |
NOT_A_FILE | Le lien ouvre une page web ou un dossier, pas un fichier. |
LOGIN_REQUIRED | Le lien demande une connexion. Partage-le avec « toute personne disposant du lien ». |
FILE_TOO_LARGE | Au-dessus de la limite de 100 Go par fichier. |
UNSUPPORTED_MEDIA_FORMAT | Format vidéo ou audio non pris en charge, ou fichier abîmé. |
IMPORT_TIMEOUT | Le téléchargement s’est bloqué ou a duré trop longtemps. |
IMPORT_FAILED | Un souci côté WizCut. Retente. |
Refusé tout de suite (aucun import ne démarre) : 400 avec URL_NOT_ALLOWED ou NOT_A_FILE pour les liens que WizCut repère comme faux sans même les ouvrir (http://, YouTube) ; 409 avec INVALID_STATUS une fois le traitement lancé, ou JOB_FULL à 12 fichiers ; 429 avec TOO_MANY_IMPORTS quand 6 imports tournent déjà dans le job, ou IMPORT_RATE_LIMITED après 20 imports en une heure, les deux avec un en-tête Retry-After ; 503 avec IMPORT_UNAVAILABLE si l’import n’est pas disponible pour le moment.
Tu utilises n8n, Make ou Zapier ? C’est la voie royale : pas de manipulation de fichiers, pas d’upload multipart. Crée le job avec un nœud HTTP Request (
"sources": []), ajoute chaque fichier avec un autre nœud HTTP Request qui pointe vers son lien Drive ou Dropbox, et passe unIdempotency-Keyfixe par fichier (par exemple l’ID du fichier dans ton drive) pour qu’un nœud relancé n’importe pas deux fois. Ensuite, patiente : fais du polling surGET /api/jobs/{jobId}?view=summarytoutes les minutes jusqu’à ce queuploads.allUploadedvailletrue, ou réagis au webhooksource_import_failed, puis lance le traitement.
Lancer le traitement
POST /api/jobs/{jobId}/process
Appelle cet endpoint une fois que tous les fichiers sont envoyés. Ça démarre le pipeline : sync audio, détection des intervenants, render proxy, mapping des caméras et génération des coupes. La requête répond immédiatement, le traitement se fait en asynchrone.
Corps optionnel :
{ "diarizeSourceIds": ["source-uuid-3"] }
diarizeSourceIds choisit les sources que WizCut écoute pour la détection des intervenants. C’est ton audio des voix : le son de l’épisode part aussi de là (voir le mix audio plus bas). Si tu l’omets, WizCut utilise tes sources audio, ou la première source s’il n’y en a pas. Choisis les sources où tout le monde s’entend le mieux : une caméra avec un micro coupé ou trop loin donne un job sans aucune coupe.
Tu peux aussi envoyer silence ici, au même format qu’à la création du job, par exemple quand le réglage des pauses est choisi après la création. Si tu l’omets, le job garde le réglage de sa création. title marche pareil.
Réponse :
{ "jobId": "uuid", "status": "syncing" }
Lister les jobs
GET /api/jobs
Retourne { "jobs": [...] } avec tes 50 jobs les plus récents, du plus récent au plus ancien. Chacun contient id, title, status, thumbnails, created_at et updated_at.
thumbnails donne une petite image fixe JPEG (320 px de large) par caméra, dans l’ordre des caméras, sous la forme { source_id, url }. C’est [] tant que les aperçus des caméras ne sont pas prêts, quelques minutes après le début du traitement. Les URL sont signées pour 6 heures et changent à chaque requête : si tu mets les images en cache, fais-le par source_id. Une caméra dont l’image n’a pas pu être créée renvoie 404, affiche alors un espace réservé.
Vérifier le statut d’un job
GET /api/jobs/{jobId}
Réponse :
{
"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"
}
Le job en lui-même se trouve sous job. Les URL signées de la réponse (output_url, sourceUrls, audioUrl) sont signées à nouveau à chaque requête, donc récupère le job à nouveau plutôt que de les stocker. downloadUrl et shareUrl sont les liens que tu peux stocker : voir Liens de partage et de téléchargement.
camera_map est la proposition de WizCut pour savoir qui est sur quelle caméra : voir La camera map. Elle vaut null tant qu’elle n’a pas été calculée.
Valeurs de statut :
| Statut | Signification |
|---|---|
created | Job créé, en attente des uploads |
uploading | En attente de la fin des uploads (par exemple après la réouverture d’un job en échec) |
syncing | Alignement audio entre les sources |
diarizing | Détection des intervenants |
mapping | Intervenants détectés. WizCut cherche encore qui est sur quelle caméra, ou une personne (ou ton agent) doit le confirmer |
ready | Coupes générées, prêtes pour la relecture ou le render |
rendering | Render final en cours |
complete | Render terminé, output_url disponible |
approved | Output validé par un humain |
failed | Quelque chose s’est mal passé, voir error_message |
Résumé du statut
Le job complet contient chaque tour de parole et chaque coupe, ce qui pèse vite. Si tu veux juste savoir où en est un job et quoi faire ensuite, par exemple pour du polling depuis un agent ou une automatisation, demande le résumé :
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 donne l’avancement du render de 0 à 1 pendant que le job est en rendering, et vaut null le reste du temps. error et failedAtStatus sont les mêmes que dans le webhook « failed ». Tant que le job accepte des fichiers (created, uploading), uploads liste chaque fichier et où il en est (uploading, uploaded, ou, pour les fichiers importés depuis un lien, importing, imported ou import_failed avec la raison), puis vaut null ensuite. nextAction.message est un petit message en anglais que tu peux transmettre tel quel à une personne ou à un agent ; pour ta logique, appuie-toi sur nextAction.type :
type | Statut | Que faire | url |
|---|---|---|---|
upload_files | created, uploading ; ou failed quand l’envoi s’est arrêté | Envoie les fichiers, puis lance le traitement. Si le job a échoué parce que l’envoi s’est arrêté (rien reçu pendant 24 heures), la personne qui envoyait peut le reprendre dans l’app WizCut avec les mêmes fichiers ; ce qui est arrivé est gardé une semaine. | null |
wait | syncing, diarizing, rendering | Rien, WizCut bosse. Repasse plus tard ou attends le prochain webhook. | null |
map_speakers | mapping | Confirme qui est sur quelle caméra, dans l’éditeur ou via l’API. | Lien de relecture, comme la reviewUrl du webhook « mapping » |
review_or_render | ready | Relis les coupes, ou lance le render. | Lien de relecture |
download | complete, approved | Télécharge la vidéo. | URL de render fraîchement signée (aussi dans outputUrl) |
retry | failed | Appelle POST /api/jobs/{jobId}/retry. | null |
contact_support | failed | Retenter ne servirait à rien, par exemple quand le fichier n’est pas dans un format compatible. Crée un nouveau job, ou contacte-nous. | Lien mailto: |
Quand les sources choisies pour la détection des intervenants sont muettes, le type est retry, mais un simple retry échouerait de la même façon : le message te dit de retenter avec une liste diarizeSourceIds qui désigne une source où la parole est claire.
Les fichiers que WizCut n’a pas pu caler. WizCut cale tes fichiers grâce à leur son. Quand le son d’un fichier ne colle à aucun autre — souvent un export coupé ou monté au lieu de l’enregistrement d’origine —, WizCut le place quand même au mieux, mais l’image et le son peuvent être décalés dessus. Le job n’échoue pas pour autant : syncWarnings (dans le résumé et dans le GET /api/jobs/{jobId} complet) liste chacun de ces fichiers avec son sourceId, son label, son kind et une reason — unverified (placé, mais rien ne l’a confirmé), not_placed (il commence au début), no_audio (pas de son pour le caler) ou unreadable (son son n’a pas pu être lu, il n’a donc pas été vérifié du tout). Un fichier qui a bien collé peut quand même être drifting : l’appareil qui l’a enregistré n’a pas tout à fait la même horloge, donc il se décale peu à peu sur l’épisode, de driftMs (en millisecondes, du début à la fin). WizCut le cale au milieu, donc le début et la fin sont chacun décalés d’environ la moitié ; ce n’est pas encore corrigé. C’est [] quand tous les fichiers collent, et les messages map_speakers, review_or_render et download nomment aussi les fichiers. Si la liste n’est pas vide, demande à quelqu’un de vérifier la synchro labiale avant de publier.
Revérifier la synchro. Pour un fichier unreadable, POST /api/jobs/{jobId}/sync-recheck relit le son de tous les fichiers et les recale. Seul le placement change ; le statut, les intervenants, l’attribution et les coupes restent. La réponse arrive tout de suite en 202, et syncRecheck (dans le résumé et dans le job complet) dit où on en est : running pendant la vérification (quelques minutes avec de gros fichiers), failed quand la dernière n’a pas abouti, et available quand une vérification peut aider maintenant (un fichier est unreadable, le job est mapping, ready ou complete, et aucune ne tourne). Interroge jusqu’à ce que running passe à false, relis syncWarnings, et lance le rendu seulement après, pour que la vidéo utilise le nouveau placement. Refus : SYNC_RECHECK_NOT_NEEDED et SYNC_RECHECK_RUNNING (tous deux 409). WizCut lance déjà une telle vérification tout seul juste après la synchro dès qu’un fichier est unreadable, donc en général tu vois juste running repasser à false ; appelle-la toi-même quand celle-là n’a pas aidé (failed).
Rendre avec des fichiers pas calés. Un fichier not_placed, no_audio ou unreadable est placé au début de l’épisode, donc il n’est pas synchro dans la vidéo. POST /api/jobs/{jobId}/render refuse alors en 409 : SYNC_RECHECK_RUNNING tant qu’une vérification cale encore les fichiers (attends quelques minutes et réessaie), FILES_NOT_SYNCED quand plus rien ne les placera, avec files qui les liste. Envoie {"allowUnsyncedFiles": true} pour rendre quand même, une fois qu’une personne l’a choisi ; la vidéo porte alors l’avertissement de rendu FILES_NOT_SYNCED. Les jobs créés avec review: false attendent la fin d’une vérification en cours avant de se rendre tout seuls, et se rendent avec l’avertissement si des fichiers ne sont toujours pas calés.
Les rendus qui ne sortent pas comme demandé. Rarement, un rendu se termine sans pouvoir faire tout ce que tu as demandé. En général, l’un de ces deux cas : PROGRAM_AUDIO_FAILED, quand WizCut n’a pas pu mixer le son de l’épisode depuis tes fichiers d’origine, donc la vidéo utilise le mix brut de la détection des intervenants, sans ton mix audio ni ton niveau sonore ; et AV_DRIFT, quand une partie de la vidéo est sortie nettement plus longue ou plus courte que prévu, donc l’image et le son peuvent se décaler. Le job est quand même « complete », et renderWarnings (dans le résumé et dans le GET /api/jobs/{jobId} complet) liste ce qui n’a pas marché, chaque fois avec un code et un message que tu peux montrer à quelqu’un. Le message download le dit aussi, et le webhook « complete » porte la même liste dans warnings. Elle vaut [] quand le rendu est sorti comme demandé. Relancer un rendu règle le problème la plupart du temps. Un troisième, FILES_NOT_SYNCED, veut dire que le rendu a été lancé avec allowUnsyncedFiles alors que des fichiers n’étaient pas calés ; relance-le une fois qu’ils le sont.
Un job peut être retenté 5 fois par heure. Si le job échoue encore après ces 5 tentatives, POST /api/jobs/{jobId}/retry répond 429 avec "code": "RETRY_LIMIT", et retryAfterSeconds (aussi dans l’en-tête Retry-After) indique quand tu pourras retenter. Les autres refus portent eux aussi un code : INVALID_STATUS (409, le job n’est pas failed), NOT_RETRYABLE (422, il a échoué à une étape qu’un retry ne peut pas relancer) et INVALID_DIARIZE_SOURCES (400, diarizeSourceIds est vide ou désigne des sources que le job n’a pas).
De nouveaux types pourront être ajoutés plus tard, donc traite un type inconnu comme wait. Une valeur de view inconnue renvoie le job complet.
Supprimer un job
DELETE /api/jobs/{jobId}
Supprime le job et tous ses fichiers : uploads, proxys, audio de détection des intervenants et rendu final. Ça marche quel que soit le statut ; si une étape tourne encore, son résultat est nettoyé dès qu’elle se termine. Les minutes déjà utilisées ne sont pas recréditées. Renvoie { "ok": true }, ou 404 si le job n’existe pas ou ne t’appartient pas.
Liens de partage et de téléchargement
Une fois la vidéo terminée, tu disposes de trois liens. Choisis celui qui colle à ce que tu veux en faire :
| Champ | Valable | Qui peut l’ouvrir | À utiliser pour |
|---|---|---|---|
outputUrl | Quelques heures (une URL de fichier signée) | Toute personne qui l’a | Passer le fichier à un autre service tout de suite |
downloadUrl | Tant que le job existe | Toi : ta clé API, ou un navigateur connecté à WizCut | Des liens que tu gardes dans tes propres outils |
shareUrl | Tant que le job existe et que le partage est activé | Toute personne qui a le lien | Envoyer la vidéo à des gens, ou un lien stable pour un tiers |
Les trois sont dans GET /api/jobs/{jobId} (complet et ?view=summary) et dans les webhooks « complete » et « approved ».
downloadUrl vaut https://wizcut.com/api/jobs/{jobId}/output. Chaque requête redirige (302) vers une URL de fichier fraîchement signée, donc le lien lui-même n’expire jamais. Envoie ta clé API avec ; dans un navigateur, il marche si tu es connecté, et sinon il te demande d’abord de te connecter. Ajoute ?download=1 pour enregistrer le fichier au lieu de le lire. Tant que le render n’est pas terminé, il répond 409 avec "code": "NOT_RENDERED".
curl -L -H "Authorization: Bearer $WIZCUT_API_KEY" \
-o episode.mp4 "https://wizcut.com/api/jobs/$JOB_ID/output"
shareUrl est une page non listée (https://wizcut.com/s/…) avec un lecteur vidéo, le titre et un bouton de téléchargement. Personne ne peut la trouver sans le lien, et les moteurs de recherche ne l’indexent pas. Ajoute /video.mp4 au lien pour obtenir le fichier brut. Tant que le render n’est pas terminé, la page indique que l’épisode n’est pas encore prêt, donc tu peux distribuer le lien à l’avance.
Le partage est activé par défaut sur les nouveaux jobs. Désactive-le à la création avec "share": false, ou change-le plus tard :
PATCH /api/jobs/{jobId}
{ "share": false }
| Champ | Type | Description |
|---|---|---|
share | boolean | Active ou désactive la page de partage. Désactiver puis réactiver redonne le même lien. |
resetShareLink | boolean | true remplace le lien par un nouveau. L’ancien lien ne marche plus, définitivement : à utiliser quand un lien a atterri là où il n’aurait pas dû. |
Réponse :
{ "jobId": "uuid", "share": true, "shareUrl": "https://wizcut.com/s/..." }
shareUrl vaut null tant que le partage est désactivé. Tu peux aussi activer ou désactiver le partage, copier le lien ou en créer un nouveau dans l’éditeur WizCut, sous la vidéo terminée.
La page de partage lit la vidéo pour toute personne qui a le lien, donc traite-la comme la vidéo elle-même. Si l’épisode montre d’autres gens, assure-toi qu’ils sont d’accord pour qu’il soit partagé.
Transcription et sous-titres
Les épisodes qui ont une transcription ont "hasTranscript": true dans GET /api/jobs/{jobId} (complet et avec ?view=summary). On déploie les transcriptions petit à petit, donc la plupart des épisodes n’en ont pas encore.
GET /api/jobs/{jobId}/transcript?format=srt
| Paramètre | Valeurs | Description |
|---|---|---|
format | txt (par défaut), srt, vtt | Texte brut avec un paragraphe par intervenant, son nom et le temps ; ou des sous-titres en SRT ou WebVTT. |
timeline | edit (par défaut), render | edit suit le montage tel qu’il est maintenant. render correspond à la dernière vidéo terminée, pour des sous-titres à côté d’un fichier que tu as déjà téléchargé. |
download | 1 | Envoie Content-Disposition: attachment, nommé d’après le titre du job. |
La réponse, c’est le fichier lui-même, pas du JSON. Les temps suivent le montage : ce qui a été coupé de l’épisode n’y est pas, et tout ce qui suit avance d’autant, pour que les sous-titres collent à la vidéo. L’en-tête X-WizCut-Timeline dit quel montage ils suivent ; il dit edit si tu as demandé render mais que la vidéo a été faite avant que WizCut n’enregistre ce qu’un rendu coupe.
curl -H "Authorization: Bearer $WIZCUT_API_KEY" \
-o episode.srt "https://wizcut.com/api/jobs/$JOB_ID/transcript?format=srt&timeline=render"
Erreurs : 404 avec "code": "NO_TRANSCRIPT" quand l’épisode n’en a pas, 409 avec "code": "INVALID_STATUS" avant qu’il soit coupé, et 409 avec "code": "NOT_RENDERED" pour timeline=render sans vidéo terminée.
Chapitres, description et notes d’épisode
Pour les épisodes qui ont une transcription, WizCut écrit aussi des chapitres, un brouillon de description et des notes d’épisode. detailsStatus dans GET /api/jobs/{jobId} (complet et avec ?view=summary) dit où ça en est : none, pending (en cours, moins d’une minute), ready ou failed.
GET /api/jobs/{jobId}/details
| Paramètre | Valeurs | Description |
|---|---|---|
timeline | edit (par défaut), render | Les temps des chapitres sur le montage actuel, ou sur la dernière vidéo terminée. |
format | json (par défaut), youtube, podcast | youtube, c’est la liste de chapitres pour une description YouTube, en texte (0:00 Titre par ligne, au moins trois chapitres). podcast, ce sont des chapitres JSON Podcasting 2.0. |
{
"status": "ready",
"language": "fr",
"chapters": [
{ "startMs": 0, "sourceMs": 0, "title": "Pourquoi Anna a lancé l’émission", "summary": "Anna raconte à Ben les débuts du podcast.", "origin": "ai" },
{ "startMs": 412000, "sourceMs": 431250, "title": "Enregistrer en voyage", "summary": "", "origin": "user" }
],
"description": "Anna et Ben parlent des débuts de l’émission et de l’enregistrement en voyage.",
"showNotes": ["Les débuts du podcast", "Un kit d’enregistrement pour voyager"],
"youtube": null,
"warnings": ["TOO_FEW_FOR_YOUTUBE"],
"revision": 1,
"edited": true
}
Les chapitres suivent le montage : startMs, c’est le début dans la vidéo, sourceMs le début dans l’enregistrement. Un chapitre qui commence dans un passage coupé démarre là où l’épisode reprend, et un chapitre coupé en entier disparaît jusqu’à ce que le passage revienne. Ensuite, les règles de YouTube s’appliquent : le premier chapitre à 0:00, chacun d’au moins 10 secondes. Les intervenants portent les noms que tu leur as donnés dans WizCut. warnings contient des codes : NEWER_VERSION, CHAPTERS_CUT_OUT, CHAPTERS_TOO_SHORT, TOO_FEW_FOR_YOUTUBE.
Pour les modifier, renvoie tout avec la revision que tu as lue :
PUT /api/jobs/{jobId}/details
{ "revision": 1, "chapters": [{ "sourceMs": 0, "title": "Pourquoi Anna a lancé l’émission" }], "description": "…", "showNotes": ["…"] }
Les temps des chapitres sont en sourceMs, dans l’ordre ; titres de 1 à 80 caractères, 30 chapitres au plus, une description jusqu’à 2 000 caractères, jusqu’à 20 notes de 300. Un chapitre envoyé sans summary garde son résumé. Les chapitres que le montage masque en ce moment sont conservés. Le premier enregistrement crée ta propre version, et c’est elle que WizCut affiche ensuite. POST /api/jobs/{jobId}/details/regenerate refait tout à partir de la transcription (202, puis status: "pending") ; ta version reste jusqu’à ce que tu la supprimes avec DELETE /api/jobs/{jobId}/details?revision=….
Erreurs : 404 avec "code": "NO_DETAILS" quand il n’y a rien dans le format demandé, 409 avec "code": "NOT_RENDERED" pour timeline=render sans vidéo terminée, à l’enregistrement 400 avec "code": "INVALID_DETAILS" et 409 avec "code": "EDIT_CHANGED" (quelqu’un a enregistré depuis ta revision), et 404 avec "code": "NO_TRANSCRIPT" pour régénérer un épisode sans transcription.
Webhooks
Si tu fournis un callbackUrl, WizCut envoie une requête POST en JSON quand un job atteint un des statuts ci-dessous. WizCut tente chaque livraison jusqu’à trois fois et attend jusqu’à 10 secondes que ton endpoint réponde.
Chaque livraison est signée, ce qui te permet de vérifier qu’elle vient bien de WizCut : voir Vérifier les webhooks. Fais aussi du polling en secours, au cas où une livraison se perdrait.
Webhook « mapping » (une personne doit confirmer qui est sur quelle caméra) :
{
"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"], "...": "..." }
]
}
}
Envoie quelqu’un sur la reviewUrl pour mapper les intervenants aux sources caméra et relire les coupes, ou mappe-les via l’API. Les liens de relecture sont valables 72 heures. speakers liste les intervenants détectés, du plus bavard au moins bavard.
cameraMap est la proposition de WizCut, au même format que camera_map sur le job : voir La camera map. Elle est absente quand il n’y a pas encore de proposition.
Le moment où ce webhook arrive dépend de autoMap :
"confident"ou"always": le job attend en « mapping » sans webhook pendant que WizCut cherche les caméras, ce qui prend quelques minutes une fois les proxys prêts. Ensuite, soit il mappe les caméras lui-même et le prochain webhook que tu reçois est « ready », soit il envoie « mapping » avec la proposition en pièce jointe. Si WizCut n’arrive pas à calculer de proposition (par exemple parce qu’un proxy a échoué), « mapping » part sanscameraMap, au plus tard environ 30 minutes après la détection des intervenants."off": « mapping » part juste après la détection des intervenants, en général sanscameraMap. La proposition apparaît dansGET /api/jobs/{jobId}quelques minutes plus tard.
Webhook « ready » (mapping soumis, par une personne, ton code ou WizCut, et 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...",
"downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
"shareUrl": "https://wizcut.com/s/..."
}
Webhook « approved » (output validé via l’UI de relecture) :
{
"jobId": "uuid",
"status": "approved",
"outputUrl": "https://presigned-download-url...",
"downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
"shareUrl": "https://wizcut.com/s/..."
}
Webhook « failed » (le job a échoué, à n’importe quelle étape) :
{
"jobId": "uuid",
"status": "failed",
"error": "description of what went wrong",
"failedAtStatus": "syncing"
}
error contient le même message que error_message dans GET /api/jobs/{jobId}, et failedAtStatus indique l’étape qui a échoué, par exemple syncing, diarizing ou rendering. Pour la plupart des échecs de sync, de détection des intervenants et de render, WizCut refait d’abord une tentative tout seul : si tu reçois ce webhook, c’est que la deuxième n’a pas marché non plus.
Il y a une exception : le fichier que WizCut n’arrive pas à lire. Chaque upload est vérifié avant le traitement, et tout ce qui n’est pas un fichier MP4, MOV, M4A, WebM, MKV, WAV, MP3 ou AAC fait échouer le job tout de suite, sans nouvelle tentative, quelle que soit l’extension : le même fichier échouerait de la même façon. C’est aussi le cas d’un fichier abîmé ou coupé en cours de route. L’error désigne le fichier par son label, par exemple "Camera 2" isn't a supported video or audio format, or the file is damaged. (le message est renvoyé tel quel, en anglais). Envoie un fichier compatible dans un nouveau job.
Webhook « source_import_failed » (un fichier ajouté depuis un lien n’a pas pu être importé) :
{
"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."
}
Celui-ci concerne un seul fichier, pas le job : le job reste où il en était. Retire la source avec DELETE /api/jobs/{jobId}/sources/{sourceId}, puis ajoute un lien qui marche ou un upload. code est l’un des codes d’échec d’import. Un import réussi n’envoie pas de webhook : consulte le résumé du statut.
Le outputUrl des webhooks « complete » et « approved » est valable sept jours après la fin du render. GET /api/jobs/{jobId} retourne toujours un output_url fraîchement signé. Pour garder un lien, stocke plutôt downloadUrl ou shareUrl (shareUrl vaut null quand le partage est désactivé) : voir Liens de partage et de téléchargement.
Vérifier les webhooks
WizCut signe chaque webhook selon la spec Standard Webhooks, donc les bibliothèques officielles standardwebhooks peuvent faire la vérification à ta place. Chaque livraison porte trois en-têtes :
| En-tête | Valeur |
|---|---|
webhook-id | Unique par événement, du genre msg_2b6f0c…. Un nouvel essai du même événement garde le même id : sers-t’en pour ignorer les doublons. |
webhook-timestamp | Le moment où cette tentative a été envoyée, en secondes Unix. |
webhook-signature | Une ou plusieurs signatures séparées par des espaces, chacune sous la forme v1,<base64>. |
Ton secret de signature se trouve sur la page de paramètres, sous « Secret de signature des webhooks ». Il ressemble à whsec_…, et un seul secret couvre tous tes jobs.
Chaque signature est le HMAC-SHA256 de {webhook-id}.{webhook-timestamp}.{body} encodé en base64, avec comme clé les octets de ton secret : la partie après whsec_, décodée depuis le base64. Pour vérifier une livraison :
- Calcule la signature sur le corps brut de la requête, exactement comme reçu, pas sur du JSON que tu as parsé puis resérialisé.
- Accepte la livraison si l’une des signatures
v1de l’en-tête correspond. Fais la comparaison en temps constant. - Rejette les timestamps à plus de 5 minutes de ton horloge, pour qu’une livraison interceptée ne puisse pas être rejouée plus tard.
- Garde la trace des
webhook-iddéjà traités, et ignore les répétitions.
Avec le package standardwebhooks (Node) :
import express from "express";
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.WIZCUT_WEBHOOK_SECRET); // "whsec_..."
const app = express();
// express.raw : la signature couvre le corps exactement comme envoyé
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
let event;
try {
// Vérifie la signature et la fenêtre de 5 minutes sur le timestamp ; lève une erreur si l'une des deux échoue
event = wh.verify(req.body.toString("utf8"), req.headers);
} catch {
return res.status(400).send("Invalid signature");
}
// event.jobId, event.status, ...
res.sendStatus(200);
});
Avec crypto tout seul (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
Renouveler ton secret. « Renouveler le secret » sur la page de paramètres crée un nouveau secret. L’ancien continue de marcher pendant 24 heures : durant ce temps, chaque livraison porte deux signatures, la nouvelle en premier, donc ton serveur vérifie avec celui qu’il a. Remplace l’ancien secret par le nouveau dans ces 24 heures. Si tu le renouvelles encore avant la fin, le plus ancien s’arrête aussitôt : seuls le secret actuel et le précédent signent, jamais plus.
Si WizCut n’arrive pas à signer une livraison, il l’envoie quand même, sans les en-têtes de signature, plutôt que de la perdre. À toi de décider si tu acceptes une livraison non signée ; si tu la rejettes, va chercher le job avec GET /api/jobs/{jobId} pour voir ce qui a changé.
Mapping des intervenants et relecture (human-in-the-loop)
Après la détection des intervenants, le job passe en statut « mapping ». Les intervenants détectés doivent être associés aux sources caméra : cette détection identifie quand quelqu’un parle, mais pas sur quelle caméra il est.
WizCut essaie de le deviner pour toi. Les gens bougent quand ils parlent : ils gesticulent, hochent la tête, se penchent. WizCut compare donc la parole de chaque intervenant avec le mouvement de chaque caméra et propose qui est sur laquelle. Tu décides jusqu’où il peut aller seul avec autoMap.
Quand il faut une personne, WizCut envoie le webhook « mapping ». Il inclut une reviewUrl, un lien signé vers l’éditeur WizCut. Envoie quelqu’un là-bas. Dans l’éditeur, il peut :
- Vérifier quel intervenant est sur quelle caméra (les caméras dont WizCut est sûr sont déjà sélectionnées)
- Prévisualiser et modifier les coupes générées automatiquement
- Cliquer sur « Render » quand c’est bon (si
review: true, le comportement par défaut) - 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. Personne ne relit les coupes avant le render.
Mapping automatique des caméras
Règle autoMap à la création du job :
| Mode | Ce que fait WizCut | À choisir quand |
|---|---|---|
"off" | Ne mappe jamais les caméras seul. Envoie « mapping » juste après la détection des intervenants ; la proposition apparaît sur le job quelques minutes plus tard, pour qu’une personne ou ton agent s’en serve. | Une personne relit de toute façon le mapping. |
"confident" | Par défaut. Mappe les caméras seul quand il est sûr d’avoir trouvé un gros plan de chaque intervenant, puis passe en « ready ». Sinon, envoie « mapping » avec la proposition. Un plan large ou un plan à deux sert dans le montage, mais ne compte jamais comme la caméra propre d’un intervenant. | La plupart des intégrations. WizCut ne se manifeste que quand il a besoin d’aide. |
"always" | N’attend pas de personne. Utilise les réponses dont il est sûr, puis ses réponses probables, et place ceux qui restent sur les caméras libres selon leur temps de parole. Il n’envoie « mapping » que s’il ne peut pas du tout calculer de proposition (par exemple parce qu’un proxy a échoué). | Les pipelines entièrement automatiques, qui préfèrent un montage deviné à un job bloqué. |
« Sûr de chaque intervenant » veut dire : tous ceux qui ont au moins une minute de parole sont sur une caméra à laquelle WizCut a répondu avec une confiance high. Les caméras dont il n’est pas sûr n’ont aucun intervenant, donc le montage ne coupe pas vers elles. Corrige ça dans l’éditeur si tu veux qu’elles servent.
Prépare-toi à ce que « confident » fasse intervenir une personne assez souvent. Il se retient sur les rushes où le mouvement ne suit pas un seul intervenant : plateaux TV avec flux commutés, événements, caméras à l’épaule ou pilotées. Il lui faut aussi environ 20 minutes de conversation pour être sûr, donc les clips courts finissent en général en « mapping ». Dans nos tests jusqu’ici, WizCut n’a jamais mis un intervenant sur la mauvaise caméra quand il disait être sûr, mais l’échantillon reste petit.
Combinés avec review: false, "confident" et "always" permettent à un job de se rendre sans que personne le regarde. C’est le but pour les pipelines automatiques ; si tu veux qu’une personne voie chaque montage, garde review: true.
La camera map
La proposition est sur le job sous camera_map (et dans le webhook « mapping » sous cameraMap). Elle vaut null tant qu’elle n’est pas calculée, soit quelques minutes après la fin des proxys. En voilà une pour une émission à deux, avec un gros plan de chaque personne et un plan à deux :
{
"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 }
}
]
}
Par caméra :
| Champ | Description |
|---|---|
sourceId | Une des sources vidéo du job. |
kind | Ce que montre la caméra : closeup (une personne), twoshot (deux personnes côte à côte), wide (trois personnes), multi (plusieurs personnes, l’une après l’autre : en général une caméra pilotée ou commutée) ou unknown. |
confidence | high (WizCut est sûr), low (une réponse probable, pas certaine) ou none (aucune réponse). |
speakers | Qui la caméra montre. Vide quand confidence vaut none. Pour les plans à deux et les plans larges, de gauche à droite. |
positions | Plans à deux et plans larges uniquement : qui est à left, middle et right du cadre. |
reason | Vaut no_motion quand une caméra n’a pas pu être analysée du tout. |
z, lagErrorS | Chiffres de diagnostic par intervenant : à quel point le mouvement de la caméra suit la parole de cette personne, et de combien de secondes la meilleure correspondance est décalée. Pratique pour déboguer, pas quelque chose sur quoi bâtir. |
Au niveau supérieur :
| Champ | Description |
|---|---|
speakers | Les intervenants que WizCut a jugés : tous ceux qui ont au moins une minute de parole. |
unassignedSpeakers | Intervenants jugés qui ne sont sur aucune caméra high. Si la liste n’est pas vide, « confident » laisse la décision à une personne. |
droppedSpeakers | Intervenants avec trop peu de parole pour être jugés, en général une étiquette parasite ou une courte interjection. WizCut ne les place sur aucune caméra. |
Pour accepter la proposition telle quelle, transforme chaque caméra de confiance en track (son sourceId et ses speakers) et envoie-le.
Mapper les intervenants via l’API
Si tu sais déjà qui est assis devant quelle caméra, ou que ton agent a vérifié la proposition, soumets le mapping toi-même pendant que le job est en statut « mapping » :
POST /api/jobs/{jobId}/tracks
{
"tracks": [
{ "sourceId": "source-uuid-1", "speakers": ["SPEAKER_00"] },
{ "sourceId": "source-uuid-2", "speakers": ["SPEAKER_01"] }
]
}
Utilise les noms d’intervenants du webhook « mapping » (ou les turns de GET /api/jobs/{jobId}) avec les IDs de tes sources vidéo. Une même caméra peut montrer plusieurs intervenants. WizCut génère alors les coupes, passe le job en « ready », envoie le webhook « ready » et, avec review: false, démarre le render. La réponse contient les nouvelles cuts.
Chaque sourceId doit être une des sources vidéo du job ; sinon tu reçois un 400 avec "code": "UNKNOWN_SOURCE". Tu peux soumettre pendant que WizCut cherche encore les caméras : le premier arrivé gagne. Si le mapping a déjà été soumis, par exemple automatiquement, tu reçois un 409 avec "code": "INVALID_STATUS".
Avancé : corriger un mapping une fois les coupes créées. Quand le job est en « ready » ou « complete », le même endpoint peut encore changer le mapping, mais il ne génère plus les coupes à ta place : envoie les cuts corrigées avec tracks (et éventuellement removedRanges), sinon tu reçois un 400 avec "code": "CUTS_REQUIRED". WizCut enregistre les deux ensemble, donc un recut ultérieur utilise le mapping corrigé. Si un bout de coupe tombe en dehors du fichier de sa caméra (parce qu’il commence plus tard ou s’arrête plus tôt), il passe sur une caméra qui a des images à ce moment-là. Les cuts de la réponse sont celles qui ont été enregistrées. Il n’envoie pas de webhook et ne lance pas de render : déclenche-en un si tu veux une nouvelle sortie. L’éditeur WizCut fait tout ça pour toi quand quelqu’un y corrige un mapping.
Suppression des silences
WizCut peut automatiquement raccourcir ou supprimer les longues pauses avant de générer les coupes. Ça se passe en premier, donc le changement de caméra est décidé sur la conversation resserrée : tu n’obtiens jamais une coupe vers une caméra qui perd immédiatement la majorité de son temps à l’écran à cause d’une pause supprimée.
Active-la avec le champ silence à la création d’un job :
{ "silence": { "mode": "tighten" } }
Modes :
| Mode | Comportement |
|---|---|
off | Garde toutes les pauses telles qu’enregistrées (par défaut si silence est absent). |
tighten | Raccourcit les longues pauses à un battement naturel (~0,7 s). Recommandé : garde à la conversation son côté humain. |
remove | Coupe les longues pauses presque entièrement, en laissant juste assez de padding pour éviter de couper des mots. |
Réglages fins optionnels (les valeurs par défaut marchent bien pour la plupart des enregistrements) :
| Champ | Défaut | Plage | Description |
|---|---|---|---|
minPauseSec | 1.5 | 0,3–10 | Seules les pauses plus longues que ça sont touchées. |
keepPauseSec | 0.7 | 0–3 | Le battement laissé à la place d’une pause resserrée (mode tighten uniquement). |
paddingSec | 0.25 | 0–1 | Marge de sécurité gardée autour de la parole à chaque intervalle supprimé. |
La détection est prudente : une pause n’est supprimée que si la détection des intervenants et une analyse de l’énergie audio s’accordent tous les deux à dire que c’est calme, donc les rires et autres moments non-parlés survivent.
L’objet job (GET /api/jobs/{jobId}) inclut removed_ranges (les intervalles supprimés en temps source, sous la forme { startMs, endMs }) en plus de cuts. Le render final saute ces intervalles ; l’éditeur de relecture les affiche comme des sections hachurées et restaurables.
Modifie ça après le traitement avec l’endpoint recut :
POST /api/jobs/{jobId}/recut
{ "silence": { "mode": "remove", "minPauseSec": 1.0 } }
Recut régénère les coupes et les intervalles supprimés à partir des intervenants déjà détectés, sans nouveau traitement, donc ça répond immédiatement avec les nouveaux cuts, removedRanges et savedMs (de combien la sortie devient plus courte). Passe { "mode": "off" } pour désactiver à nouveau la suppression des silences ; omets silence entièrement pour garder le réglage déjà enregistré du job. Pour le rythme de coupe, c’est pareil : ajoute "presetId" ("relaxed", "balanced" ou "dynamic") pour le changer, ou laisse-le de côté pour garder le rythme actuel du job.
Note sur la facturation : l’usage est mesuré en minutes d’entrée (les rushes que tu uploades), donc la suppression des silences ne change pas ce que coûte un job, elle rend juste la sortie plus resserrée.
Avancé : contrôle programmatique des coupes
Pour les pipelines entièrement automatisés qui contournent l’UI, laisse WizCut mapper les caméras ou mappe les intervenants via l’API, puis gère toi-même les coupes et le render. Ces endpoints fonctionnent tant que le job est en « ready » ou « complete » :
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" }
]
}
Ce même endpoint accepte aussi removedRanges (un tableau de { startMs, endMs }) pour éditer directement les intervalles de suppression de silences, par exemple pour restaurer une pause que la passe automatique a supprimée. Tu peux envoyer cuts, removedRanges, ou les deux.
Chaque coupe doit pointer vers une des sources vidéo du job, donc une caméra. Un fichier audio n’a pas d’image : une coupe dessus te renvoie un 422 avec "code": "CUT_NOT_ON_CAMERA", et les ids en cause dans sourceIds. Les fichiers audio restent dans le son de l’épisode.
Déclencher le render :
POST /api/jobs/{jobId}/render
Marche depuis « ready », ou depuis « complete » pour relancer un render après avoir modifié les coupes. Retourne { "jobId": "uuid", "status": "rendering" }, ou un 409 avec "code": "NO_CUTS" si le job n’a aucune coupe à render, ou "code": "NO_CAMERA" s’il ne reste que des fichiers audio.
Valider l’output :
POST /api/jobs/{jobId}/approve
Ne marche qu’une fois le job « complete ». Le fait passer en « approved » et envoie le webhook « approved ».
Audio
WizCut mixe la bande-son à partir de tes fichiers audio d’origine, en pleine qualité. Par défaut, il prend les fichiers que t’as choisis pour la détection des voix, tels qu’enregistrés. Deux choses changent ça.
Le volume. Passe loudness quand tu lances le rendu :
POST /api/jobs/{jobId}/render
{ "loudness": "podcast" }
"original" laisse le niveau tel qu’enregistré (par défaut), "podcast" amène l’épisode à −16 LUFS, "youtube" à −14 LUFS, avec des crêtes sous −1 dBTP dans les deux cas. C’est un seul gain pour tout l’épisode, donc les passages calmes et forts gardent leur équilibre. Sans ce champ, le job garde son dernier choix. Pour fixer le choix sans lancer de rendu, envoie { "loudness": "podcast" } à PUT /api/jobs/{jobId}/audio-mix (plus bas) ; l’éditeur le fait dès que tu choisis un niveau. Le champ output_loudness du job dit à quel volume le dernier rendu est sorti.
Le mix. Pour le lire :
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 montre chaque fichier comme le prochain rendu le joue : s’il est dans le mix et son gainDb final (balanceDb venant de « Équilibrer les voix », plus ton propre levelDb). speaker dit à qui est le micro ; WizCut le déduit des niveaux après la détection des voix. centered vaut true quand la gauche et la droite d’un fichier n’avaient pas le même son (un micro d’un seul côté, ou un de chaque côté) : WizCut joue alors les deux canaux des deux côtés, pour que personne ne se retrouve dans une seule oreille. C’est réglé automatiquement pendant le traitement.
role dit ce que le fichier entend, d’après ses niveaux après la détection des intervenants : own (le micro d’une personne, 6 dB ou plus au-dessus de tous les autres pour elle), group (quelques personnes à peu près au même niveau) ou everyone (un micro d’ambiance ou un plan large). Un speechToNoiseDb sous 15 sonne bruyant. Tant que tu ne règles rien (usingDefault), le mix est defaultMix, choisi selon le rôle : le micro de chacun, un par personne, parmi tous tes fichiers, baissé entre les prises de parole (ownMics) ; sinon, parmi tes diarizeSourceIds, si chaque piste choisie entend tout le monde, la plus propre seule (cleanest) ; sinon ta sélection telle quelle (picks). Une piste que tu laisses de côté dans tracks lors d’un PUT revient à ce réglage par défaut.
Pour le modifier :
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 }
}
}
Seuls les champs que t’envoies changent. duck est fusionné champ par champ ; tracks remplace toute la liste par piste, donc envoie chaque piste que tu veux régler.
| Champ | Effet |
|---|---|
balance | Équilibrer les voix : remonte les micros plus faibles au niveau du plus fort (un gain par piste, +18 dB max). |
duck.enabled | Baisse chaque micro quand sa personne ne parle pas, pour que les autres voix qu’il capte ne rendent pas le mix creux. Réglages fins : depthDb (−40 à −3, −12 par défaut), fadeMs (20–1000, 150 par défaut) et padMs (0–1000, 250 par défaut : combien de temps avant la prise de parole il s’ouvre). |
tracks.<sourceId>.gainDb | Ton niveau pour ce fichier, de −24 à +12 dB, en plus de « Équilibrer les voix ». |
tracks.<sourceId>.muted | true retire le fichier de la bande-son. |
tracks.<sourceId>.speaker | À qui est le micro : un label de voix, ou null pour personne (micro d’ambiance ou caméra, jamais baissé). Laisse-le de côté pour garder l’estimation de WizCut. |
Ça marche dans n’importe quel statut. Le mix s’applique au prochain rendu : rappelle l’endpoint de rendu pour l’entendre dans la vidéo. Un champ mal formé, ou un speaker qui n’existe pas dans l’épisode, renvoie 400 avec "code": "INVALID_AUDIO_MIX".
Réponses d’erreur
Tous les endpoints retournent les erreurs dans ce format :
{ "error": "Description of what went wrong" }
Certaines erreurs incluent aussi un code exploitable par un programme :
| Code | HTTP | Signification |
|---|---|---|
TRACKS_ON_CREATE | 400 | POST /api/jobs a reçu un mapping des intervenants. Laisse tracks de côté et utilise autoMap, ou règle le mapping plus tard. |
FILE_TOO_LARGE | 400 | Un fichier dépasse la limite de taille, déclarée dans fileSize ou constatée une fois le fichier envoyé. maxBytes donne la limite. |
INVALID_FILE_SIZE | 400 | fileSize n’est pas un nombre entier d’octets. |
NOT_A_MEDIA_FILE | 422 | Un fichier ne peut pas être un enregistrement : un fichier de métadonnées macOS (son nom commence par ._) ou un fileSize sous 32 Ko. fileName et reason disent lequel et pourquoi. Envoie directement les fichiers caméra et audio. |
FILE_SIZE_MISMATCH | 400 | Le fichier envoyé est beaucoup plus petit ou plus gros que son fileSize. Renvoie-le. |
UNKNOWN_SOURCE | 400 | Un track nomme un sourceId qui n’est pas une des sources vidéo du job. |
CUTS_REQUIRED | 400 | Changer le mapping une fois les coupes créées demande aussi les cuts mises à jour. |
CUT_NOT_ON_CAMERA | 422 | Une coupe pointe vers autre chose qu’une source vidéo du job, par exemple un fichier audio (pas d’image). sourceIds les liste. |
NOT_ENOUGH_VIDEOS | 400 | Le job a besoin d’au moins deux sources vidéo pour être traité. |
EMPTY_MAPPING | 400 | Le mapping ne met aucun intervenant sur aucune caméra. Assigne au moins un intervenant. |
INVALID_IDEMPOTENCY_KEY | 400 | L’en-tête Idempotency-Key ne fait pas 1 à 255 caractères ASCII imprimables. |
URL_NOT_ALLOWED | 400 | Import depuis un lien : ce n’est pas un lien https:// public. |
NOT_A_FILE | 400 | Import depuis un lien : une page YouTube ou Vimeo, pas un fichier. |
QUOTA_EXCEEDED | 403 | Tu as épuisé tes minutes. |
SOURCES_PENDING | 409 | /process a été appelé alors que des fichiers sont encore en cours d’upload ou d’import, ou que l’import d’un fichier a échoué. pendingSourceIds les liste (importingSourceIds et importFailedSourceIds disent lesquels sont des imports) : termine ces uploads, et retire les fichiers dont l’import a échoué. |
INVALID_STATUS | 409 | Le statut du job ne permet pas cette action, par exemple parce que son mapping a déjà été soumis. |
NO_CUTS | 409 | Il n’y a aucune coupe à render. |
NO_CAMERA | 409 | Le job n’a plus de source vidéo, que des fichiers audio : il n’y a pas d’image à render. |
SOURCES_DELETED | 409 | Les fichiers d’origine du job ont été supprimés : on ne les garde que pour une durée limitée, selon le plan. Ouvre-le dans l’éditeur, renvoie les mêmes fichiers, puis relance le render. |
NOT_RENDERED | 409 | Il n’y a pas encore de vidéo terminée : downloadUrl marche dès que le job est complete ou approved. |
IDEMPOTENCY_IN_PROGRESS | 409 | Une requête avec le même Idempotency-Key est encore en cours de traitement. Retente dans un instant. |
IDEMPOTENCY_KEY_REUSED | 409 | Le job (ou le fichier importé) créé avec cet Idempotency-Key a été supprimé. Prends une nouvelle clé. |
JOB_FULL | 409 | Import depuis un lien : le job a déjà 12 fichiers. |
IDEMPOTENCY_KEY_MISMATCH | 422 | Cet Idempotency-Key a déjà servi avec un corps de requête différent. |
TOO_MANY_IMPORTS | 429 | Import depuis un lien : 6 imports tournent déjà dans ce job. Attends le temps indiqué par Retry-After. |
IMPORT_RATE_LIMITED | 429 | Import depuis un lien : 20 imports sur la dernière heure. Attends le temps indiqué par Retry-After, ou envoie les fichiers. |
IMPORT_UNAVAILABLE | 503 | L’import depuis un lien n’est pas disponible pour le moment. Envoie plutôt le fichier. |
Codes HTTP courants :
| Code | Signification |
|---|---|
| 400 | Requête invalide (par exemple moins de deux sources vidéo au moment du traitement) |
| 401 | Clé API manquante ou invalide |
| 403 | Quota dépassé, ou l’upload appartient à un autre compte |
| 404 | Job introuvable ou qui ne t’appartient pas |
| 409 | Transition de statut invalide (ex. render d’un job qui n’est pas « ready »), ou requête avec le même Idempotency-Key encore en cours |
| 422 | Un Idempotency-Key réutilisé avec un corps de requête différent |
| 429 | Trop d’imports depuis un lien en même temps, ou sur la dernière heure |
| 500 | Erreur serveur |
| 502 | Un service de traitement a rejeté le job ou n’a pas réussi à démarrer |
| 503 | Service indisponible |
Déroulement complet
Voilà le chemin nominal complet pour un agent IA ou une automatisation :
# 1. Créer un job avec deux caméras (fichiers jusqu'à 5 Go chacun,
# passe fileSize pour obtenir des uploads multipart au-delà, jusqu'à 100 Go)
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. Envoyer les fichiers vidéo vers les URL présignées
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. Lancer le traitement
curl -s -X POST "https://wizcut.com/api/jobs/$JOB_ID/process" \
-H "Authorization: Bearer wc_live_your_key"
# 4. Attendre le prochain webhook. Avec l'autoMap par défaut ("confident") :
# - { status: "ready", reviewUrl: "..." } : WizCut a mappé les caméras tout seul
# - { status: "mapping", reviewUrl: "...", speakers: [...], cameraMap: {...} }
# : il n'était pas sûr. Envoyer quelqu'un sur la reviewUrl pour confirmer les caméras
# (ou envoyer le mapping toi-même en POST vers /api/jobs/$JOB_ID/tracks)
# 5. La personne relit et retouche les coupes → clique sur Render dans l'éditeur
# Attendre le webhook : { status: "complete", outputUrl: "..." }
# 6. Télécharger la vidéo rendue depuis outputUrl
Entièrement automatique (autoMap: "always", review: false) :
# Comme ci-dessus, mais avec "autoMap": "always" et "review": false à l'étape 1
# WizCut mappe les caméras lui-même, même quand il n'est pas sûr,
# et lance le render juste après, sans aucune intervention humaine
# Tu reçois : { status: "ready", ... }, puis { status: "complete", outputUrl: "..." }
Intégrations
Tu préfères éviter le code ? Tu peux piloter l’API WizCut depuis des plateformes d’automatisation sans écrire aucune des requêtes ci-dessus.
n8n
On maintient une intégration n8n officielle avec le nœud communautaire vérifié @wizcut/n8n-nodes-wizcut. Installe-le depuis Settings → Community Nodes dans n8n (il est vérifié, donc disponible sur n8n Cloud aussi).
Il embarque deux nœuds :
- WizCut : actions pour Create Job, Get Job, Start Processing, Start Render et Approve.
- WizCut Trigger : un déclencheur webhook qui lance ton workflow à chaque changement de statut d’un job (mapping, ready, complete, approved).
Les nœuds n’importent pas encore depuis un lien : pour des fichiers déjà dans un drive en ligne, ajoute-les avec un nœud HTTP Request, comme décrit dans Importer des fichiers depuis un lien.
Pointe l’URL webhook du trigger vers le callbackUrl de ton job et tu obtiens un pipeline entièrement événementiel : ping Slack quand WizCut a besoin que quelqu’un confirme qui est sur quelle caméra, démarrage automatique du render quand les coupes sont prêtes, envoi du lien de téléchargement quand l’épisode est terminé. Les deux nœuds fonctionnent aussi comme outils pour les agents IA n8n.
Tu veux démarrer vite ? Récupère le template prêt à l’emploi : Suis et gère le statut de montage de tes podcasts avec WizCut et Slack.
Plus de plateformes
Des intégrations Make.com et Zapier sont dans la roadmap. Tu bosses sur une autre plateforme, ou tu veux un template de workflow pour ta config précise ? Contacte le support WizCut. Les demandes de fonctionnalités sont les bienvenues.