hiapi API で flux-3 を使って AI 動画編集を行う方法

ここでいう「編集」には特定の意味があります。flux-3（FLUX.3 Video、Black Forest Labs 製）は既存のクリップを拡張します——その動き、カメラワーク、サウンドを引き継いで新しい映像を生成します——あるいは順序付けられた一連のキーフレーム画像を基にショットを構築します。既存の素材をクロップしたり、カットしたり、マスクしたり、カラーグレーディングしたり、その他のインプレース処理を行ったりはしません。動画エディタを探しに来たのであれば、以下の FAQ が、コードを書く前に flux-3 が本当に自分に適しているかを判断する最速の方法です。

これが本当に得意とするのは、手持ちの動画を取り、同じ被写体、レンズ言語、音声を保ったまま続きを生成することです——早すぎる終わり方をするショットを延長したり、複数の生成クリップをつなげてより長いショットにしたりするのに適しています。もう一つのモードは、一連の静止画を順序付きキーフレームとして受け取り、それらの間の動きを生成します。これは絵コンテに基づく編集のようなものですが、既存の動画は一切関係しません。

1. 必要なもの

ダッシュボードから取得した hiapi API キー（sk-...）が1つ。flux-3 は他のすべての hiapi モデルと同様、統一された task API で呼び出されるため、ここにモデル固有のセットアップは一切ありません——他の hiapi 動画モデルを呼び出したことがあれば、準備はもう整っています。

2. 最小動作例

タスクを作成し、終了状態に達するまでポーリングします（またはコールバックを使用——本番パターンを参照）。

