Nalaganje videov prek API: curl, Python, Node.js, WebDAV in FTP

Video lahko na UFOLOAD postavite, ne da bi sploh odprli nadzorno ploščo. REST API sprejema nalaganja prek HTTPS, strežnik lahko datoteko namesto vas prenese s povezave, isti račun pa je za orodja, ki te protokole že podpirajo, dosegljiv tudi prek WebDAV in FTP. Ta vodnik z delujočimi ukazi predstavi vseh pet poti, razloži, kaj strežnik odgovori, in pokaže, kako počakati na konec kodiranja. Spodnje končne točke so preverjene glede na javno specifikacijo OpenAPI; celotna referenca je v dokumentaciji API.

Ustvarite ključ API

Ključ ustvarite v razdelku Razvijalci na nadzorni plošči. Vsaka zahteva ga nosi kot žeton bearer v glavi Authorization. Ključ je prikazan samo enkrat ob ustvarjanju, zato ga shranite v spremenljivko okolja ali upravitelja skrivnosti in ga na nadzorni plošči prekličite, če uide. Isti ključ deluje kot geslo za WebDAV in FTP, uporabniško ime pa je e-poštni naslov vašega računa. Če računa še nimate, ustvarite brezplačnega; stran Cenik navaja omejitev velikosti datoteke ter kvote shrambe in prometa, ki veljajo za vaš paket.

export UFOLOAD_API_KEY="ufo_..."

Nalaganje s curl

Najpreprostejše nalaganje datoteko pošlje kot surovo telo zahteve, njeno ime pa postavi v glavo X-File-Name. Če ime vsebuje presledke ali znake, ki niso ASCII, ga pošljite v odstotnem kodiranju (UTF-8). Privzeto datoteka pristane v korenski mapi; za izbiro druge dodajte ?folder_id= ali glavo 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

Deluje tudi obrazec multipart. Datoteka gre v polje file, mapo pa lahko podate kot polje obrazca folder_id:

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

Uspešno nalaganje odgovori s 201 in telesom JSON, ki vsebuje objekt datoteke. Najpogosteje boste uporabljali polja id, public_id (kratka koda, ki gre v naslove predvajalnika), status, duration_ms in max_quality. Strežnik za vsebino, ki jo že ima, ne porabi dodatnega prostora: če iste bajte naložite znova, odgovori s 200, obstoječo datoteko in "duplicate": true, datoteke pa primerja po zgoščeni vrednosti SHA-256.

Počakajte, da je video pripravljen

Nalaganje je šele prva polovica. Po njem se datoteka uvrsti v čakalno vrsto in kodira v prilagodljivo lestvico HLS (glejte kako je lestvica zgrajena). Njen status gre skozi uploading, queued in processing ter se konča pri ready ali failed; neuspela datoteka nosi sporočilo error. Datoteko preverjajte na nekaj sekund in nikoli v tesni zanki: API ima omejitev hitrosti in odgovori s 429.

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

Odgovor ima dva dela: file z metapodatki in links s podpisanimi naslovi za glavni seznam predvajanja (playback), naslovno sliko (poster), sliko sličic za predogled ob prehodu z miško (sprite), vsako različico in expires_at. Če potrebujete drugačno življenjsko dobo, POST /files/{id}/links izda povezave, veljavne od 60 sekund do 30 dni, po želji vezane na naslov IP ali piškotek.

Python

Če knjižnici requests podate odprt objekt datoteke, ga ta pretaka z diska, zato poraba pomnilnika ostane enaka tudi pri velikih videih. Spodnja funkcija naloži datoteko in nato počaka na rezultat.

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 in novejši ima fetch vgrajen, zato odvisnosti niso potrebne. Ta različica datoteko prebere v pomnilnik, kar je v redu za posnetke in kratke videe; za večgigabajtne datoteke raje uporabite curl, WebDAV ali FTP, ki pretakajo z diska.

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)

Uvoz z URL-ja

Če je video že na spletu na neposredni povezavi, naj ga prenese strežnik, namesto da ga vlečete na svoj računalnik in ga znova pošiljate. Klic takoj vrne 202 z nalogo uvoza; strežnik prenese datoteko in jo nato uvrsti v čakalno vrsto za kodiranje. Povezave do notranjih omrežij, povratne zanke in servisnih obsegov naslovov so zavrnjene, hkrati imate lahko do deset aktivnih uvozov, GET /files/import pa prikazuje napredek.

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

Za množične prenose in za orodja, ki ne znajo klicati API, je ista knjižnica na voljo prek WebDAV in FTP. Uporabniško ime je e-poštni naslov vašega računa, geslo pa ključ API. Oba pretakata z diska in sta najzanesljivejša možnost za zelo velike datoteke.

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/

Kadar vaš odjemalec to podpira, uporabite šifrirani različici, saj je ključ API geslo. Iste podatke lahko uporabi vsak odjemalec, ki podpira WebDAV ali FTPS, od upraviteljev datotek do orodij za sinhronizacijo. Tako kopirane datoteke se pojavijo v vaši knjižnici in se kodirajo kot vsako drugo nalaganje.

Katero pot izbrati

Uporabite video

Ko je stanje ready, je naslov predvajalnika https://iframe.andromedans.live/e/, ki mu sledi public_id, in prav to vstavite v iframe (deluje tudi dolgi id, ki se preusmeri na kratki naslov); vodnik za vdelavo pokaže oznako in alternativo s hls.js. Kje se video predvaja, lahko omejite s pravili za domene in države, kadar so oglasi na voljo, pa jih lahko vklopite in zaslužite z ogledi. Ključa ne puščajte v kodi brskalnika, zamenjajte ga, ko ljudje zapustijo vašo ekipo, in ne pozabite, da je API na voljo v vseh paketih, zato lahko začnete graditi že danes.