Supprimer l'arriere-plan d'une video avec JavaScript et Node.js

JavaScript est un excellent choix pour automatiser la suppression d'arriere-plan video. Au lieu de traiter chaque fichier manuellement, vous pouvez envoyer une video depuis Node.js, laisser Unscreen la traiter, puis telecharger le resultat dans un script, une route backend, un worker ou une pipeline de contenu.

Ce guide montre comment utiliser @unscreen/video-background-remover depuis l'installation jusqu'aux deux flux principaux :

• attendre la fin du job avec wait
• lancer le job sans attendre et recevoir le resultat via un webhook

1. Installer le SDK

Le package est publie comme une bibliotheque npm Node.js pour Node.js 20 ou plus recent.

npm install @unscreen/video-background-remover

Ajoutez votre cle API dans l'environnement :

export UNSCREEN_API_KEY="votre_cle_api"

En production, configurez cette variable dans votre hebergeur, votre CI, vos secrets de conteneur ou votre environnement serveur. Ne publiez jamais la cle API dans du JavaScript cote navigateur.

2. Creer le client

import { Unscreen } from "@unscreen/video-background-remover";

const unscreen = new Unscreen({
  apiKey: process.env.UNSCREEN_API_KEY,
});

Vous pouvez reutiliser ce client dans les parties serveur de votre application.

3. Methode rapide avec attente

La methode removeBackground est le chemin le plus court. Sans webhookUrl, elle attend la fin du traitement par defaut.

import { Unscreen } from "@unscreen/video-background-remover";

const unscreen = new Unscreen({
  apiKey: process.env.UNSCREEN_API_KEY,
});

await unscreen.removeBackground({
  input: "./input.mp4",
  output: "./output.mp4",
  mode: "auto",
});

console.log("Fichier enregistre dans ./output.mp4");

Ce script cree le job, charge la video locale, lance le traitement, attend le statut final, puis ecrit la video de sortie.

L'option mode accepte auto ou human_only. Utilisez auto quand Unscreen doit detecter automatiquement le sujet au premier plan, et human_only quand la video doit se concentrer sur les personnes comme sujet.

4. Controle manuel avec "jobs.wait"

Si vous voulez separer les etapes, utilisez jobs.submit, jobs.wait, puis jobs.download.

import { Unscreen } from "@unscreen/video-background-remover";

const unscreen = new Unscreen({
  apiKey: process.env.UNSCREEN_API_KEY,
});

const started = await unscreen.jobs.submit({
  input: "./input.mp4",
  mode: "auto",
});

console.log(`Job lance : ${started.jobId}`);

const completed = await unscreen.jobs.wait(started.jobId, {
  intervalMs: 2000,
  timeoutMs: 10 * 60 * 1000,
});

await unscreen.jobs.download(completed, {
  asset: "outputVideo",
  path: "./output.mp4",
});

jobs.wait interroge le statut jusqu'a completed ou failed. En cas d'echec, le SDK leve une UnscreenError. En cas de depassement du temps limite, il leve une UnscreenTimeoutError.

5. Utiliser une URL video

input accepte un chemin local, une URL HTTP(S), un Blob, un ArrayBuffer ou un Uint8Array.

await unscreen.removeBackground({
  input: "https://example.com/videos/demo.mp4",
  output: "./demo-sans-fond.mp4",
  mode: "auto",
});

Si l'URL ne donne pas un type video clair, forcez le type :

await unscreen.jobs.submit({
  input: "https://example.com/download?id=123",
  contentType: "video/mp4",
});

6. Telecharger d'autres fichiers de sortie

Le fichier par defaut est outputVideo, mais vous pouvez demander d'autres assets quand ils existent :

await unscreen.jobs.download(completed, {
  asset: "alphaVideo",
  path: "./alpha.webm",
});

await unscreen.jobs.download(completed, {
  asset: "mask",
  path: "./mask.mp4",
});

Assets disponibles :

• outputVideo
• alphaVideo
• mask
• previewImage
• metadata

7. Lancer sans attendre avec un webhook

Pour une application web, garder une requete ouverte pendant le traitement n'est pas ideal. Passez un webhookUrl pour recevoir le resultat plus tard.

import { Unscreen } from "@unscreen/video-background-remover";

const unscreen = new Unscreen({
  apiKey: process.env.UNSCREEN_API_KEY,
});

const started = await unscreen.removeBackground({
  input: "./input.mp4",
  mode: "auto",
  webhookUrl: "https://example.com/api/webhooks/unscreen",
});

console.log(`Job ${started.jobId} lance ; attente du webhook`);

Avec webhookUrl, removeBackground n'attend pas par defaut. Il soumet, charge et demarre le job, puis retourne immediatement.

8. Recevoir le webhook dans Node.js

Exemple minimal avec Express :

import express from "express";
import { writeFile } from "node:fs/promises";

const app = express();

app.use(express.json());

app.post("/api/webhooks/unscreen", async (req, res) => {
  const event = req.body;

  if (event.eventType === "video.completed") {
    console.log(`Job termine : ${event.jobId}`);

    if (event.resultUrl) {
      const response = await fetch(event.resultUrl);
      const arrayBuffer = await response.arrayBuffer();

      await writeFile(
        `./downloads/${event.jobId}.mp4`,
        Buffer.from(arrayBuffer)
      );
    }
  }

  if (event.eventType === "video.failed") {
    console.error(`Job echoue : ${event.jobId}`);
  }

  res.sendStatus(200);
});

app.listen(3000);

En production, enregistrez le jobId au moment de la soumission, puis mettez a jour la ligne correspondante quand le webhook arrive.

9. Typer l'evenement webhook

import type { WebhookEvent } from "@unscreen/video-background-remover";

export async function handleUnscreenWebhook(event: WebhookEvent) {
  if (event.eventType === "video.completed") {
    console.log(event.jobId, event.resultUrl);
    return;
  }

  if (event.eventType === "video.failed") {
    console.error(`Job Unscreen echoue : ${event.jobId}`);
  }
}

Les evenements sont video.completed et video.failed.

10. Forcer wait avec un webhook

Si vous avez besoin d'un webhook et d'un resultat synchrone, ajoutez wait: true.

const completed = await unscreen.removeBackground({
  input: "./input.mp4",
  output: "./output.mp4",
  webhookUrl: "https://example.com/api/webhooks/unscreen",
  wait: true,
  waitOptions: {
    intervalMs: 3000,
    timeoutMs: 15 * 60 * 1000,
  },
});

console.log(completed.status);

Ce flux est utile pour des outils internes. Pour une application utilisateur, le webhook sans attente reste generalement le meilleur choix.

11. Verifier les credits

const balance = await unscreen.credits.getBalance();

console.log(`Credits restants : ${balance.credits}`);

Cette verification est pratique avant de lancer un lot de videos.

12. Gerer les erreurs

import {
  Unscreen,
  UnscreenError,
  UnscreenTimeoutError,
} from "@unscreen/video-background-remover";

const unscreen = new Unscreen({
  apiKey: process.env.UNSCREEN_API_KEY,
});

try {
  await unscreen.removeBackground({
    input: "./input.mp4",
    output: "./output.mp4",
    waitOptions: {
      timeoutMs: 10 * 60 * 1000,
    },
  });
} catch (error) {
  if (error instanceof UnscreenTimeoutError) {
    console.error("Le job continue. Verifiez son statut plus tard.");
  } else if (error instanceof UnscreenError) {
    console.error(error.message);
  } else {
    throw error;
  }
}

Choisissez wait pour les scripts et traitements courts. Choisissez webhook pour les applications, files d'attente et workflows ou le resultat peut arriver plus tard.