Subir vídeos por API: curl, Python, Node.js, WebDAV y FTP

Puedes subir un vídeo a UFOLOAD sin abrir nunca el panel. La REST API acepta subidas por HTTPS, el servidor puede descargar un archivo desde un enlace por ti y la misma cuenta es accesible por WebDAV y FTP para las herramientas que ya usan esos protocolos. Esta guía recorre las cinco vías con comandos que funcionan, explica qué responde el servidor y muestra cómo esperar a que termine la codificación. Los endpoints de abajo se han comprobado con la especificación OpenAPI pública; la documentación de la API contiene la referencia completa.

Crea una clave de API

Crea una clave en la sección Desarrolladores de tu panel. Cada petición la lleva como token bearer en la cabecera Authorization. La clave solo se muestra una vez, al crearla, así que guárdala en una variable de entorno o en un gestor de secretos y revócala desde el panel si se filtra. La misma clave sirve como contraseña para WebDAV y FTP, con el correo de tu cuenta como usuario. Si aún no tienes cuenta, crea una gratis; la página de precios indica el límite de tamaño de archivo y las cuotas de almacenamiento y tráfico de tu plan.

export UFOLOAD_API_KEY="ufo_..."

Subir con curl

La subida más sencilla envía el archivo como cuerpo sin procesar de la petición y pone su nombre en la cabecera X-File-Name. Envía el nombre codificado en porcentaje (UTF-8) si contiene espacios o caracteres no ASCII. Por defecto, el archivo va a la carpeta raíz; añade ?folder_id= o una cabecera X-Folder-Id para elegir otra.

curl -X POST "https://ufoload.com/api/v1/files?folder_id=root" \
  -H "Authorization: Bearer $UFOLOAD_API_KEY" \
  -H "X-File-Name: holiday-2026.mp4" \
  -H "Content-Type: video/mp4" \
  --data-binary @holiday-2026.mp4

También funciona un formulario multipart. El archivo va en el campo file y la carpeta se puede indicar con un campo de formulario folder_id:

curl -X POST "https://ufoload.com/api/v1/files" \
  -H "Authorization: Bearer $UFOLOAD_API_KEY" \
  -F "file=@holiday-2026.mp4"

Una subida correcta responde 201 con un cuerpo JSON que contiene el objeto del archivo. Los campos que más usarás son id, public_id (el código corto que va en las direcciones del reproductor), status, duration_ms y max_quality. El servidor no gasta espacio adicional en contenido que ya tiene: si vuelves a subir los mismos bytes, responde 200 con el archivo existente y "duplicate": true, identificando los archivos por su hash SHA-256.

Espera a que el vídeo esté listo

La subida es solo la primera mitad. Después, el archivo entra en cola y se codifica en una escalera HLS adaptativa (consulta cómo se construye la escalera). Su status pasa por uploading, queued y processing y termina en ready o failed; un archivo fallido incluye un mensaje error. Consulta el archivo cada pocos segundos, nunca en un bucle sin pausa: la API tiene límite de peticiones y responde 429.

curl "https://ufoload.com/api/v1/files/FILE_ID" \
  -H "Authorization: Bearer $UFOLOAD_API_KEY"

La respuesta tiene dos partes: file, con los metadatos, y links, con direcciones firmadas para la lista de reproducción maestra (playback), la portada (poster), el sprite de vista previa al pasar el cursor (sprite), cada versión y expires_at. Si necesitas otra vida útil, POST /files/{id}/links emite enlaces válidos de 60 segundos a 30 días, opcionalmente vinculados a una dirección IP o a una cookie.

Python

Con la biblioteca requests, al pasar el objeto de archivo abierto se transmite desde el disco, así que el uso de memoria se mantiene estable incluso con vídeos grandes. La función de abajo sube el archivo y después espera el resultado.

import os
import time
import urllib.parse

import requests

BASE = "https://ufoload.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['UFOLOAD_API_KEY']}"}


def upload(path, folder_id="root"):
    name = urllib.parse.quote(os.path.basename(path))
    with open(path, "rb") as f:
        r = requests.post(
            f"{BASE}/files",
            params={"folder_id": folder_id},
            data=f,
            headers={**HEADERS, "X-File-Name": name, "Content-Type": "application/octet-stream"},
        )
    r.raise_for_status()
    return r.json()["file"]


