Nahrávanie videí cez API: curl, Python, Node.js, WebDAV a FTP

Video môžete do UFOLOAD dostať bez toho, aby ste vôbec otvorili prehľad. REST API prijíma nahrávanie cez HTTPS, server za vás dokáže stiahnuť súbor z odkazu a ten istý účet je dostupný aj cez WebDAV a FTP pre nástroje, ktoré tieto protokoly už ovládajú. Tento návod prechádza všetkými piatimi cestami s funkčnými príkazmi, vysvetľuje, čo server odpovedá, a ukazuje, ako počkať na dokončenie kódovania. Endpointy nižšie boli overené podľa verejnej špecifikácie OpenAPI; úplnú referenciu nájdete v dokumentácii API.

Vytvorte kľúč API

Kľúč vytvoríte v sekcii Pre vývojárov vo svojom prehľade. Každá požiadavka ho nesie ako bearer token v hlavičke Authorization. Kľúč sa zobrazí len raz pri vytvorení, preto ho uložte do premennej prostredia alebo správcu tajomstiev, a ak unikne, zrušte ho v prehľade. Ten istý kľúč slúži ako heslo pre WebDAV a FTP, prihlasovacím menom je e-mail vášho účtu. Ak ešte nemáte účet, vytvorte si bezplatný; stránka Cenník uvádza limit veľkosti súboru a kvóty úložiska a prenosu, ktoré platia pre váš plán.

export UFOLOAD_API_KEY="ufo_..."

Nahrávanie cez curl

Najjednoduchšie nahratie pošle súbor ako surové telo požiadavky a jeho názov vloží do hlavičky X-File-Name. Ak názov obsahuje medzery alebo znaky mimo ASCII, pošlite ho percentuálne zakódovaný (UTF-8). Predvolene súbor skončí v koreňovom priečinku; ak chcete iný, pridajte ?folder_id= alebo hlavičku X-Folder-Id.

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

Funguje aj formulár multipart. Súbor patrí do poľa file a priečinok možno zadať ako pole formulára folder_id:

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

Úspešné nahratie odpovie kódom 201 s telom JSON, ktoré obsahuje objekt súboru. Najčastejšie použijete polia id, public_id (krátky kód, ktorý patrí do adries prehrávača), status, duration_ms a max_quality. Server nezaberá ďalšie miesto pre obsah, ktorý už má: ak nahráte tie isté bajty znova, odpovie kódom 200 s existujúcim súborom a "duplicate": true, pričom súbory porovnáva podľa hashu SHA-256.

Počkajte, kým bude video pripravené

Nahratie je len prvá polovica. Potom sa súbor zaradí do frontu a zakóduje do adaptívneho rebríka HLS (pozrite ako sa rebrík vytvára). Jeho status prechádza stavmi uploading, queued a processing a končí na ready alebo failed; neúspešný súbor nesie správu error. Stav súboru zisťujte každých niekoľko sekúnd, nikdy nie v tesnej slučke: API má limit požiadaviek a odpovedá 429.

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

Odpoveď má dve časti: file s metadátami a links s podpísanými adresami hlavného playlistu (playback), obálky (poster), sprite pre náhľady pri prejdení myšou (sprite), každej verzie a expires_at. Ak potrebujete inú platnosť, POST /files/{id}/links vydá odkazy platné od 60 sekúnd do 30 dní, voliteľne viazané na IP adresu alebo cookie.

Python

S knižnicou requests sa pri odovzdaní otvoreného objektu súboru súbor streamuje z disku, takže pamäť zostáva nízko aj pri veľkých videách. Funkcia nižšie súbor nahrá a potom čaká na výsledok.

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 a novší má zabudovaný fetch, takže nie sú potrebné žiadne závislosti. Táto verzia načíta súbor do pamäte, čo je v poriadku pre klipy a krátke videá; pre súbory s veľkosťou niekoľkých gigabajtov radšej použite curl, WebDAV alebo FTP, ktoré streamujú z disku.

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 z URL

Ak je video už online na priamom odkaze, nechajte ho stiahnuť server namiesto toho, aby ste ho sťahovali na svoj počítač a znova odosielali. Volanie hneď vráti 202 s úlohou importu; server súbor stiahne a potom ho zaradí do frontu na kódovanie. Odkazy na interné siete, loopback a servisné rozsahy adries sa odmietajú, aktívnych importov môžete mať najviac desať a GET /files/import ukazuje priebeh.

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

Na hromadné prenosy a pre nástroje, ktoré nevedia volať API, je tá istá knižnica dostupná cez WebDAV a FTP. Prihlasovacím menom je e-mail vášho účtu a heslom kľúč API. Oba streamujú z disku a sú najrobustnejšou možnosťou pre veľmi veľké súbory.

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/

Kedykoľvek to váš klient podporuje, používajte šifrované varianty, pretože heslom je kľúč API. Tie isté údaje môže použiť každý klient, ktorý ovláda WebDAV alebo FTPS, od správcov súborov po synchronizačné nástroje. Súbory skopírované týmto spôsobom sa objavia vo vašej knižnici a zakódujú sa ako každé iné nahratie.

Ktorú cestu zvoliť

Použitie videa

Keď je stav ready, adresa prehrávača je https://iframe.andromedans.live/e/ nasledovaná public_id, čo je presne to, čo vložíte do iframe (funguje aj dlhé id, ktoré sa presmeruje na krátku adresu); návod na vkladanie ukazuje značky aj alternatívu s hls.js. Kde sa video prehráva, môžete obmedziť pravidlami pre domény a krajiny a ak sú reklamy dostupné, zapnúť ich a zarábať na zhliadnutiach. Kľúč držte mimo kódu prehliadača, vymeňte ho, keď niekto odíde z tímu, a pamätajte, že API je dostupné v každom pláne, takže môžete začať stavať už dnes.