Videoiden lataus API:lla: curl, Python, Node.js, WebDAV ja FTP

Voit lisätä videon UFOLOADiin avaamatta koskaan hallintapaneelia. REST API vastaanottaa lataukset HTTPS:n kautta, palvelin voi hakea tiedoston linkistä puolestasi, ja sama tili on käytettävissä WebDAVin ja FTP:n kautta työkaluille, jotka jo puhuvat näitä protokollia. Tämä opas käy läpi kaikki viisi reittiä toimivine komentoineen, selittää palvelimen vastaukset ja näyttää, miten odotetaan koodauksen valmistumista. Alla olevat päätepisteet on tarkistettu julkista OpenAPI-määrittelyä vasten; API-dokumentaatiossa on täydellinen viiteosio.

Luo API-avain

Luo avain hallintapaneelin Kehittäjät-osiossa. Jokainen pyyntö lähettää sen bearer-tunnisteena Authorization-otsakkeessa. Avain näytetään vain kerran luonnin yhteydessä, joten tallenna se ympäristömuuttujaan tai salaisuuksien hallintaan ja mitätöi se hallintapaneelista, jos se vuotaa. Sama avain toimii WebDAVin ja FTP:n salasanana, ja käyttäjätunnuksena on tilisi sähköpostiosoite. Jos sinulla ei vielä ole tiliä, luo ilmainen tili; hinnoittelusivu luettelee pakettiisi sovellettavan tiedostokokorajan sekä tallennus- ja liikennekiintiöt.

export UFOLOAD_API_KEY="ufo_..."

Lataus curlilla

Yksinkertaisin lataus lähettää tiedoston pyynnön raakarunkona ja sen nimen X-File-Name-otsakkeessa. Lähetä nimi prosenttikoodattuna (UTF-8), jos siinä on välilyöntejä tai muita kuin ASCII-merkkejä. Oletuksena tiedosto päätyy juurikansioon; lisää ?folder_id= tai X-Folder-Id-otsake valitaksesi toisen kansion.

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

Myös multipart-lomake toimii. Tiedosto menee kenttään file, ja kansion voi antaa lomakekenttänä folder_id:

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

Onnistunut lataus vastaa koodilla 201 ja JSON-rungolla, joka sisältää tiedosto-objektin. Eniten käyttämäsi kentät ovat id, public_id (soitinosoitteisiin tuleva lyhytkoodi), status, duration_ms ja max_quality. Palvelin ei käytä lisätilaa sisältöön, joka sillä jo on: jos lataat samat tavut uudelleen, se vastaa koodilla 200, palauttaa olemassa olevan tiedoston ja "duplicate": true, ja tiedostot tunnistetaan niiden SHA-256-tiivisteen perusteella.

Odota, että video on valmis

Lataus on vasta ensimmäinen puolisko. Sen jälkeen tiedosto asetetaan jonoon ja koodataan mukautuvaksi HLS-portaikoksi (katso miten portaikko rakennetaan). Sen status kulkee tilojen uploading, queued ja processing kautta ja päättyy tilaan ready tai failed; epäonnistuneessa tiedostossa on error-viesti. Kysele tiedoston tilaa muutaman sekunnin välein, äläkä koskaan tiiviissä silmukassa: API:ssa on pyyntörajoitus, ja se vastaa koodilla 429.

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

Vastauksessa on kaksi osaa: file metatietoineen ja links allekirjoitettuine osoitteineen pääsoittolistalle (playback), kansikuvalle (poster), esikatselusprite-kuvalle (sprite) ja jokaiselle versiolle sekä expires_at. Jos tarvitset eri voimassaoloajan, POST /files/{id}/links luo linkkejä, jotka ovat voimassa 60 sekunnista 30 päivään, valinnaisesti IP-osoitteeseen tai evästeeseen sidottuina.

Python

requests-kirjastoa käytettäessä avoimen tiedosto-objektin välittäminen virtaa sen levyltä, joten muistinkäyttö pysyy tasaisena suurillakin videoilla. Alla oleva funktio lataa tiedoston ja odottaa sitten tulosta.

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:ssa ja uudemmissa on sisäänrakennettu fetch, joten riippuvuuksia ei tarvita. Tämä versio lukee tiedoston muistiin, mikä sopii leikkeille ja lyhyille videoille; usean gigatavun tiedostoille suosi curlia, WebDAVia tai FTP:tä, jotka virtaavat levyltä.

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)

Tuonti URL-osoitteesta

Jos video on jo verkossa suoran linkin takana, anna palvelimen ladata se sen sijaan, että hakisit sen omalle koneellesi ja lähettäisit uudelleen. Kutsu palauttaa heti koodin 202 ja tuontitehtävän; palvelin hakee tiedoston ja asettaa sen sitten koodausjonoon. Linkit sisäverkkoihin, loopback-osoitteisiin ja palveluosoitealueisiin hylätään, aktiivisia tuonteja voi olla enintään kymmenen, ja GET /files/import näyttää edistymisen.

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

Massasiirtoja ja API:a kutsumaan kykenemättömiä työkaluja varten sama kirjasto on käytettävissä WebDAVin ja FTP:n kautta. Käyttäjätunnus on tilisi sähköpostiosoite ja salasana API-avain. Molemmat virtaavat levyltä ja ovat vakain vaihtoehto hyvin suurille tiedostoille.

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/

Käytä salattuja vaihtoehtoja aina, kun asiakasohjelmasi tukee niitä, koska API-avain on salasana. Mikä tahansa WebDAVia tai FTPS:ää puhuva asiakasohjelma tiedostonhallinnoista synkronointityökaluihin voi käyttää samoja tietoja. Näin kopioidut tiedostot näkyvät kirjastossasi ja koodataan kuten mikä tahansa muu lataus.

Minkä reitin valita

Käytä videota

Kun tila on ready, soittimen osoite on https://iframe.andromedans.live/e/ ja sen perään public_id, mikä on juuri se, mitä laitat iframeen (pitkä id toimii myös ja ohjataan lyhyeen osoitteeseen); upotusopas näyttää merkinnän ja hls.js-vaihtoehdon. Voit rajata, missä video toistuu, verkkotunnus- ja maasäännöillä, ja kun mainoksia on saatavilla, ottaa ne käyttöön ansaitaksesi katselukerroilla. Pidä avain poissa selaimen koodista, vaihda se, kun ihmisiä lähtee tiimistäsi, ja muista, että API on käytettävissä kaikissa paketeissa, joten voit aloittaa rakentamisen jo tänään.