ƒƒffhub.io

クイックスタート

FFHub クラウド FFmpeg API を 3 分で動かす。

このページでは初回の API コールを通します：API キー取得 → タスク投入 → 結果取得。

1. API キーを取得

ffhub.io でアカウント登録し、ダッシュボードの API Keys でキーを作成します。sk_xxxxx の形式です。漏らさないでください。

新規登録で無料クレジットが付くので、以下の手順は無料で試せます。

GET /v1/me で API キーを検証します。Authorization: Bearer YOUR_API_KEY を付けると、有効なキーにはアカウント情報と HTTP 200、無効なキーには HTTP 401 が返ります。接続の検証には、タスク取得ではなくこのエンドポイントを使用してください。

2. タスクを投入

任意の FFmpeg コマンドを POST /v1/tasks に投げるだけ。入力は公開 URL である必要があります（ローカルパスはクラウドワーカーに拒否されます）。

curl -X POST https://api.ffhub.io/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ffmpeg -i https://storage.ffhub.io/Sample_Video_File_100MB.mp4 -c:v libx264 -preset fast output.mp4"
  }'

const res = await fetch("https://api.ffhub.io/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FFHUB_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    command:
      "ffmpeg -i https://storage.ffhub.io/Sample_Video_File_100MB.mp4 -c:v libx264 -preset fast output.mp4",
  }),
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.ffhub.io/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['FFHUB_API_KEY']}"},
    json={
        "command": "ffmpeg -i https://storage.ffhub.io/Sample_Video_File_100MB.mp4 -c:v libx264 -preset fast output.mp4",
    },
)
task_id = res.json()["task_id"]

レスポンスの task_id を使ってステータスをポーリングします：

{
  "task_id": "01abcd…"
}

3. 完了までポーリング

curl https://api.ffhub.io/v1/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

status が pending または running の間は 2〜5 秒間隔で確認し、succeeded または failed になったらポーリングを終了します。succeeded の場合のみ outputs からファイルをダウンロードしてください。failed の場合は error を読み、失敗を報告します。取得リクエストの HTTP 成功は、処理タスクの成功を意味しません。以下は成功レスポンスの抜粋です：

{
  "task_id": "01abcd…",
  "status": "succeeded",
  "progress": 100,
  "outputs": [
    {
      "filename": "output.mp4",
      "url": "https://storage.ffhub.io/outputs/01abcd…/output.mp4",
      "size": 10485760
    }
  ]
}

タスク取得レスポンスには created_at が含まれ、終了後には finished_at も含まれます。これらはタイムゾーン付きの ISO 8601 タイムスタンプで、小数秒を含む場合があります。例えば 2026-05-10T12:00:00Z と 2026-05-10T12:00:00.123Z はどちらも有効です。終了前は finished_at が存在しない場合があります。欠落した値を解析したり、終了時刻として扱ったりしないでください。

出力ファイルはタスク完了から 7 日 で削除されます。残したいファイルは早めにダウンロードしてください。

ローカルファイルをアップロード

入力がまだ公開 URL でない場合、先にアップロードして URL を取得します。2 ステップです：

# 1. 使い捨ての署名付き PUT URL をリクエスト
SIGNED=$(curl -s -X POST https://api.ffhub.io/v1/uploads/sign \
  -H "Authorization: Bearer $FFHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"input.mp4","size":12345678,"content_type":"video/mp4"}')

# 2. ファイルを R2 に直接 PUT — サーバーはバイトを一切経由しません
curl -fsS -X PUT "$(echo "$SIGNED" | jq -r '.upload_url')" \
  -H "Content-Type: video/mp4" \
  --data-binary "@./input.mp4" || { echo "アップロードに失敗しました"; exit 1; }

# 返ってきた .public_url フィールドが、タスクコマンドの `-i` に渡す URL です。

詳しい手順は ファイルアップロード を参照してください。

次に

  • CLI — ターミナルから直接実行、ローカルファイルは自動アップロード
  • n8n 連携 — ビジュアルワークフロー
  • Claude Code スキル — Claude Code から FFHub を呼ぶ
  • OpenAPI 仕様 — 全エンドポイントの詳細