API ile Video Yükleme: curl, Python, Node.js, WebDAV ve FTP

UFOLOAD'a kontrol panelini hiç açmadan video koyabilirsiniz. REST API, HTTPS üzerinden yükleme kabul eder, sunucu sizin için bir dosyayı bir bağlantıdan çekebilir ve aynı hesaba, bu protokolleri zaten kullanan araçlar için WebDAV ve FTP üzerinden de erişilebilir. Bu rehber beş yolun hepsini çalışan komutlarla anlatıyor, sunucunun ne yanıt verdiğini açıklıyor ve kodlamanın bitmesini nasıl bekleyeceğinizi gösteriyor. Aşağıdaki uç noktalar herkese açık OpenAPI spesifikasyonuyla karşılaştırılarak kontrol edildi; tam başvuru kaynağı API belgelerinde.

Bir API anahtarı oluşturun

Kontrol panelinizin Geliştiriciler bölümünde bir anahtar oluşturun. Her istek onu Authorization başlığında bearer token olarak taşır. Anahtar yalnızca oluşturulduğunda bir kez gösterilir; bu yüzden onu bir ortam değişkeninde veya bir gizli bilgi yöneticisinde saklayın ve sızarsa kontrol panelinden iptal edin. Aynı anahtar, kullanıcı adı olarak hesap e-postanızla birlikte WebDAV ve FTP için parola olarak da çalışır. Henüz hesabınız yoksa ücretsiz bir hesap oluşturun; fiyatlandırma sayfası planınız için geçerli dosya boyutu sınırını ve depolama ile trafik kotalarını listeliyor.

export UFOLOAD_API_KEY="ufo_..."

curl ile yükleme

En basit yükleme, dosyayı ham istek gövdesi olarak gönderir ve adını X-File-Name başlığına koyar. Ad boşluk veya ASCII dışı karakterler içeriyorsa onu yüzde kodlamasıyla (UTF-8) gönderin. Varsayılan olarak dosya kök klasöre gider; başka bir klasör seçmek için ?folder_id= ya da bir X-Folder-Id başlığı ekleyin.

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

Çok parçalı (multipart) bir form da çalışır. Dosya file alanına girer, klasör ise bir folder_id form alanı olarak verilebilir:

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

Başarılı bir yükleme, dosya nesnesini içeren bir JSON gövdesiyle 201 yanıtı verir. En sık kullanacağınız alanlar id, public_id (oynatıcı adreslerine giren kısa kod), status, duration_ms ve max_quality alanlarıdır. Sunucu zaten sahip olduğu içerik için ek alan kullanmaz: aynı baytları yeniden yüklerseniz, dosyaları SHA-256 özetlerine göre eşleştirerek mevcut dosyayla ve "duplicate": true ile 200 yanıtı verir.

Video hazır olana kadar bekleyin

Yükleme işin yalnızca ilk yarısıdır. Ardından dosya kuyruğa alınır ve uyarlanabilir bir HLS merdivenine kodlanır (bkz. merdiven nasıl kurulur). status değeri uploading, queued ve processing aşamalarından geçer ve ready ya da failed ile sona erer; başarısız bir dosya bir error mesajı taşır. Dosyayı birkaç saniyede bir sorgulayın, asla sıkı bir döngüde değil: API hız sınırlıdır ve 429 yanıtı verir.

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

Yanıtın iki bölümü vardır: meta verileri içeren file ve ana oynatma listesi (playback), kapak (poster), üzerine gelince önizleme sprite'ı (sprite), her sürüm ve expires_at için imzalı adresleri içeren links. Farklı bir geçerlilik süresine ihtiyacınız varsa, POST /files/{id}/links 60 saniyeden 30 güne kadar geçerli, isteğe bağlı olarak bir IP adresine veya bir çereze bağlanmış bağlantılar üretir.

Python

requests kütüphanesiyle açık dosya nesnesini iletmek onu diskten akış halinde gönderir; böylece büyük videolarda bile bellek kullanımı sabit kalır. Aşağıdaki fonksiyon yükleme yapar, ardından sonucu bekler.

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 ve sonrasında fetch yerleşik olarak gelir, bu yüzden hiçbir bağımlılık gerekmez. Bu sürüm dosyayı belleğe okur; klipler ve kısa videolar için bu sorun değildir. Çok gigabaytlık dosyalar için diskten akış halinde gönderen curl, WebDAV veya FTP'yi tercih edin.

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 ile içe aktarma

Video zaten doğrudan bir bağlantıda çevrimiçiyse, onu kendi makinenize çekip yeniden göndermek yerine sunucunun indirmesine izin verin. Çağrı bir içe aktarma göreviyle hemen 202 döndürür; sunucu dosyayı çeker ve ardından kodlama için kuyruğa alır. Dahili ağlara, loopback'e ve hizmet adres aralıklarına giden bağlantılar reddedilir, aynı anda en fazla on etkin içe aktarmanız olabilir ve GET /files/import ilerlemeyi gösterir.

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

Toplu aktarımlar ve API çağıramayan araçlar için aynı kütüphaneye WebDAV ve FTP üzerinden erişilebilir. Kullanıcı adı hesap e-postanız, parola ise bir API anahtarıdır. İkisi de diskten akış halinde gönderir ve çok büyük dosyalar için en sağlam seçenektir.

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 anahtarı parola olduğu için istemciniz destekliyorsa her zaman şifreli varyantları kullanın. Dosya yöneticilerinden eşitleme araçlarına kadar WebDAV veya FTPS konuşan her istemci aynı bilgileri kullanabilir. Bu yolla kopyalanan dosyalar kütüphanenizde görünür ve diğer tüm yüklemeler gibi kodlanır.

Hangi yolu seçmeli

Videoyu kullanın

Durum ready olduğunda oynatıcı adresi, https://iframe.andromedans.live/e/ ve ardından gelen public_id değeridir; iframe'e koyacağınız da tam olarak budur (uzun id de çalışır ve kısa adrese yönlendirilir). Yerleştirme rehberi işaretlemeyi ve hls.js alternatifini gösteriyor. Videonun nerede oynatılacağını alan adı ve ülke kurallarıyla kısıtlayabilir ve reklamlar kullanılabilir olduğunda bunları etkinleştirerek görüntülemelerden kazanabilirsiniz. Anahtarı tarayıcı kodunun dışında tutun, ekibinizden biri ayrıldığında yenileyin ve API'nin her planda kullanılabildiğini unutmayın; yani bugün geliştirmeye başlayabilirsiniz.