Caricare video tramite API: curl, Python, Node.js, WebDAV e FTP

Puoi mettere un video su UFOLOAD senza mai aprire la dashboard. La REST API accetta caricamenti via HTTPS, il server può scaricare un file da un link al posto tuo e lo stesso account è raggiungibile via WebDAV e FTP per gli strumenti che già parlano quei protocolli. Questa guida percorre tutte e cinque le strade con comandi funzionanti, spiega cosa risponde il server e mostra come attendere la fine della codifica. Gli endpoint qui sotto sono stati verificati sulla specifica OpenAPI pubblica; la documentazione API contiene il riferimento completo.

Crea una chiave API

Crea una chiave nella sezione Sviluppatori della dashboard. Ogni richiesta la trasmette come bearer token nell'intestazione Authorization. La chiave viene mostrata una sola volta al momento della creazione, quindi salvala in una variabile d'ambiente o in un gestore di segreti e revocala dalla dashboard se viene divulgata. La stessa chiave funziona come password per WebDAV e FTP, con l'email del tuo account come nome utente. Se non hai ancora un account, creane uno gratuito; la pagina dei prezzi elenca il limite di dimensione dei file e le quote di spazio e traffico del tuo piano.

export UFOLOAD_API_KEY="ufo_..."

Caricare con curl

Il caricamento più semplice invia il file come corpo grezzo della richiesta e ne mette il nome nell'intestazione X-File-Name. Invia il nome con codifica percentuale (UTF-8) se contiene spazi o caratteri non ASCII. Per impostazione predefinita il file finisce nella cartella principale; aggiungi ?folder_id= o un'intestazione X-Folder-Id per sceglierne un'altra.

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

Funziona anche un modulo multipart. Il file va nel campo file e la cartella può essere indicata con un campo del modulo folder_id:

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

Un caricamento riuscito risponde 201 con un corpo JSON che contiene l'oggetto file. I campi che userai più spesso sono id, public_id (il codice breve che va negli indirizzi del player), status, duration_ms e max_quality. Il server non occupa spazio aggiuntivo per contenuti che ha già: se carichi di nuovo gli stessi byte, risponde 200 con il file esistente e "duplicate": true, confrontando i file tramite il loro hash SHA-256.

Attendi che il video sia pronto

Il caricamento è solo la prima metà. Dopo, il file viene messo in coda e codificato in una scala HLS adattiva (vedi come viene costruita la scala). Il suo status passa per uploading, queued e processing e termina con ready o failed; un file non riuscito contiene un messaggio error. Interroga il file ogni pochi secondi e mai in un ciclo serrato: l'API ha limiti di frequenza e risponde 429.

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

La risposta ha due parti: file con i metadati e links con gli indirizzi firmati per la master playlist (playback), la copertina (poster), lo sprite per le anteprime al passaggio del mouse (sprite), ogni rendition e expires_at. Se ti serve una durata diversa, POST /files/{id}/links genera link validi da 60 secondi a 30 giorni, facoltativamente legati a un indirizzo IP o a un cookie.

Python

Con la libreria requests, passando l'oggetto file aperto lo si trasmette in streaming dal disco, così l'uso di memoria resta costante anche con video grandi. La funzione qui sotto carica il file e poi attende il risultato.

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 e versioni successive hanno fetch integrato, quindi non servono dipendenze. Questa versione legge il file in memoria, il che va bene per clip e video brevi; per file di diversi gigabyte preferisci curl, WebDAV o FTP, che trasmettono in streaming dal 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)

Importare da URL

Se il video è già online a un link diretto, lascia che sia il server a scaricarlo invece di trasferirlo sul tuo computer e poi ricaricarlo. La chiamata restituisce subito 202 con un'attività di importazione; il server scarica il file e poi lo mette in coda per la codifica. I link a reti interne, loopback e intervalli di indirizzi di servizio vengono rifiutati, puoi avere fino a dieci importazioni attive e GET /files/import mostra l'avanzamento.

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 e FTP

Per i trasferimenti in blocco e per gli strumenti che non possono chiamare un'API, la stessa libreria è disponibile via WebDAV e FTP. Il nome utente è l'email del tuo account e la password è una chiave API. Entrambi trasmettono in streaming dal disco e sono l'opzione più robusta per i file molto grandi.

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 le varianti cifrate ogni volta che il tuo client le supporta, dato che la chiave API è la password. Qualsiasi client che parli WebDAV o FTPS, dai file manager agli strumenti di sincronizzazione, può usare gli stessi dati. I file copiati in questo modo compaiono nella tua libreria e vengono codificati come qualsiasi altro caricamento.

Quale strada scegliere

Usare il video

Quando lo stato è ready, l'indirizzo del player è https://iframe.andromedans.live/e/ seguito da public_id, ed è esattamente ciò che metti in un iframe (funziona anche l'id lungo, che viene reindirizzato all'indirizzo breve); la guida all'incorporamento mostra il markup e l'alternativa con hls.js. Puoi limitare dove viene riprodotto con le regole per dominio e Paese e, quando gli annunci sono disponibili, attivarli per guadagnare dalle visualizzazioni. Tieni la chiave fuori dal codice del browser, cambiala quando qualcuno lascia il tuo team e ricorda che l'API è disponibile in ogni piano, quindi puoi iniziare a sviluppare oggi stesso.