bgless.videobgless.video

API

Autenticación

Base URL:

https://api.bgless.video/v1

Los puntos finales de migración no compatibles con Screen están disponibles en:

https://api.bgless.video/v1.0/videos

Utilice una clave API de /settings/apikeys.

Authorization: Bearer sk_...

También se acepta X-Api-Key.

Las claves API pueden tener opcionalmente una etiqueta de proyecto y una cuota de crédito mensual. Cuando una clave excede su cuota, la creación de empleo devuelve "429 rate_limited" antes de enviar el trabajo del proveedor.

Los créditos se reservan cuando se crea un trabajo. Los trabajos RGBA fallidos o cancelados restauran el saldo reservado y escriben una entrada de crédito de "reembolso" para el historial de auditoría.

Subir

Solicite una carga prefirmada URL:

curl -X POST https://api.bgless.video/v1/uploads \
  -H "Authorization: Bearer $BGLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "input.mp4",
    "contentType": "video/mp4",
    "sizeBytes": 123456
  }'

Respuesta:

{
  "data": {
    "uploadUrl": "https://storage.example.com/presigned-put-url",
    "fileUrl": "https://cdn.example.com/uploads/source/file.mp4",
    "method": "PUT",
    "headers": {
      "Content-Type": "video/mp4"
    },
    "fileUrlExpiresAt": "2026-05-08T12:00:00.000Z",
    "sizeBytes": 123456,
    "uploaded": false,
    "directUpload": true
  }
}

Luego cargue el archivo con PUT a data.uploadUrl usando los encabezados devueltos. Utilice data.fileUrl al crear un trabajo. Las URL de archivos R2 del mismo origen están firmadas y caducan después de 24 horas.

Para archivos ya alojados, envíe { "url": "https://example.com/input.mp4" } y use la fileUrl devuelta.

Estimar trabajo

Calcule los créditos, la ETA y el saldo actual antes de enviar el trabajo del proveedor. Este punto final no crea un trabajo y no gasta KIE créditos.

curl -X POST https://api.bgless.video/v1/jobs/estimate \
  -H "Authorization: Bearer $BGLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "mode": "text",
      "prompt": "a floating product bottle rotating slowly",
      "durationSec": 3,
      "resolution": "720p"
    },
    "options": {
      "outputs": ["webm-vp9-alpha"],
      "preset": "web-app"
    }
  }'

Respuesta:

{
  "data": {
    "provider": "kie",
    "model": "kie.kling-3-video",
    "credits": 48,
    "etaSec": 120,
    "remainingCredits": 100,
    "quota": null,
    "canAfford": true
  }
}

Para los archivos seleccionados por el navegador que aún no se han cargado, la aplicación web puede realizar estimaciones a partir del modo, la duración, la resolución, los resultados y el modelo antes de la carga directa.

Modelos

Lista de modelos públicos RGBA disponibles:

curl https://api.bgless.video/v1/models

La respuesta tiene la forma "data.providers" y "data.models". Cada modelo incluye su identificación, proveedor, nombre para mostrar, modos admitidos, capacidades y tipo de salida. Utilice la identificación del modelo devuelto como "modelo" al crear o estimar un trabajo. Los flujos de trabajo de carga de video exponen el transcodificador local como "local.ffmpeg-encoder".

SDK de nodo

La fuente del SDK de Node.js escrita reside en sdk/node y se publica como @bgless/nodo.

pnpm sdk:node:typecheck
pnpm sdk:node:build
import { createBglessClient } from '@bgless/node';

const bgless = createBglessClient({
  apiKey: process.env.BGLESS_API_KEY!,
});

const job = await bgless.createJob({
  input: {
    mode: 'video',
    videoUrl: 'https://cdn.example.com/input.mp4',
    resolution: '1080p',
  },
  options: {
    outputs: ['webm-vp9-alpha'],
    callbackUrl: 'https://example.com/webhooks/bgless',
  },
});

console.log(job.data.id, job.pollUrl);

Ejemplo de Python

El SDK de Python está previsto para después de M0. Hasta entonces, utilice "solicitudes" directamente contra el DESCANSO API.

import os
import requests

response = requests.post(
    "https://api.bgless.video/v1/jobs",
    headers={
        "Authorization": f"Bearer {os.environ['BGLESS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "input": {
            "mode": "video",
            "videoUrl": "https://cdn.example.com/input.mp4",
            "resolution": "1080p",
        },
        "options": {
            "outputs": ["webm-vp9-alpha", "mov-prores4444"],
            "callbackUrl": "https://example.com/webhooks/bgless",
        },
    },
    timeout=30,
)

