Nahrávání videí přes API: curl, Python, Node.js, WebDAV a FTP

Video můžete do UFOLOAD dostat, aniž byste kdy otevřeli panel. REST API přijímá nahrávání přes HTTPS, server za vás umí stáhnout soubor z odkazu a stejný účet je dostupný přes WebDAV a FTP pro nástroje, které tyto protokoly už ovládají. Tento návod prochází všech pět cest s funkčními příkazy, vysvětluje, co server odpovídá, a ukazuje, jak počkat na dokončení kódování. Níže uvedené endpointy byly ověřeny proti veřejné specifikaci OpenAPI; úplnou referenci obsahuje dokumentace API.

Vytvořte klíč API

Klíč vytvoříte v sekci Vývojáři ve svém panelu. Každý požadavek ho nese jako bearer token v hlavičce Authorization. Klíč se zobrazí jen jednou při vytvoření, proto ho uložte do proměnné prostředí nebo správce tajných údajů, a pokud unikne, zrušte ho v panelu. Stejný klíč slouží jako heslo pro WebDAV a FTP, přičemž přihlašovacím jménem je e-mail vašeho účtu. Pokud ještě účet nemáte, vytvořte si ho zdarma; stránka Ceník uvádí limit velikosti souboru a kvóty úložiště a provozu, které pro váš tarif platí.

export UFOLOAD_API_KEY="ufo_..."

Nahrávání pomocí curl

Nejjednodušší nahrání odešle soubor jako surové tělo požadavku a jeho název uvede v hlavičce X-File-Name. Pokud název obsahuje mezery nebo znaky mimo ASCII, pošlete ho v procentovém kódování (UTF-8). Ve výchozím stavu soubor skončí v kořenové složce; jinou zvolíte pomocí ?folder_id= nebo hlavičky 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 také formulář multipart. Soubor patří do pole file a složku lze zadat jako pole formuláře folder_id:

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

Úspěšné nahrání odpoví kódem 201 s tělem JSON, které obsahuje objekt souboru. Nejčastěji budete používat pole id, public_id (krátký kód, který patří do adres přehrávače), status, duration_ms a max_quality. Server nezabírá místo navíc pro obsah, který už má: pokud nahrajete stejné bajty znovu, odpoví 200 s existujícím souborem a "duplicate": true, přičemž soubory porovnává podle hashe SHA-256.

Počkejte, až bude video připravené

Nahrání je jen první polovina. Poté se soubor zařadí do fronty a zakóduje do adaptivního žebříčku HLS (viz jak se žebříček sestavuje). Jeho status prochází stavy uploading, queued a processing a končí ve stavu ready nebo failed; neúspěšný soubor nese zprávu error. Dotazujte se na soubor každých několik sekund, nikdy ne v těsné smyčce: API má omezený počet požadavků a odpovídá 429.

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

Odpověď má dvě části: file s metadaty a links s podepsanými adresami hlavního playlistu (playback), titulního obrázku (poster), spritu pro náhledy při najetí myší (sprite), každé verze a expires_at. Pokud potřebujete jinou platnost, POST /files/{id}/links vydá odkazy platné od 60 sekund do 30 dnů, volitelně svázané s adresou IP nebo cookie.

Python

S knihovnou requests se předaný otevřený objekt souboru streamuje z disku, takže spotřeba paměti zůstává stejná i u velkých videí. Funkce níže soubor nahraje a pak počká na výsledek.

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ější má vestavěný fetch, takže nejsou potřeba žádné závislosti. Tato verze načte soubor do paměti, což je v pořádku pro klipy a krátká videa; pro soubory o velikosti několika gigabajtů raději použijte curl, WebDAV nebo FTP, které 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

Pokud je video už online na přímém odkazu, nechte ho stáhnout server, místo abyste ho stahovali do svého počítače a znovu odesílali. Volání okamžitě vrátí 202 s úlohou importu; server soubor stáhne a pak ho zařadí do fronty kódování. Odkazy do interních sítí, na loopback a do servisních rozsahů adres jsou odmítnuty, aktivních importů můžete mít až deset a průběh ukazuje GET /files/import.

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

Pro hromadné přenosy a pro nástroje, které neumí volat API, je stejná knihovna dostupná přes WebDAV a FTP. Přihlašovacím jménem je e-mail vašeho účtu a heslem klíč API. Obojí streamuje z disku a pro velmi velké soubory jde o nejrobustnější možnost.

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/

Kdykoli to váš klient podporuje, používejte šifrované varianty, protože heslem je klíč API. Stejné údaje může použít jakýkoli klient, který umí WebDAV nebo FTPS, od správců souborů po synchronizační nástroje. Soubory zkopírované tímto způsobem se objeví ve vaší knihovně a zakódují se jako každé jiné nahrání.

Kterou cestu zvolit

Použití videa

Jakmile je stav ready, adresa přehrávače je https://iframe.andromedans.live/e/ následovaná public_id, což je přesně to, co vložíte do iframe (funguje i dlouhé id, které se přesměruje na krátkou adresu); návod k vkládání ukazuje kód i alternativu s hls.js. Kde se video přehrává, můžete omezit pravidly pro domény a země, a pokud jsou reklamy dostupné, můžete je zapnout a vydělávat na zhlédnutích. Klíč nedávejte do kódu v prohlížeči, měňte ho, když lidé odcházejí z vašeho týmu, a pamatujte, že API je dostupné v každém tarifu, takže můžete začít stavět ještě dnes.