APIUploadWebDAV

APIで動画をアップロード:curl、Python、Node.js、WebDAV、FTP

UFOLOADのREST APIを使い、curl、Python、Node.jsで動画をアップロード・インポートし、エンコード完了を待つ方法と、大きなファイル向けのWebDAV・FTPの使い方。

ダッシュボードを一度も開かずに、UFOLOADに動画を載せることができます。REST APIはHTTPS経由でアップロードを受け付け、サーバーがリンクからファイルを取得することもでき、同じアカウントには、すでにWebDAVやFTPに対応したツールからもアクセスできます。このガイドでは、5つの方法すべてを動作するコマンドとともに紹介し、サーバーの応答内容を説明し、エンコード完了を待つ方法を示します。以下のエンドポイントは公開OpenAPI仕様と照合済みです。完全なリファレンスはAPIドキュメントにあります。

APIキーを作成する

ダッシュボードの「開発者」セクションでキーを作成します。すべてのリクエストは、Authorization ヘッダーのBearerトークンとしてキーを送ります。キーは作成時に一度だけ表示されるため、環境変数かシークレットマネージャーに保存し、漏洩した場合はダッシュボードから失効させてください。同じキーはWebDAVとFTPのパスワードとしても使え、ログインはアカウントのメールアドレスです。まだアカウントがない場合は無料で作成してください。プランに適用されるファイルサイズ上限、ストレージ容量、トラフィック枠は料金ページに掲載しています。

bash
export UFOLOAD_API_KEY="ufo_..."

curlでアップロードする

最も簡単なアップロードは、ファイルをリクエストボディにそのまま入れて送り、ファイル名を X-File-Name ヘッダーに入れる方法です。名前にスペースや非ASCII文字が含まれる場合は、パーセントエンコード(UTF-8)して送ってください。デフォルトではファイルはルートフォルダーに入ります。別のフォルダーを選ぶには ?folder_id= か X-Folder-Id ヘッダーを追加します。

Rawボディ · bash
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

マルチパートフォームでも送れます。ファイルは file フィールドに入れ、フォルダーは folder_id フォームフィールドで指定できます:

マルチパートフォーム · bash
curl -X POST "https://ufoload.com/api/v1/files" \
  -H "Authorization: Bearer $UFOLOAD_API_KEY" \
  -F "file=@holiday-2026.mp4"

アップロードが成功すると、ファイルオブジェクトを含むJSONボディとともに 201 が返されます。よく使うフィールドは id、public_id(プレーヤーのアドレスに入る短いコード)、status、duration_ms、max_quality です。サーバーはすでにあるコンテンツのために余分な容量を使いません。同じバイト列を再度アップロードすると、SHA-256ハッシュでファイルを照合し、既存のファイルと "duplicate": true とともに 200 を返します。

ステータス意味
201ファイルが受け付けられ、処理キューに入った
200同じコンテンツがすでにライブラリにある。duplicate は true
401キーがない、または無効
404保存先のフォルダーが存在しない
409ストレージが不足している
413ファイルがプランの上限を超えている
429リクエストが多すぎる。待ってから再試行する
ヒント

大きなアップロードには、通常のAPI呼び出しに適用される短いリクエストタイムアウトはかかりません。サーバーはボディが届き続ける限り受け付けるため、低速な回線でも数ギガバイトのアップロードが途切れることはありません。ただし、ブロック間の停止が長すぎるとリバースプロキシで切断されることがあります。

動画の準備完了を待つ

アップロードは前半にすぎません。その後ファイルはキューに入り、アダプティブなHLSラダーにエンコードされます(ラダーの構成方法を参照)。status は uploading、queued、processing と進み、ready か failed で終わります。失敗したファイルには error メッセージが付きます。ファイルは数秒おきにポーリングし、間隔を空けないループは絶対に避けてください。APIにはレート制限があり、429 が返されます。

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

応答は2つの部分からなります。メタデータを含む file と、マスタープレイリスト(playback)、カバー(poster)、ホバープレビューのスプライト(sprite)、各レンディションの署名付きアドレスと expires_at を含む links です。別の有効期間が必要なら、POST /files/{id}/links で60秒〜30日有効なリンクを発行でき、必要に応じてIPアドレスやcookieに紐付けられます。

Python

requests ライブラリでは、開いたファイルオブジェクトを渡すとディスクからストリーム送信されるため、大きな動画でもメモリ使用量は一定に保たれます。以下の関数はアップロードしてから結果を待ちます。

python
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を使ってください。

js
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 を返し、サーバーがファイルを取得してからエンコードのキューに入れます。内部ネットワーク、ループバック、サービス用アドレス範囲へのリンクは拒否されます。同時に実行できるインポートは最大10件で、進行状況は GET /files/import で確認できます。

bash
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キーです。どちらもディスクからストリーム送信するため、非常に大きなファイルには最も堅牢な選択肢です。

HTTPS経由のWebDAV、ポート443 · bash
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
明示的TLSのFTP、ポート21 · bash
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に対応したクライアントなら同じ接続情報を使えます。この方法でコピーしたファイルはライブラリに表示され、他のアップロードと同様にエンコードされます。

どの方法を選ぶか

方法最適な用途注意点
APIでのアップロードユーザーに代わってアップロードするアプリケーションやバックエンドクライアントがファイル全体を先に読み込む場合のメモリ使用量
URLからのインポートすでに公開の直接リンクがあるファイルhttp(s)の直接リンクのみ。同時インポートは10件まで
WebDAV大きなファイル、ライブラリをドライブとしてマウント認証情報にはメールアドレスとAPIキーを使う
FTP / FTPS既存のツールやスクリプト、一括転送明示的TLSのオプションを使う

動画を活用する

ステータスが ready になれば、プレーヤーのアドレスは https://iframe.andromedans.live/e/ の後に public_id を続けたもので、これがそのままiframeに入れるアドレスです(長い id でも動作し、短いアドレスにリダイレクトされます)。マークアップとhls.jsによる代替方法は埋め込みガイドで紹介しています。ドメインと国のルールで再生できる場所を制限でき、広告が利用可能なら有効にして視聴から収益を得ることもできます。キーはブラウザーのコードに含めず、チームからメンバーが抜けたらローテーションしてください。APIはすべてのプランで利用できるので、今日から開発を始められます。

無料アカウントで試してみる

動画をアップロードすれば、数分でHLSプレーヤーとAPIキーが手に入ります。プランごとの上限は料金ページに掲載しています。