def wait_ready(file_id, timeout=3600):
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{BASE}/files/{file_id}", headers=HEADERS)
        r.raise_for_status()
        data = r.json()
        status = data["file"]["status"]
        if status == "ready":
            return data
        if status == "failed":
            raise RuntimeError(data["file"].get("error") or "encoding failed")
        time.sleep(5)
    raise TimeoutError("video is still processing")


file = upload("holiday-2026.mp4")
data = wait_ready(file["id"])
print("embed:", f"https://iframe.andromedans.live/e/{file['public_id']}")
print("playlist:", data["links"]["playback"])

Node.js

Node.js 18 y posteriores incluyen fetch, así que no hacen falta dependencias. Esta versión lee el archivo en memoria, lo cual está bien para clips y vídeos cortos; para archivos de varios gigabytes es preferible curl, WebDAV o FTP, que transmiten desde el disco.

import { readFile } from 'node:fs/promises'
import { basename } from 'node:path'
import { setTimeout as sleep } from 'node:timers/promises'

const BASE = 'https://ufoload.com/api/v1'
const headers = { Authorization: `Bearer ${process.env.UFOLOAD_API_KEY}` }

async function upload(path) {
  const res = await fetch(`${BASE}/files?folder_id=root`, {
    method: 'POST',
    headers: { ...headers, 'X-File-Name': encodeURIComponent(basename(path)), 'Content-Type': 'application/octet-stream' },
    body: await readFile(path),
  })
  if (!res.ok) throw new Error(`upload failed: ${res.status}`)
  return (await res.json()).file
}

async function waitReady(id) {
  for (;;) {
    const res = await fetch(`${BASE}/files/${id}`, { headers })
    if (!res.ok) throw new Error(`status check failed: ${res.status}`)
    const data = await res.json()
    if (data.file.status === 'ready') return data
    if (data.file.status === 'failed') throw new Error(data.file.error || 'encoding failed')
    await sleep(5000)
  }
}

const file = await upload('holiday-2026.mp4')
const data = await waitReady(file.id)
console.log('embed:', `https://iframe.andromedans.live/e/${file.public_id}`)
console.log('playlist:', data.links.playback)

Importar por URL

Si el vídeo ya está en internet con un enlace directo, deja que el servidor lo descargue en lugar de bajarlo a tu equipo y volver a subirlo. La llamada devuelve 202 de inmediato con una tarea de importación; el servidor descarga el archivo y después lo pone en cola para codificarlo. Se rechazan los enlaces a redes internas, a loopback y a rangos de direcciones de servicio, puedes tener hasta diez importaciones activas y GET /files/import muestra el progreso.

curl -X POST "https://ufoload.com/api/v1/files/import" \
  -H "Authorization: Bearer $UFOLOAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/video.mp4", "name": "video.mp4"}'

WebDAV y FTP

Para transferencias masivas y para herramientas que no pueden llamar a una API, la misma biblioteca está disponible por WebDAV y FTP. El usuario es el correo de tu cuenta y la contraseña es una clave de API. Ambos transmiten desde el disco y son la opción más robusta para archivos muy grandes.

curl -u "you@example.com:$UFOLOAD_API_KEY" https://ufoload.com/dav/
curl -u "you@example.com:$UFOLOAD_API_KEY" -T holiday-2026.mp4 https://ufoload.com/dav/holiday-2026.mp4

curl -u "you@example.com:$UFOLOAD_API_KEY" ftp://ftp.ufoload.com/
curl -u "you@example.com:$UFOLOAD_API_KEY" --ftp-ssl -T holiday-2026.mp4 ftp://ftp.ufoload.com/

Usa las variantes cifradas siempre que tu cliente las admita, ya que la clave de API es la contraseña. Cualquier cliente que hable WebDAV o FTPS, desde gestores de archivos hasta herramientas de sincronización, puede usar los mismos datos. Los archivos copiados así aparecen en tu biblioteca y se codifican como cualquier otra subida.

Qué vía elegir

Usa el vídeo

Cuando el estado sea ready, la dirección del reproductor es https://iframe.andromedans.live/e/ seguida de public_id, que es exactamente lo que pones en un iframe (el id largo también funciona y redirige a la dirección corta); la guía de inserción muestra el marcado y la alternativa con hls.js. Puedes restringir dónde se reproduce con reglas de dominio y país y, cuando haya anuncios disponibles, activarlos para ganar con las visualizaciones. Mantén la clave fuera del código del navegador, cámbiala cuando alguien deje tu equipo y recuerda que la API está disponible en todos los planes, así que puedes empezar a construir hoy mismo.