Videófeltöltés API-n: curl, Python, Node.js, WebDAV és FTP

Az UFOLOAD-ra úgy is feltölthetsz videót, hogy egyszer sem nyitod meg a vezérlőpultot. A REST API HTTPS-en fogadja a feltöltéseket, a szerver linkről is letölthet helyetted egy fájlt, ugyanaz a fiók pedig WebDAV-on és FTP-n is elérhető azoknak az eszközöknek, amelyek már ismerik ezeket a protokollokat. Ez az útmutató működő parancsokkal végigveszi mind az öt utat, elmagyarázza, mit válaszol a szerver, és megmutatja, hogyan várd meg a kódolás végét. Az alábbi végpontokat a nyilvános OpenAPI-specifikáció alapján ellenőriztük; a teljes referenciát az API-dokumentáció tartalmazza.

API-kulcs létrehozása

Hozz létre kulcsot a vezérlőpult Fejlesztők részében. Minden kérés bearer tokenként viszi az Authorization fejlécben. A kulcs csak egyszer, a létrehozásakor jelenik meg, ezért tárold környezeti változóban vagy titokkezelőben, és ha kiszivárog, vond vissza a vezérlőpultról. Ugyanez a kulcs jelszóként működik WebDAV-hoz és FTP-hez, felhasználónévként pedig a fiókod e-mail-címét használod. Ha még nincs fiókod, hozz létre egy ingyeneset; az Árak oldal felsorolja a csomagodra vonatkozó fájlméretkorlátot, valamint a tárhely- és forgalmi kvótákat.

export UFOLOAD_API_KEY="ufo_..."

Feltöltés curl-lel

A legegyszerűbb feltöltés a fájlt nyers kéréstörzsként küldi, a nevét pedig az X-File-Name fejlécbe teszi. Ha a név szóközt vagy nem ASCII karaktert tartalmaz, százalékkódolva (UTF-8) küldd. Alapértelmezés szerint a fájl a gyökérmappába kerül; másik mappa választásához add hozzá a ?folder_id= paramétert vagy egy X-Folder-Id fejlécet.

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

Multipart űrlap is működik. A fájl a file mezőbe kerül, a mappa pedig folder_id űrlapmezőként adható meg:

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

Sikeres feltöltés esetén a válasz 201, a JSON-törzs pedig a fájlobjektumot tartalmazza. A leggyakrabban használt mezők: id, public_id (a lejátszócímekbe kerülő rövid kód), status, duration_ms és max_quality. A szerver nem foglal extra helyet olyan tartalomnak, amely már megvan: ha ugyanazokat a bájtokat újra feltöltöd, 200 választ ad a meglévő fájllal és "duplicate": true értékkel, a fájlokat SHA-256 hash alapján párosítva.

Várd meg, amíg a videó elkészül

A feltöltés csak az első fele a munkának. Utána a fájl sorba kerül, és adaptív HLS-létrába kódoljuk (lásd: hogyan épül fel a létra). A status az uploading, queued és processing állapotokon halad át, és ready vagy failed értéken ér véget; a sikertelen fájlhoz error üzenet tartozik. Néhány másodpercenként kérdezd le a fájlt, soha ne szoros ciklusban: az API sebességkorlátos, és 429 kóddal válaszol.

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

A válasz két részből áll: a file a metaadatokat tartalmazza, a links pedig aláírt címeket a master playlisthez (playback), a borítóképhez (poster), a rámutatáskori előnézet sprite-jához (sprite), az összes változathoz, valamint az expires_at értéket. Ha más élettartamra van szükséged, a POST /files/{id}/links 60 másodperctől 30 napig érvényes linkeket állít ki, opcionálisan IP-címhez vagy sütihez kötve.

Python

A requests könyvtárral a megnyitott fájlobjektum átadása a lemezről streameli a fájlt, így a memóriahasználat nagy videóknál is állandó marad. Az alábbi függvény feltölt, majd megvárja az eredményt.

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

A Node.js 18-as és újabb verzióiban a fetch beépített, így nincs szükség függőségekre. Ez a változat a memóriába olvassa a fájlt, ami klipekhez és rövid videókhoz rendben van; többgigabájtos fájlokhoz inkább a curl-t, a WebDAV-ot vagy az FTP-t válaszd, amelyek a lemezről streamelnek.

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álás URL-ről

Ha a videó már elérhető online egy közvetlen linken, hagyd, hogy a szerver töltse le, ahelyett hogy a saját gépedre húznád, majd újra feltöltenéd. A hívás azonnal 202 választ ad egy importálási feladattal; a szerver letölti a fájlt, majd kódolási sorba teszi. A belső hálózatokra, a loopbackre és a szolgáltatási címtartományokra mutató linkeket elutasítjuk, egyszerre legfeljebb tíz aktív importálásod lehet, a folyamatot pedig a GET /files/import mutatja.

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 és FTP

Tömeges átvitelhez és olyan eszközökhöz, amelyek nem tudnak API-t hívni, ugyanaz a könyvtár WebDAV-on és FTP-n is elérhető. A felhasználónév a fiókod e-mail-címe, a jelszó egy API-kulcs. Mindkettő a lemezről streamel, és nagyon nagy fájlokhoz ez a legmegbízhatóbb lehetőség.

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/

Ha a kliensed támogatja, mindig a titkosított változatokat használd, hiszen az API-kulcs a jelszó. Bármely WebDAV-ot vagy FTPS-t ismerő kliens – a fájlkezelőktől a szinkronizáló eszközökig – ugyanezekkel az adatokkal csatlakozhat. Az így átmásolt fájlok megjelennek a könyvtáradban, és ugyanúgy kódoljuk őket, mint bármely más feltöltést.

Melyik utat válaszd

A videó használata

Amint az állapot ready, a lejátszó címe https://iframe.andromedans.live/e/, majd utána a public_id – pontosan ezt kell egy iframe-be tenned (a hosszú id is működik, és átirányít a rövid címre); a beágyazási útmutató bemutatja a kódot és a hls.js-es alternatívát. Domain- és országszabályokkal korlátozhatod, hol játszható le, és ha elérhetők hirdetések, bekapcsolhatod őket, hogy bevételt szerezz a megtekintésekből. A kulcsot tartsd távol a böngészőben futó kódtól, cseréld le, amikor valaki kilép a csapatodból, és ne feledd: az API minden csomagban elérhető, így már ma elkezdhetsz építeni.