Video's uploaden via API: curl, Python, Node.js, WebDAV en FTP

Je kunt een video op UFOLOAD zetten zonder ooit het dashboard te openen. De REST API accepteert uploads via HTTPS, de server kan een bestand voor je ophalen via een link, en hetzelfde account is bereikbaar via WebDAV en FTP voor tools die die protocollen al spreken. Deze gids behandelt alle vijf routes met werkende commando's, legt uit wat de server antwoordt en laat zien hoe je wacht tot de codering klaar is. De endpoints hieronder zijn gecontroleerd tegen de openbare OpenAPI-specificatie; de API-documentatie bevat de volledige naslag.

Maak een API-sleutel aan

Maak een sleutel aan in het onderdeel Ontwikkelaars van je dashboard. Elk verzoek stuurt hem mee als bearer-token in de header Authorization. De sleutel wordt maar één keer getoond, bij het aanmaken, dus bewaar hem in een omgevingsvariabele of een secrets manager en trek hem in via het dashboard als hij uitlekt. Dezelfde sleutel werkt als wachtwoord voor WebDAV en FTP, met het e-mailadres van je account als gebruikersnaam. Heb je nog geen account, maak er dan gratis een aan; de prijspagina toont de maximale bestandsgrootte en de quota voor opslag en verkeer die voor je abonnement gelden.

export UFOLOAD_API_KEY="ufo_..."

Uploaden met curl

De eenvoudigste upload stuurt het bestand als ruwe request body en zet de naam in de header X-File-Name. Stuur de naam procent-gecodeerd (UTF-8) als die spaties of niet-ASCII-tekens bevat. Standaard komt het bestand in de hoofdmap terecht; voeg ?folder_id= of een header X-Folder-Id toe om een andere map te kiezen.

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

Een multipart-formulier werkt ook. Het bestand gaat in het veld file en de map kan worden opgegeven als formulierveld folder_id:

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

Een geslaagde upload antwoordt met 201 en een JSON-body met het bestandsobject. De velden die je het meest gebruikt, zijn id, public_id (de korte code die in spelersadressen komt), status, duration_ms en max_quality. De server gebruikt geen extra ruimte voor content die hij al heeft: upload je dezelfde bytes opnieuw, dan antwoordt hij met 200, het bestaande bestand en "duplicate": true, waarbij bestanden worden vergeleken op hun SHA-256-hash.

Wacht tot de video klaar is

Uploaden is pas de eerste helft. Daarna wordt het bestand in de wachtrij gezet en gecodeerd tot een adaptieve HLS-ladder (zie hoe de ladder wordt opgebouwd). De status doorloopt uploading, queued en processing en eindigt bij ready of failed; een mislukt bestand bevat een melding in error. Vraag het bestand om de paar seconden op, en nooit in een strakke lus: de API heeft een rate limit en antwoordt dan met 429.

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

Het antwoord heeft twee delen: file met de metadata en links met ondertekende adressen voor de master-playlist (playback), de omslag (poster), de sprite voor voorbeelden bij hover (sprite), elke versie en expires_at. Heb je een andere levensduur nodig, dan geeft POST /files/{id}/links links uit die 60 seconden tot 30 dagen geldig zijn, optioneel gekoppeld aan een IP-adres of een cookie.

Python

Met de bibliotheek requests wordt een geopend bestandsobject vanaf schijf gestreamd, zodat het geheugengebruik ook bij grote video's gelijk blijft. De functie hieronder uploadt en wacht daarna op het resultaat.

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 en nieuwer heeft fetch ingebouwd, dus er zijn geen afhankelijkheden nodig. Deze versie leest het bestand in het geheugen, wat prima is voor clips en korte video's; gebruik voor bestanden van meerdere gigabytes liever curl, WebDAV of FTP, die vanaf schijf streamen.

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)

Importeren via URL

Staat de video al online achter een directe link, laat de server hem dan downloaden in plaats van hem naar je eigen machine te halen en opnieuw te versturen. De aanroep antwoordt direct met 202 en een importtaak; de server haalt het bestand op en zet het daarna in de wachtrij voor codering. Links naar interne netwerken, loopback en service-adresbereiken worden geweigerd, je kunt tot tien actieve imports hebben, en GET /files/import toont de voortgang.

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

Voor bulkoverdrachten en voor tools die geen API kunnen aanroepen, is dezelfde bibliotheek beschikbaar via WebDAV en FTP. De gebruikersnaam is het e-mailadres van je account en het wachtwoord is een API-sleutel. Beide streamen vanaf schijf en zijn de robuustste optie voor zeer grote bestanden.

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/

Gebruik de versleutelde varianten waar je client dat ondersteunt, want de API-sleutel is het wachtwoord. Elke client die WebDAV of FTPS spreekt, van bestandsbeheerders tot synchronisatietools, kan dezelfde gegevens gebruiken. Bestanden die op deze manier worden gekopieerd, verschijnen in je bibliotheek en worden gecodeerd zoals elke andere upload.

Welke route kies je?

De video gebruiken

Zodra de status ready is, is het spelersadres https://iframe.andromedans.live/e/ gevolgd door public_id, precies wat je in een iframe zet (de lange id werkt ook en wordt doorgestuurd naar het korte adres); de gids over insluiten laat de markup en het alternatief met hls.js zien. Je kunt beperken waar de video speelt met regels voor domeinen en landen, en, als advertenties beschikbaar zijn, ze inschakelen om aan weergaven te verdienen. Houd de sleutel buiten browsercode, vervang hem als mensen je team verlaten en onthoud dat de API op elk abonnement beschikbaar is, zodat je vandaag nog kunt beginnen met bouwen.