Quitar el fondo de un video con JavaScript y Node.js

JavaScript es una forma practica de automatizar la eliminacion de fondos de video. En vez de subir cada clip manualmente, puedes enviar un video desde Node.js, dejar que Unscreen lo procese y descargar el resultado desde un script, backend, worker o pipeline de contenido.

Esta guia explica como usar @unscreen/video-background-remover desde la instalacion hasta dos formas habituales de integracion:

• esperar el resultado con wait
• enviar el trabajo sin esperar y recibir el resultado por webhook

1. Instalar el SDK

El paquete esta publicado como una libreria npm de Node.js para Node.js 20 o superior.

npm install @unscreen/video-background-remover

Guarda la clave API en una variable de entorno:

export UNSCREEN_API_KEY="tu_api_key"

En produccion, configuralo como secreto del servidor, hosting, CI o contenedor. No pongas la clave API en JavaScript del navegador.

2. Crear el cliente

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

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

Reutiliza este cliente en tus rutas o workers del servidor.

3. Camino rapido con wait

removeBackground es la forma mas simple. Si no pasas webhookUrl, espera a que el trabajo termine por defecto.

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

Este flujo crea el trabajo, sube el video local, inicia el procesamiento, espera el estado final y escribe el video terminado.

La opcion mode acepta auto o human_only. Usa auto cuando Unscreen deba detectar automaticamente el sujeto en primer plano, y human_only cuando el clip deba centrarse solo en personas como primer plano.

4. Control manual con "jobs.wait"

Si necesitas mas control, separa los pasos:

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(`Trabajo iniciado: ${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 consulta el estado hasta que sea completed o failed. Si falla, el SDK lanza UnscreenError. Si excede el tiempo limite, lanza UnscreenTimeoutError.

5. Usar una URL remota

input acepta ruta local, URL HTTP(S), Blob, ArrayBuffer o Uint8Array.

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

Si la URL no devuelve un tipo de video claro, define contentType:

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

6. Descargar distintos resultados

Por defecto se descarga outputVideo, pero puedes pedir otros assets cuando esten disponibles:

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

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

Assets soportados:

• outputVideo
• alphaVideo
• mask
• previewImage
• metadata

7. Enviar sin wait usando webhook

En una app web, no conviene mantener una peticion abierta hasta que termine un video. Usa webhookUrl para recibir el resultado despues.

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(`Trabajo ${started.jobId} iniciado; esperando webhook`);

Con webhookUrl, removeBackground no espera por defecto. Solo espera si pasas wait: true.

8. Recibir el webhook en Node.js

Ejemplo minimo con 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(`Trabajo completado: ${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(`Trabajo fallido: ${event.jobId}`);
  }

  res.sendStatus(200);
});

app.listen(3000);

En produccion, guarda el jobId al enviar el trabajo y actualiza esa fila cuando llegue el webhook.

9. Tipar el evento 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(`Trabajo de Unscreen fallido: ${event.jobId}`);
  }
}

Los eventos son video.completed y video.failed.

10. Forzar wait con webhook

Si necesitas webhook y resultado sincronico, usa 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);

Esto puede servir para herramientas internas. Para apps de usuario, el webhook sin espera suele ser mas robusto.

11. Consultar creditos

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

console.log(`Creditos restantes: ${balance.credits}`);

Usalo antes de enviar muchos videos a una cola.

12. Manejar errores

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("El trabajo sigue ejecutandose. Revisa el estado despues.");
  } else if (error instanceof UnscreenError) {
    console.error(error.message);
  } else {
    throw error;
  }
}

Elige wait para scripts y workers controlados. Elige webhooks para aplicaciones, videos largos y flujos asincronos.