Vaizdo įrašų įkėlimas per API: curl, Python, Node.js, WebDAV ir FTP

Vaizdo įrašą į UFOLOAD galite įkelti net neatidarę valdymo skydelio. REST API priima įkėlimus per HTTPS, serveris gali už jus parsisiųsti failą iš nuorodos, o ta pati paskyra pasiekiama per WebDAV ir FTP įrankiams, kurie jau naudoja šiuos protokolus. Šiame vadove aptariami visi penki būdai su veikiančiomis komandomis, paaiškinama, ką atsako serveris, ir parodoma, kaip palaukti, kol baigsis kodavimas. Toliau pateikti galiniai taškai patikrinti pagal viešą OpenAPI specifikaciją; visas žinynas pateiktas API dokumentacijoje.

Sukurkite API raktą

Sukurkite raktą valdymo skydelio skiltyje „Kūrėjams“. Kiekviena užklausa jį perduoda kaip bearer prieigos raktą antraštėje Authorization. Raktas parodomas tik vieną kartą jį sukūrus, todėl išsaugokite jį aplinkos kintamajame ar slaptųjų duomenų tvarkyklėje, o jei jis nutekėtų, atšaukite jį valdymo skydelyje. Tas pats raktas veikia kaip WebDAV ir FTP slaptažodis, o prisijungimo vardas yra jūsų paskyros el. pašto adresas. Jei dar neturite paskyros, susikurkite nemokamą; kainų puslapyje nurodytas failo dydžio limitas ir jūsų planui taikomos saugyklos bei srauto kvotos.

export UFOLOAD_API_KEY="ufo_..."

Įkėlimas su curl

Paprasčiausias įkėlimas siunčia failą kaip neapdorotą užklausos turinį, o jo pavadinimą įrašo į antraštę X-File-Name. Jei pavadinime yra tarpų ar ne ASCII simbolių, siųskite jį procentiniu kodavimu (UTF-8). Pagal numatymą failas patenka į šakninį aplanką; norėdami pasirinkti kitą, pridėkite ?folder_id= arba antraštę 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

Tinka ir multipart forma. Failas perduodamas lauke file, o aplanką galima nurodyti formos lauku folder_id:

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

Sėkmingas įkėlimas atsako 201 su JSON turiniu, kuriame yra failo objektas. Dažniausiai naudosite laukus id, public_id (trumpas kodas, įrašomas į grotuvo adresus), status, duration_ms ir max_quality. Serveris nenaudoja papildomos vietos jau turimam turiniui: jei vėl įkelsite tuos pačius baitus, jis atsakys 200 su esamu failu ir "duplicate": true, failus lygindamas pagal jų SHA-256 maišos reikšmę.

Palaukite, kol vaizdo įrašas bus paruoštas

Įkėlimas – tik pirmoji pusė. Po jo failas įtraukiamas į eilę ir užkoduojamas į adaptyvias HLS kopėčias (žr. kaip sudaromos kopėčios). Jo status pereina uploading, queued ir processing būsenas ir baigiasi ready arba failed; nepavykęs failas turi error pranešimą. Tikrinkite failą kas kelias sekundes ir niekada ne be pertraukos: API taiko užklausų limitus ir atsako 429.

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

Atsakymą sudaro dvi dalys: file su metaduomenimis ir links su pasirašytais pagrindinio grojaraščio (playback), viršelio (poster), peržiūros užvedus pelę sprite (sprite), kiekvienos versijos adresais ir expires_at. Jei reikia kito galiojimo laiko, POST /files/{id}/links išduoda nuorodas, galiojančias nuo 60 sekundžių iki 30 dienų, pasirinktinai susietas su IP adresu ar slapuku.

Python

Naudojant biblioteką requests ir perduodant atidarytą failo objektą, jis siunčiamas srautu iš disko, todėl net dideliems vaizdo įrašams atminties sąnaudos nedidėja. Toliau pateikta funkcija įkelia failą ir palaukia rezultato.

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 ir naujesnės versijos turi įmontuotą fetch, todėl priklausomybių nereikia. Ši versija nuskaito failą į atmintį – tai tinka klipams ir trumpiems vaizdo įrašams; kelių gigabaitų failams rinkitės curl, WebDAV ar FTP, kurie siunčia srautu iš disko.

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)

Importas pagal URL

Jei vaizdo įrašas jau yra internete tiesiogine nuoroda, leiskite serveriui jį atsisiųsti, užuot traukę jį į savo kompiuterį ir vėl siuntę. Kvietinys iškart grąžina 202 su importo užduotimi; serveris parsisiunčia failą ir tada įtraukia jį į kodavimo eilę. Nuorodos į vidinius tinklus, loopback ir tarnybinius adresų intervalus atmetamos, vienu metu galite turėti iki dešimties aktyvių importų, o GET /files/import rodo eigą.

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

Masiniams perdavimams ir įrankiams, kurie negali kviesti API, ta pati biblioteka prieinama per WebDAV ir FTP. Prisijungimo vardas – jūsų paskyros el. pašto adresas, slaptažodis – API raktas. Abu būdai siunčia srautu iš disko ir yra patikimiausias pasirinkimas labai dideliems failams.

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/

Kai tik klientas palaiko, naudokite šifruotus variantus, nes API raktas yra slaptažodis. Tuos pačius duomenis gali naudoti bet kuris WebDAV ar FTPS palaikantis klientas – nuo failų tvarkyklių iki sinchronizavimo įrankių. Taip nukopijuoti failai atsiranda jūsų bibliotekoje ir koduojami kaip bet kuris kitas įkėlimas.

Kurį būdą pasirinkti

Naudokite vaizdo įrašą

Kai būsena tampa ready, grotuvo adresas yra https://iframe.andromedans.live/e/ su public_id gale – būtent tai įrašote į iframe (veikia ir ilgasis id, kuris nukreipiamas į trumpąjį adresą); įterpimo vadove parodytas maketas ir hls.js alternatyva. Galite apriboti, kur jis atkuriamas, domenų ir šalių taisyklėmis, o kai reklama prieinama, įjungti ją ir uždirbti iš peržiūrų. Nelaikykite rakto naršyklės kode, pakeiskite jį, kai žmonės palieka jūsų komandą, ir atminkite, kad API prieinama kiekviename plane, todėl kurti galite pradėti jau šiandien.