# 1. タスクを作成——継続モード（start_video）
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3",
    "input": {
      "prompt": "パン動作を継続し、カメラは右へドリフトし続け、同じ照明を保つ",
      "start_video": "https://your-cdn.example.com/source-clip.mp4",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. 終了状態までポーリング
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

start_video は MP4 を指す公開 HTTPS URL です（ソース素材は最大 50MB、15 秒まで）——これが flux-3 の続きとなるクリップです。duration は 5〜20 秒の整数で、新たに生成されるクリップの長さを制御するもので、合成後の出力全体の長さではありません。resolution は 720p または 1080p です。aspect_ratio は auto、21:9、2:1、16:9、4:3、1:1、3:4、9:16 を受け付けます。generate_audio はブール値です——true の場合、モデルが生成した環境音が別の音声ファイルとしてではなく、出力 MP4 に直接焼き込まれます。プロンプトを反復する際には draft: true を設定してください。ドラフトタスクは安価ですが、resolution は 720p に固定されます（draft: true と resolution: "1080p" を同時に指定したリクエストは拒否されます）。

キーフレーム絵コンテ（既存素材の編集ではない）

もう一つの入力モードは start_video の代わりに image_urls を使用します——1〜10 個の画像 URL を含む順序付き配列で、flux-3 はこれを絵コンテとして扱い、それらを順に接続する動きを生成します：

{
  "model": "flux-3",
  "input": {
    "prompt": "各シーンを順にスムーズにドリーインする",
    "image_urls": [
      "https://your-cdn.example.com/keyframe-1.jpg",
      "https://your-cdn.example.com/keyframe-2.jpg",
      "https://your-cdn.example.com/keyframe-3.jpg"
    ],
    "duration": 8,
    "resolution": "720p"
  }
}

image_urls と start_video は同じモデル上の2つの異なるタスク形態です——1つのリクエストで両方を同時に送信しないでください。静止画からゼロベースでショットを構築する場合は image_urls を使用し、既に生成済み（またはソース）の素材を先へ延長したい場合は start_video を使用します。

3. 本番パターン

大規模運用時はポーリングの代わりにコールバックを使用します。 ループでポーリングするのではなく、同じリクエストボディに callback オブジェクトを渡します：

{
  "model": "flux-3",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" はタスクが任意の終了状態に達した時に一度だけ発火します——succeeded も failed も終了状態であるため、コールバックは成功を意味するものと仮定せず、taskId で webhook ハンドラを重複排除してください。GET /v1/tasks/:id のポーリングは、ローカルでのデバッグ、低頻度の単発タスク、またはコールバックが届かなかった場合の照合フォールバックとしてより適しています。

冪等性。 不注意だと、タイムアウトや接続断の後のリトライが重複した（課金対象の）タスクを作成する可能性があります——作成呼び出しが返すタスク id を追跡し、新しいタスクを送信することを検討する前に、リトライをその id への GET に変えてください。

出力 URL は期限切れになります。 各出力エントリの expireAt フィールドは飾りではありません——コールバックでもポーリングでもタスク成功を知ったら、タスク成功後すぐに動画をダウンロードし、自分のストレージに永続化してください。

認証失敗。 誤った、または欠落したキーは HTTP 401 を返し、内容は {"error": {"code": "permission_denied", ...}} です。2xx 以外はすべて生成自体の失敗だと仮定せず、そのステータス/コードを明示的にチェックしてください——「キーが間違っている」と「モデルが入力を受け付けなかった」では修正方法が異なります。

送信前にメディア URL を検証してください。 start_video と image_urls は型とフォーマットをチェックしますが、その URL のファイルが実際に存在するか、デコード可能かはチェックしません——構文的には有効でも壊れた URL はタスクを正常に作成でき、送信時に拒否されるのではなく、数秒間実行した後に失敗します。URL をバッチタスクに組み込む前に、それらが実際に解決できることを確認してください。

4. 関連ページ

• flux-3 モデルページ——完全なパラメータリファレンス、プレイグラウンド、および3つのモードすべて（テキストから動画、キーフレーム絵コンテ、継続）の現在の秒単位・解像度別料金。
• タスク作成ドキュメント——コールバックオプションを含む、完全な /v1/tasks のリクエスト/レスポンスリファレンス。
• 認証ドキュメント——Authorization: Bearer sk-... ヘッダーとキースコープの仕組み。
• AI 動画における最初/最後のフレーム制御——flux-3 のマルチキーフレーム絵コンテモードがあなたのショットにとって十分に精细でない場合に適した、2つの静止画フレーム間を補間するモデル向けの関連手法。
• hiapi 料金——現在のレート（継続は標準生成より高価で、ドラフトモードはどちらよりも安価です——ハードコードされた数値ではなく、ライブページを確認してください）。

5. よくある質問

flux-3 は既存の動画をクロップ、カット、マスク、またはカラーグレーディングできますか？ いいえ。flux-3 の「動画から動画」モードは継続です——ソースクリップの被写体、カメラワーク、サウンドを引き継いで新しい映像を生成します。既存のフレームを修正することはありません。現在、hiapi のモデルで動画に対するタイムライン式のクロップ/カット編集やマスク領域編集ができるものはありません。

継続とキーフレーム絵コンテの違いは何ですか？ 継続（start_video）は既存の動画ファイルを必要とし、それを拡張します。キーフレーム絵コンテ（image_urls）は静止画のみを必要とし、それらの間の動きを生成します——ソース動画は不要です。これらは同じ flux-3 モデル id 上の相互排他的な入力です。

1つのリクエストで start_video と image_urls を同時に使用できますか？ いいえ——各タスクは1つのモードを選択します。両方を同時に送信することはサポートされる入力形態ではありません。

draft: true は継続モードで使用できますか？ はい、そしてフル解像度の実行を送信する前に継続プロンプトを反復する安価な方法です——ただし標準モードと同様、ドラフト継続も 720p に制限されます。

なぜ私のタスクは通常の生成時間をかけずにほぼ瞬時に失敗するのですか？ 最も一般的な原因は、start_video または image_urls のエントリがリクエスト時に実際には有効なファイルに解決されていないことです——API は構文的に正しい URL を受け付けますが、同期的に取得することはないため、壊れたリンクは事前の検証エラーではなく、迅速な failed 状態として現れます。

継続モードでソースクリップはどれくらいの長さにできますか？ 最大 15 秒、50MB、フォーマットは MP4 です。より長い、またはより大きなソースファイルは start_video 入力として受け付けられません。