Качване на видеа през API: curl, Python, Node.js, WebDAV и FTP

Можете да качите видео в UFOLOAD, без изобщо да отваряте таблото. REST API приема качвания през HTTPS, сървърът може да изтегли файл от връзка вместо вас, а същият акаунт е достъпен през WebDAV и FTP за инструменти, които вече говорят тези протоколи. Това ръководство минава през всичките пет пътя с работещи команди, обяснява какво отговаря сървърът и показва как да изчакате края на кодирането. Крайните точки по-долу са проверени спрямо публичната спецификация OpenAPI; документацията на API съдържа пълния справочник.

Създайте API ключ

Създайте ключ в раздела „За разработчици“ на таблото. Всяка заявка го носи като bearer токен в заглавката Authorization. Ключът се показва само веднъж при създаването си, затова го запазете в променлива на средата или в мениджър на тайни и го отменете от таблото, ако изтече. Същият ключ служи за парола за WebDAV и FTP, а за потребителско име се използва имейлът на акаунта. Ако още нямате акаунт, създайте безплатен; страницата с цените изброява лимита за размер на файла и квотите за място и трафик, които важат за плана ви.

export UFOLOAD_API_KEY="ufo_..."

Качване с curl

Най-простото качване изпраща файла като сурово тяло на заявката и слага името му в заглавката X-File-Name. Изпращайте името процентно кодирано (UTF-8), ако съдържа интервали или знаци извън ASCII. По подразбиране файлът попада в основната папка; добавете ?folder_id= или заглавка 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

Работи и multipart форма. Файлът отива в полето file, а папката може да се подаде като поле folder_id във формата:

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

Успешното качване отговаря с 201 и JSON тяло, съдържащо обекта на файла. Полетата, които ще използвате най-често, са id, public_id (краткият код, който влиза в адресите на плейъра), status, duration_ms и max_quality. Сървърът не заема допълнително място за съдържание, което вече има: ако качите същите байтове отново, той отговаря с 200, съществуващия файл и "duplicate": true, като сравнява файловете по SHA-256 хеш.

Изчакайте видеото да е готово

Качването е само първата половина. След него файлът се поставя на опашка и се кодира в адаптивна HLS стълбица (вижте как се изгражда стълбицата). Неговият status минава през uploading, queued и processing и завършва с ready или failed; неуспешният файл носи съобщение в error. Проверявайте файла на всеки няколко секунди и никога в плътен цикъл: API има ограничение на заявките и отговаря с 429.

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

Отговорът има две части: file с метаданните и links с подписани адреси за главния плейлист (playback), корицата (poster), спрайта за преглед при посочване (sprite), всяка версия и expires_at. Ако ви трябва друг срок на валидност, POST /files/{id}/links издава връзки, валидни от 60 секунди до 30 дни, по желание обвързани с IP адрес или бисквитка.

Python

С библиотеката requests подаването на отворения файлов обект го предава поточно от диска, така че паметта не расте дори при големи видеа. Функцията по-долу качва и след това изчаква резултата.

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 и по-новите имат вграден fetch, така че не са нужни зависимости. Тази версия чете файла в паметта, което е наред за клипове и кратки видеа; за файлове от няколко гигабайта предпочетете curl, WebDAV или FTP, които предават поточно от диска.

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)

Импорт по URL

Ако видеото вече е онлайн на директна връзка, оставете сървъра да го изтегли, вместо да го сваляте на своята машина и да го качвате отново. Извикването веднага връща 202 със задача за импорт; сървърът изтегля файла и след това го поставя на опашка за кодиране. Връзки към вътрешни мрежи, loopback и служебни диапазони от адреси се отхвърлят, можете да имате до десет активни импорта, а GET /files/import показва напредъка.

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

За масови прехвърляния и за инструменти, които не могат да извикват API, същата библиотека е достъпна през WebDAV и FTP. Потребителското име е имейлът на акаунта, а паролата е API ключ. И двата протокола предават поточно от диска и са най-надеждният вариант за много големи файлове.

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/

Използвайте криптираните варианти винаги, когато клиентът ви ги поддържа, тъй като API ключът е паролата. Всеки клиент, който говори WebDAV или FTPS — от файлови мениджъри до инструменти за синхронизация, — може да използва същите данни. Копираните така файлове се появяват в библиотеката ви и се кодират като всяко друго качване.

Кой път да изберете

Използвайте видеото

Щом статусът е ready, адресът на плейъра е https://iframe.andromedans.live/e/, последван от public_id — точно това поставяте в iframe (дългият id също работи и се пренасочва към краткия адрес); ръководството за вграждане показва разметката и алтернативата с hls.js. Можете да ограничите къде се възпроизвежда с правила по домейн и държава, а когато рекламата е налична — да я включите, за да печелите от гледанията. Пазете ключа извън кода в браузъра, сменяйте го, когато хора напускат екипа ви, и помнете, че API е достъпен във всеки план, така че можете да започнете още днес.