Unggah Video lewat API: curl, Python, Node.js, WebDAV, dan FTP

Anda dapat menaruh video di UFOLOAD tanpa pernah membuka dasbor. REST API menerima unggahan lewat HTTPS, server dapat mengambil file dari tautan untuk Anda, dan akun yang sama dapat diakses lewat WebDAV dan FTP untuk alat yang sudah mendukung protokol tersebut. Panduan ini membahas kelima jalur dengan perintah yang berfungsi, menjelaskan jawaban server, dan menunjukkan cara menunggu hingga encoding selesai. Endpoint di bawah telah dicocokkan dengan spesifikasi OpenAPI publik; dokumentasi API berisi referensi lengkapnya.

Buat kunci API

Buat kunci di bagian Pengembang pada dasbor Anda. Setiap permintaan membawanya sebagai bearer token di header Authorization. Kunci hanya ditampilkan sekali saat dibuat, jadi simpan di variabel lingkungan atau pengelola rahasia, dan cabut dari dasbor jika bocor. Kunci yang sama berfungsi sebagai kata sandi untuk WebDAV dan FTP, dengan email akun Anda sebagai nama pengguna. Jika Anda belum punya akun, buat akun gratis; halaman harga mencantumkan batas ukuran file serta kuota penyimpanan dan trafik yang berlaku untuk paket Anda.

export UFOLOAD_API_KEY="ufo_..."

Unggah dengan curl

Unggahan paling sederhana mengirim file sebagai isi mentah permintaan dan menaruh namanya di header X-File-Name. Kirim nama dalam bentuk percent-encoding (UTF-8) jika mengandung spasi atau karakter non-ASCII. Secara bawaan, file masuk ke folder root; tambahkan ?folder_id= atau header X-Folder-Id untuk memilih folder lain.

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

Formulir multipart juga berfungsi. File dimasukkan ke field file dan folder dapat diberikan sebagai field formulir folder_id:

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

Unggahan yang berhasil menjawab 201 dengan isi JSON yang memuat objek file. Field yang paling sering Anda pakai adalah id, public_id (kode pendek yang dimasukkan ke alamat pemutar), status, duration_ms, dan max_quality. Server tidak memakai ruang tambahan untuk konten yang sudah dimilikinya: jika Anda mengunggah byte yang sama lagi, server menjawab 200 dengan file yang sudah ada dan "duplicate": true, dengan mencocokkan file berdasarkan hash SHA-256-nya.

Tunggu hingga video siap

Mengunggah barulah separuh pertama. Setelahnya, file masuk antrean dan di-encode menjadi tangga HLS adaptif (lihat cara tangga bitrate dibangun). status-nya bergerak melalui uploading, queued, dan processing, lalu berakhir di ready atau failed; file yang gagal membawa pesan error. Lakukan polling file setiap beberapa detik, dan jangan pernah dalam loop yang rapat: API memiliki batas laju dan akan menjawab 429.

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

Jawabannya terdiri dari dua bagian: file dengan metadata, dan links dengan alamat bertanda tangan untuk master playlist (playback), sampul (poster), sprite pratinjau saat kursor diarahkan (sprite), setiap versi video, dan expires_at. Jika Anda memerlukan masa berlaku lain, POST /files/{id}/links menerbitkan tautan yang berlaku dari 60 detik hingga 30 hari, opsional diikat ke alamat IP atau cookie.

Python

Dengan pustaka requests, meneruskan objek file yang terbuka akan mengalirkannya dari disk, sehingga penggunaan memori tetap datar bahkan untuk video besar. Fungsi di bawah mengunggah, lalu menunggu hasilnya.

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 ke atas sudah memiliki fetch bawaan, sehingga tidak diperlukan dependensi. Versi ini membaca file ke memori, yang tidak masalah untuk klip dan video pendek; untuk file berukuran beberapa gigabyte, lebih baik gunakan curl, WebDAV, atau FTP, yang mengalirkan data dari disk.

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)

Impor lewat URL

Jika video sudah tersedia daring lewat tautan langsung, biarkan server yang mengunduhnya alih-alih Anda menariknya ke komputer lalu mengunggahnya lagi. Panggilan ini langsung mengembalikan 202 dengan tugas impor; server mengambil file lalu memasukkannya ke antrean encoding. Tautan ke jaringan internal, loopback, dan rentang alamat layanan ditolak, Anda dapat memiliki hingga sepuluh impor aktif, dan GET /files/import menampilkan progresnya.

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

Untuk transfer massal dan untuk alat yang tidak dapat memanggil API, pustaka yang sama tersedia lewat WebDAV dan FTP. Nama penggunanya adalah email akun Anda dan kata sandinya adalah kunci API. Keduanya mengalirkan data dari disk dan merupakan opsi paling andal untuk file yang sangat besar.

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/

Gunakan varian terenkripsi setiap kali klien Anda mendukungnya, karena kunci API adalah kata sandinya. Klien apa pun yang mendukung WebDAV atau FTPS, dari pengelola file hingga alat sinkronisasi, dapat memakai detail yang sama. File yang disalin dengan cara ini muncul di pustaka Anda dan di-encode seperti unggahan lainnya.

Jalur mana yang dipilih

Gunakan videonya

Setelah statusnya ready, alamat pemutar adalah https://iframe.andromedans.live/e/ diikuti public_id, dan itulah yang Anda masukkan ke iframe (id panjang juga berfungsi dan dialihkan ke alamat pendek); panduan menyematkan menunjukkan markup-nya dan alternatif hls.js. Anda dapat membatasi tempat video diputar dengan aturan domain dan negara, dan, saat iklan tersedia, mengaktifkannya untuk memperoleh pendapatan dari penayangan. Jauhkan kunci dari kode browser, ganti kunci saat ada anggota yang keluar dari tim Anda, dan ingat bahwa API tersedia di setiap paket, jadi Anda bisa mulai membangun hari ini.