Videos per API hochladen: curl, Python, Node.js, WebDAV und FTP

Sie können ein Video zu UFOLOAD bringen, ohne jemals das Dashboard zu öffnen. Die REST API nimmt Uploads über HTTPS entgegen, der Server kann eine Datei für Sie von einem Link abholen, und dasselbe Konto ist über WebDAV und FTP für Werkzeuge erreichbar, die diese Protokolle bereits sprechen. Diese Anleitung geht alle fünf Wege mit funktionierenden Befehlen durch, erklärt, was der Server antwortet, und zeigt, wie Sie auf das Ende der Kodierung warten. Die Endpunkte unten wurden mit der öffentlichen OpenAPI-Spezifikation abgeglichen; die vollständige Referenz steht in der API-Dokumentation.

API-Schlüssel erstellen

Erstellen Sie einen Schlüssel im Bereich „Entwickler“ Ihres Dashboards. Jede Anfrage trägt ihn als Bearer-Token im Header Authorization. Der Schlüssel wird nur einmal bei der Erstellung angezeigt – speichern Sie ihn also in einer Umgebungsvariable oder einem Secrets-Manager und widerrufen Sie ihn im Dashboard, falls er nach außen gelangt. Derselbe Schlüssel dient als Passwort für WebDAV und FTP, mit der E-Mail-Adresse Ihres Kontos als Login. Wenn Sie noch kein Konto haben, erstellen Sie ein kostenloses; die Preisseite nennt die Dateigrößengrenze sowie die Speicher- und Traffic-Kontingente Ihres Tarifs.

export UFOLOAD_API_KEY="ufo_..."

Upload mit curl

Der einfachste Upload sendet die Datei als rohen Request-Body und schreibt ihren Namen in den Header X-File-Name. Senden Sie den Namen prozentkodiert (UTF-8), wenn er Leerzeichen oder Nicht-ASCII-Zeichen enthält. Standardmäßig landet die Datei im Stammordner; mit ?folder_id= oder einem Header X-Folder-Id wählen Sie einen anderen.

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

Ein Multipart-Formular funktioniert ebenfalls. Die Datei kommt in das Feld file, und der Ordner kann als Formularfeld folder_id angegeben werden:

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

Ein erfolgreicher Upload antwortet mit 201 und einem JSON-Body, der das Dateiobjekt enthält. Die Felder, die Sie am häufigsten brauchen, sind id, public_id (der kurze Code für Player-Adressen), status, duration_ms und max_quality. Für Inhalte, die er bereits hat, belegt der Server keinen zusätzlichen Platz: Laden Sie dieselben Bytes erneut hoch, antwortet er mit 200, der vorhandenen Datei und "duplicate": true, wobei Dateien anhand ihres SHA-256-Hashes abgeglichen werden.

Warten, bis das Video fertig ist

Das Hochladen ist nur die erste Hälfte. Danach wird die Datei eingereiht und in eine adaptive HLS-Leiter kodiert (siehe wie die Leiter aufgebaut ist). Ihr status durchläuft uploading, queued und processing und endet bei ready oder failed; eine fehlgeschlagene Datei enthält eine Meldung in error. Fragen Sie die Datei alle paar Sekunden ab, niemals in einer engen Schleife: Die API hat ein Rate-Limit und antwortet mit 429.

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

Die Antwort besteht aus zwei Teilen: file mit den Metadaten und links mit signierten Adressen für die Master-Playlist (playback), das Titelbild (poster), das Sprite für Hover-Vorschauen (sprite), jede Variante sowie expires_at. Brauchen Sie eine andere Gültigkeit, stellt POST /files/{id}/links Links mit einer Gültigkeit von 60 Sekunden bis 30 Tagen aus, optional gebunden an eine IP-Adresse oder ein Cookie.

Python

Mit der Bibliothek requests wird das geöffnete Dateiobjekt direkt von der Festplatte gestreamt, sodass der Speicherverbrauch auch bei großen Videos konstant bleibt. Die Funktion unten lädt hoch und wartet dann auf das Ergebnis.

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 ab Version 18 hat fetch eingebaut, Abhängigkeiten sind also nicht nötig. Diese Version liest die Datei in den Arbeitsspeicher, was für Clips und kurze Videos in Ordnung ist; für Dateien mit mehreren Gigabyte nehmen Sie besser curl, WebDAV oder FTP, die von der Festplatte 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)

Import per URL

Liegt das Video bereits unter einem direkten Link online, lassen Sie den Server es herunterladen, statt es auf Ihren Rechner zu holen und wieder hochzuschieben. Der Aufruf antwortet sofort mit 202 und einer Importaufgabe; der Server holt die Datei und reiht sie dann zur Kodierung ein. Links in interne Netze, auf Loopback und auf Service-Adressbereiche werden abgelehnt, Sie können bis zu zehn aktive Importe haben, und GET /files/import zeigt den Fortschritt.

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

Für Massenübertragungen und für Werkzeuge, die keine API aufrufen können, ist dieselbe Bibliothek über WebDAV und FTP erreichbar. Der Login ist die E-Mail-Adresse Ihres Kontos, das Passwort ein API-Schlüssel. Beide streamen von der Festplatte und sind die robusteste Option für sehr große Dateien.

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/

Nutzen Sie die verschlüsselten Varianten, wann immer Ihr Client sie unterstützt, denn der API-Schlüssel ist das Passwort. Jeder Client, der WebDAV oder FTPS spricht, vom Dateimanager bis zum Sync-Tool, kann dieselben Zugangsdaten nutzen. Auf diesem Weg kopierte Dateien erscheinen in Ihrer Bibliothek und werden wie jeder andere Upload kodiert.

Welchen Weg Sie wählen sollten

Das Video verwenden

Sobald der Status ready ist, lautet die Player-Adresse https://iframe.andromedans.live/e/ gefolgt von public_id – genau das, was Sie in ein iframe einsetzen (die lange id funktioniert ebenfalls und wird auf die kurze Adresse umgeleitet); die Anleitung zum Einbetten zeigt das Markup und die Alternative mit hls.js. Mit Domain- und Länderregeln können Sie einschränken, wo es abgespielt wird, und – sofern Werbung verfügbar ist – sie aktivieren, um an Aufrufen zu verdienen. Halten Sie den Schlüssel aus dem Browser-Code heraus, tauschen Sie ihn aus, wenn Personen Ihr Team verlassen, und denken Sie daran, dass die API in jedem Tarif verfügbar ist – Sie können also noch heute loslegen.