Încărcare video prin API: curl, Python, Node.js, WebDAV și FTP

Poți pune un videoclip pe UFOLOAD fără să deschizi vreodată panoul. REST API-ul acceptă încărcări prin HTTPS, serverul poate prelua în locul tău un fișier de la un link, iar același cont este accesibil prin WebDAV și FTP pentru instrumentele care vorbesc deja aceste protocoale. Acest ghid trece prin toate cele cinci căi cu comenzi funcționale, explică ce răspunde serverul și arată cum aștepți finalizarea codării. Endpointurile de mai jos au fost verificate cu specificația OpenAPI publică; documentația API conține referința completă.

Creează o cheie API

Creează o cheie în secțiunea Dezvoltatori din panou. Fiecare cerere o poartă ca token bearer în antetul Authorization. Cheia este afișată o singură dată, la creare, așa că păstrează-o într-o variabilă de mediu sau într-un manager de secrete și revoc-o din panou dacă se scurge. Aceeași cheie funcționează ca parolă pentru WebDAV și FTP, cu e-mailul contului ca nume de utilizator. Dacă nu ai încă un cont, creează unul gratuit; pagina de prețuri arată limita de dimensiune a fișierelor și cotele de stocare și trafic ale planului tău.

export UFOLOAD_API_KEY="ufo_..."

Încărcare cu curl

Cea mai simplă încărcare trimite fișierul ca corp brut al cererii și pune numele lui în antetul X-File-Name. Trimite numele codificat procentual (UTF-8) dacă are spații sau caractere non-ASCII. Implicit, fișierul ajunge în folderul rădăcină; adaugă ?folder_id= sau un antet X-Folder-Id ca să alegi alt folder.

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

Funcționează și un formular multipart. Fișierul merge în câmpul file, iar folderul poate fi dat ca un câmp de formular folder_id:

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

O încărcare reușită răspunde cu 201 și un corp JSON care conține obiectul fișierului. Câmpurile pe care le vei folosi cel mai des sunt id, public_id (codul scurt care intră în adresele playerului), status, duration_ms și max_quality. Serverul nu ocupă spațiu suplimentar pentru conținut pe care îl are deja: dacă încarci din nou aceiași bytes, răspunde cu 200, fișierul existent și "duplicate": true, potrivind fișierele după hash-ul SHA-256.

Așteaptă ca videoclipul să fie gata

Încărcarea este doar prima jumătate. După ea, fișierul intră în coadă și este codat într-o scară HLS adaptivă (vezi cum se construiește scara). status-ul lui trece prin uploading, queued și processing și se termină cu ready sau failed; un fișier eșuat are un mesaj error. Interoghează fișierul la câteva secunde și niciodată într-o buclă strânsă: API-ul are limită de rată și răspunde cu 429.

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

Răspunsul are două părți: file cu metadatele și links cu adrese semnate pentru playlistul master (playback), copertă (poster), sprite-ul pentru previzualizarea la hover (sprite), fiecare variantă și expires_at. Dacă ai nevoie de altă valabilitate, POST /files/{id}/links emite linkuri valabile între 60 de secunde și 30 de zile, opțional legate de o adresă IP sau de un cookie.

Python

Cu biblioteca requests, transmiterea obiectului fișier deschis îl trimite în flux de pe disc, așa că memoria rămâne constantă chiar și pentru videoclipuri mari. Funcția de mai jos încarcă, apoi așteaptă rezultatul.

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 versiunile mai noi au fetch integrat, așa că nu sunt necesare dependențe. Această versiune citește fișierul în memorie, ceea ce e în regulă pentru clipuri și videoclipuri scurte; pentru fișiere de mai mulți gigabytes preferă curl, WebDAV sau FTP, care trimit în flux de pe disc.

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 după URL

Dacă videoclipul este deja online la un link direct, lasă serverul să-l descarce, în loc să-l aduci pe calculatorul tău și să-l trimiți din nou. Apelul răspunde imediat cu 202 și o sarcină de import; serverul preia fișierul și apoi îl pune în coada de codare. Linkurile către rețele interne, loopback și plaje de adrese de serviciu sunt respinse, poți avea până la zece importuri active, iar GET /files/import arată progresul.

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

Pentru transferuri în masă și pentru instrumentele care nu pot apela un API, aceeași bibliotecă este disponibilă prin WebDAV și FTP. Numele de utilizator este e-mailul contului, iar parola este o cheie API. Ambele trimit în flux de pe disc și sunt varianta cea mai robustă pentru fișiere foarte mari.

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/

Folosește variantele criptate ori de câte ori clientul tău le suportă, pentru că parola este cheia API. Orice client care vorbește WebDAV sau FTPS, de la managere de fișiere la instrumente de sincronizare, poate folosi aceleași date. Fișierele copiate astfel apar în biblioteca ta și sunt codate ca orice altă încărcare.

Ce cale să alegi

Folosește videoclipul

Odată ce starea este ready, adresa playerului este https://iframe.andromedans.live/e/ urmat de public_id, exact ce pui într-un iframe (funcționează și id-ul lung, care este redirecționat către adresa scurtă); ghidul de încorporare arată codul și alternativa cu hls.js. Poți restricționa unde se redă cu reguli pe domenii și țări și, când reclamele sunt disponibile, le poți activa ca să câștigi din vizualizări. Ține cheia departe de codul din browser, schimb-o când pleacă oameni din echipă și reține că API-ul este disponibil în orice plan, așa că poți începe să construiești chiar azi.