Przesyłanie wideo przez API: curl, Python, Node.js, WebDAV i FTP

Możesz umieścić wideo w UFOLOAD, w ogóle nie otwierając panelu. REST API przyjmuje pliki przez HTTPS, serwer może sam pobrać plik z linku, a to samo konto jest dostępne przez WebDAV i FTP dla narzędzi, które już obsługują te protokoły. Ten poradnik omawia wszystkie pięć dróg z działającymi poleceniami, wyjaśnia, co odpowiada serwer, i pokazuje, jak poczekać na zakończenie kodowania. Poniższe endpointy zostały sprawdzone z publiczną specyfikacją OpenAPI; pełny opis znajdziesz w dokumentacji API.

Utwórz klucz API

Utwórz klucz w sekcji Dla deweloperów w panelu. Każde żądanie przekazuje go jako token bearer w nagłówku Authorization. Klucz jest wyświetlany tylko raz, przy tworzeniu, więc zapisz go w zmiennej środowiskowej lub menedżerze sekretów i unieważnij w panelu, jeśli wycieknie. Ten sam klucz służy jako hasło do WebDAV i FTP, a loginem jest adres e-mail konta. Jeśli nie masz jeszcze konta, załóż darmowe; cennik podaje limit rozmiaru pliku oraz limity przestrzeni i ruchu obowiązujące w Twoim planie.

export UFOLOAD_API_KEY="ufo_..."

Przesyłanie przez curl

Najprostsze przesłanie wysyła plik jako surową treść żądania, a jego nazwę umieszcza w nagłówku X-File-Name. Jeśli nazwa zawiera spacje lub znaki spoza ASCII, wyślij ją zakodowaną procentowo (UTF-8). Domyślnie plik trafia do folderu głównego; dodaj ?folder_id= lub nagłówek X-Folder-Id, aby wybrać inny.

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

Formularz multipart też działa. Plik trafia do pola file, a folder można podać w polu formularza folder_id:

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

Udane przesłanie zwraca 201 z treścią JSON zawierającą obiekt pliku. Najczęściej używane pola to id, public_id (krótki kod, który trafia do adresów odtwarzacza), status, duration_ms i max_quality. Serwer nie zajmuje dodatkowego miejsca na treści, które już ma: jeśli prześlesz ponownie te same bajty, odpowie 200 z istniejącym plikiem i "duplicate": true, dopasowując pliki po skrócie SHA-256.

Poczekaj, aż wideo będzie gotowe

Przesłanie to dopiero pierwsza połowa. Potem plik trafia do kolejki i jest kodowany do adaptacyjnej drabinki HLS (zobacz, jak budowana jest drabinka). Jego status przechodzi przez uploading, queued i processing i kończy się na ready lub failed; nieudany plik zawiera komunikat error. Odpytuj plik co kilka sekund, nigdy w ciasnej pętli: API ma limity zapytań i odpowiada 429.

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

Odpowiedź ma dwie części: file z metadanymi oraz links z podpisanymi adresami głównej playlisty (playback), okładki (poster), sprite’a podglądu po najechaniu (sprite), każdej wersji oraz expires_at. Jeśli potrzebujesz innego czasu ważności, POST /files/{id}/links wydaje linki ważne od 60 sekund do 30 dni, opcjonalnie powiązane z adresem IP lub ciasteczkiem.

Python

W bibliotece requests przekazanie otwartego obiektu pliku przesyła go strumieniowo z dysku, więc zużycie pamięci pozostaje stałe nawet przy dużych filmach. Poniższa funkcja przesyła plik, a potem czeka na wynik.

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 i nowsze mają wbudowane fetch, więc nie trzeba żadnych zależności. Ta wersja wczytuje plik do pamięci, co wystarcza dla klipów i krótkich filmów; dla plików o rozmiarze wielu gigabajtów wybierz curl, WebDAV lub FTP, które przesyłają dane strumieniowo z dysku.

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

Jeśli wideo jest już dostępne online pod bezpośrednim linkiem, pozwól serwerowi je pobrać, zamiast ściągać je na swój komputer i wysyłać ponownie. Wywołanie od razu zwraca 202 z zadaniem importu; serwer pobiera plik, a potem dodaje go do kolejki kodowania. Linki do sieci wewnętrznych, adresów loopback i zakresów adresów usługowych są odrzucane, możesz mieć do dziesięciu aktywnych importów, a GET /files/import pokazuje postęp.

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

Do transferów hurtowych i narzędzi, które nie potrafią wywoływać API, ta sama biblioteka jest dostępna przez WebDAV i FTP. Loginem jest adres e-mail konta, a hasłem — klucz API. Obie metody przesyłają dane strumieniowo z dysku i są najpewniejszą opcją dla bardzo dużych plików.

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/

Używaj wariantów szyfrowanych zawsze, gdy Twój klient je obsługuje, bo hasłem jest klucz API. Każdy klient obsługujący WebDAV lub FTPS, od menedżerów plików po narzędzia synchronizacji, może użyć tych samych danych. Pliki skopiowane w ten sposób pojawiają się w bibliotece i są kodowane jak każde inne przesłanie.

Którą drogę wybrać

Użyj wideo

Gdy status to ready, adres odtwarzacza to https://iframe.andromedans.live/e/ z dopisanym public_id — dokładnie to wstawiasz do iframe (długie id też działa i przekierowuje na krótki adres); poradnik osadzania pokazuje kod oraz alternatywę z hls.js. Możesz ograniczyć, gdzie wideo się odtwarza, regułami dla domen i krajów, a gdy reklamy są dostępne, włączyć je, by zarabiać na wyświetleniach. Trzymaj klucz z dala od kodu przeglądarki, zmieniaj go, gdy ktoś odchodzi z zespołu, i pamiętaj, że API jest dostępne w każdym planie, więc możesz zacząć budować już dziś.