Video-Hintergrund mit JavaScript und Node.js entfernen

JavaScript eignet sich gut, um Video-Hintergrunde automatisiert zu entfernen. Statt jeden Clip manuell hochzuladen, senden Sie ein Video aus Node.js, lassen Unscreen es verarbeiten und laden das Ergebnis in einem Script, Backend, Worker oder Content-Workflow herunter.

Dieser Guide zeigt die Nutzung von @unscreen/video-background-remover von der Installation bis zu zwei typischen Produktionsmustern:

• mit wait auf das fertige Ergebnis warten
• ohne Warten absenden und das Ergebnis per Webhook erhalten

1. SDK installieren

Das Paket ist als npm Node.js-Bibliothek fur Node.js 20 oder neuer veroffentlicht.

npm install @unscreen/video-background-remover

Setzen Sie Ihren API-Key als Umgebungsvariable:

export UNSCREEN_API_KEY="ihr_api_key"

In Produktion gehort dieser Wert in Server-Secrets, Hosting-Variablen, CI-Secrets oder Container-Secrets. Er darf nicht in Browser-JavaScript landen.

2. Client erstellen

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

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

Den Client konnen Sie in Ihren serverseitigen Job-Funktionen wiederverwenden.

3. Schnellster Weg mit wait

removeBackground ist die bequemste Methode. Ohne webhookUrl wartet sie standardmassig, bis der Job abgeschlossen ist.

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("Gespeichert als ./output.mp4");

Der Ablauf erstellt den Job, laedt das lokale Video hoch, startet die Verarbeitung, wartet auf den finalen Status und schreibt das fertige Video.

Die Option mode akzeptiert auto oder human_only. Verwenden Sie auto, wenn Unscreen das Vordergrundmotiv automatisch erkennen soll, und human_only, wenn der Clip nur Personen als Vordergrund behandeln soll.

4. Manuelles Polling mit "jobs.wait"

Wenn Sie die Schritte getrennt steuern wollen, nutzen Sie jobs.submit, jobs.wait und 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 gestartet: ${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 fragt den Status ab, bis der Job completed oder failed ist. Bei Fehlern wirft das SDK eine UnscreenError, bei Zeituberschreitung eine UnscreenTimeoutError.

5. Remote-Video statt lokaler Datei

input akzeptiert lokale Pfade, HTTP(S)-URLs, Blob, ArrayBuffer und Uint8Array.

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

Wenn die URL keinen klaren Video-Content-Type liefert, setzen Sie ihn manuell:

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

6. Verschiedene Ergebnisdateien herunterladen

Standard ist outputVideo. Je nach Job konnen weitere Assets verfugbar sein:

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

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

Unterstutzte Assets:

• outputVideo
• alphaVideo
• mask
• previewImage
• metadata

7. Ohne wait per Webhook arbeiten

In Web-Apps sollten HTTP-Requests nicht so lange offen bleiben, bis ein Video fertig verarbeitet ist. Geben Sie stattdessen eine webhookUrl an.

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} gestartet; Ergebnis kommt per Webhook`);

Mit webhookUrl wartet removeBackground nicht, ausser Sie setzen explizit wait: true.

8. Webhook in Node.js empfangen

Minimalbeispiel mit 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 abgeschlossen: ${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 fehlgeschlagen: ${event.jobId}`);
  }

  res.sendStatus(200);
});

app.listen(3000);

Speichern Sie in einer echten App den jobId beim Absenden. Wenn der Webhook eintrifft, aktualisieren Sie den zugehorigen Datenbankeintrag.

9. Webhook-Event typisieren

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(`Unscreen-Job fehlgeschlagen: ${event.jobId}`);
  }
}

Die Event-Namen sind video.completed und video.failed.

10. wait trotz Webhook erzwingen

Wenn Sie Webhook und synchrones Ergebnis zusammen brauchen, setzen Sie 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);

Das ist fur interne Tools hilfreich. Fur Nutzer-Apps ist der Webhook ohne Warten meistens robuster.

11. Credits vor Batch-Jobs prufen

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

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

Prufen Sie Credits, bevor Sie viele Videos in eine Queue legen.

12. Fehler behandeln

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("Der Job lauft weiter. Status spaeter erneut prufen.");
  } else if (error instanceof UnscreenError) {
    console.error(error.message);
  } else {
    throw error;
  }
}

Kurz gesagt: wait ist ideal fur Skripte und kontrollierte Worker. Webhooks sind besser fur Apps, lange Videos und asynchrone Nutzer-Workflows.