Завантаження відео через API: curl, Python, Node.js, WebDAV і FTP

Розмістити відео на UFOLOAD можна, жодного разу не відкриваючи кабінет. REST API приймає завантаження через HTTPS, сервер може сам забрати файл за посиланням, а той самий акаунт доступний через WebDAV і FTP для інструментів, які вже працюють із цими протоколами. У цьому посібнику розібрано всі п'ять шляхів із робочими командами, пояснено, що відповідає сервер, і показано, як дочекатися завершення кодування. Наведені нижче ендпоінти звірено з публічною специфікацією OpenAPI; повний довідник — у документації API.

Створіть API-ключ

Створіть ключ у розділі «Розробникам» вашого кабінету. Кожен запит передає його як bearer-токен у заголовку Authorization. Ключ показується лише один раз під час створення, тож збережіть його у змінній середовища або в менеджері секретів і відкличте в кабінеті, якщо він потрапить у чужі руки. Той самий ключ слугує паролем для WebDAV і FTP, а логіном — email вашого акаунта. Якщо акаунта ще немає, створіть безкоштовний; на сторінці тарифів наведено ліміт розміру файлу та квоти сховища й трафіку для вашого тарифу.

export UFOLOAD_API_KEY="ufo_..."

Завантаження через curl

Найпростіше завантаження надсилає файл як сире тіло запиту, а його ім'я — у заголовку X-File-Name. Якщо ім'я містить пробіли чи символи поза ASCII, надсилайте його у percent-кодуванні (UTF-8). За замовчуванням файл потрапляє в кореневу папку; додайте ?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; файл зі статусом 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-адреси або cookie.

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. Логін — email вашого акаунта, пароль — 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 доступний на будь-якому тарифі, тож почати можна вже сьогодні.