response.raise_for_status()
job = response.json()["data"]
print(job["id"], job["status"])

Crear trabajo

curl -X POST https://api.bgless.video/v1/jobs \
  -H "Authorization: Bearer $BGLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "mode": "video",
      "videoUrl": "https://cdn.example.com/input.mp4",
      "resolution": "1080p",
      "refineEdges": true
    },
    "options": {
      "outputs": ["webm-vp9-alpha", "mov-prores4444"],
      "preset": "web-app",
      "callbackUrl": "https://example.com/webhooks/bgless",
      "callbackSecret": "replace-with-your-secret"
    }
  }'

La respuesta es "202 Aceptada" con un trabajo en cola y "pollUrl".

/api/v1/alpha-videos es un alias de /api/v1/jobs para clientes que prefieren el nombre de recurso alpha-video.

Los valores de salida admitidos son webm-vp9-alpha, mov-prores4444, animated-webp, gif, apng, png-sequence y matte-grayscale-mp4.

Compatibilidad sin pantalla

Para migraciones desde la forma Unscreen API anterior, use X-Api-Key y POST /v1.0/videos con video_url o video_file.

curl -X POST https://api.bgless.video/v1.0/videos \
  -H "X-Api-Key: $BGLESS_API_KEY" \
  -F "video_url=https://cdn.example.com/input.mp4" \
  -F "format=pro_bundle" \
  -F "webhook_url=https://example.com/webhooks/unscreen"

La capa de compatibilidad asigna pro_bundle a bgless WebM alpha más un MP4 mate alpha, devuelve respuestas data.type = "video" estilo Unscreen y admite GET /v1.0/videos/:id y DELETE /v1.0/videos/:id.

Para trabajos cortos, puede solicitar espera síncrona limitada:

curl -X POST "https://api.bgless.video/v1/jobs?wait=true&timeout=30" \
  -H "Authorization: Bearer $BGLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

API devuelve 200 cuando el trabajo alcanza un estado de terminal dentro del tiempo de espera. Todavía devuelve 202 con pollUrl cuando el trabajo todavía está en cola, procesándose o transcodificando.

Para flujos de trabajo de video cargados, auto, preserve-source-alpha, chroma-key y ai-matting se dirigen al transcodificador local (local.ffmpeg-encoder) de forma predeterminada y no envían una tarea de generación KIE. Las estimaciones y creaciones explícitas de "ai-matting" se bloquean antes de la creación del trabajo hasta que el transcodificador informe sobre un proveedor de matting configurado.

Consulta de trabajo

curl https://api.bgless.video/v1/jobs/job_id \
  -H "Authorization: Bearer $BGLESS_API_KEY"

Los trabajos transcodificados exitosos incluyen outputAssets, previewAssets para vistas previas de tablero de ajedrez/oscuro/claro y qaReport. Los artefactos de control de calidad JSON también se enumeran en previewAssets con kind: "qa".

Estados:

  • en cola
  • enviado
  • procesamiento
  • transcodificación
  • éxito
  • fallido
  • cancelado

Descargar

curl -L "https://api.bgless.video/v1/jobs/job_id/download?format=webm-vp9-alpha" \
  -H "Authorization: Bearer $BGLESS_API_KEY"

Eliminar

curl -X DELETE https://api.bgless.video/v1/jobs/job_id \
  -H "Authorization: Bearer $BGLESS_API_KEY"

Al eliminar un trabajo en ejecución, primero se cancela y luego se oculta del historial de trabajos. Para los activos respaldados por R2, la eliminación también hace el mejor esfuerzo para eliminar los objetos de fuente, salida, vista previa y control de calidad almacenados.

Ganchos web

Cuando se configura options.callbackUrl, los trabajos de terminal se envían al webhook del usuario. Si se configura options.callbackSecret, la entrega incluye:

X-Bgless-Signature: t=unix_timestamp,v1=hmac_sha256(secret, t + "." + body)

Los eventos son job.completed, job.failed y job.canceled.

Los webhooks del proveedor de KIE deben apuntar a:

https://bgless.video/api/v1/webhooks/kie

Configure KIE_WEBHOOK_HMAC_KEY en producción.

On this page

Autenticación
Subir
Estimar trabajo
Modelos
SDK de nodo
Ejemplo de Python
Crear trabajo
Compatibilidad sin pantalla
Consulta de trabajo
Descargar
Eliminar
Ganchos web