Genjutsu API:オブジェクト置換動画を1本送信する
Genjutsu APIでオブジェクト置換(Object Swap)を1件リクエストする方法を解説。元クリップの準備、ジョブの送信、編集済み動画の取得までの手順を紹介します。

Genjutsu API の動画編集機能は、ジョブが成功として返っても、チームにとって使えないアセットが残ることがあります。クリップの違う部分が処理された、フレーム間で差し替え結果がずれる、誰も出力を保存していなかった、といったケースです。Genjutsu API を組み込む際、私は1回の編集を入力から承認済みファイルまで追跡できるようにします。Higgsfield の API クイックスタートは、送信・ポーリング・取得というフローを説明しています。このガイドでは、そのフローを1件の Object Swap リクエストに当てはめて解説します。
モデルとエンドポイントを提供するのは Higgsfield です。お使いのプロダクトが WaveSpeedAI を利用している場合は、この操作に対応するモデルがモデルディレクトリにあるか、またそのリクエストスキーマがどうなっているかを確認してください。別の動画スワップモデルが Higgsfield のリクエストをそのまま受け付けると思い込まないでください。

Genjutsu の Object Swap リクエスト1件に必要なものは?
1件のリクエストには、ソース動画の URL と 1〜8枚の参照画像 URL が必要です。プロンプトは任意です。resolution のデフォルトは 720p で、480p と 1080p も記載されています。Object Swap API リファレンスでは、モデルは higgsfield/genjutsu/object-swap/v1.0 とされています。動画は4秒以上で、1フレームあたり409,600ピクセル以上である必要があります。
送信前にクリップを確認してください。30秒を超える動画は30秒にトリミングされ、出力はその準備後の長さに従います。意図した編集が34秒の位置にある場合、リクエストが成功してもそれを納品することはできません。先にセグメントを選択し、どのセグメントを送信したかを記録してください。
サーバーサイドのリクエストは、次のような形になります。URL と環境変数はあくまで例です。
curl -X POST \
"https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0" \
-H "Authorization: Key ${HF_KEY}" \
-H "Idempotency-Key: ${EDIT_ID}" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/approved-source.mp4",
"image_urls": ["https://example.com/approved-object.png"],
"prompt": "Replace the featured cup with the reference cup.",
"resolution": "720p"
}'
認証情報はサーバー側で保持してください。 論理的な編集ごとに固定の冪等性キーを付与すれば、送信結果が不明な場合でも、意図せず2つ目のジョブを作ることなく再試行できます。ソースに特定可能な人物が映っている場合や、保護対象の映像・アートワークを使用する場合は、アップロード前に必要な権利と同意を取得してください。これは本番運用上の注意喚起であり、法的助言ではありません。
編集を送信してステータスを追跡する
POST が成功しても、受け付けられたのは作業であり、完成した動画が返るわけではありません。レスポンスの request_id、status_url、cancel_url を、プロダクト側の編集レコードに紐づけて保存してください。これらの URL は自分で組み立てず、返されたものを使用してください。
Higgsfield のリクエストライフサイクルのドキュメントでは、queued と in_progress が非終端状態として挙げられています。ステータスが completed、failed、nsfw、canceled のいずれかになったら待機を終了します。これらの結果は UI 上で区別して表示してください。プロバイダーがすでにジョブを拒否しているのに「処理中」と表示するのは、不親切なフィードバックです。

ポーリングは約2秒間隔で開始し、待ち時間が長くなる場合は間隔を広げてください。 ステータス確認で一時的なネットワークエラーが発生した場合は、ステータス確認を再試行します。ポーリングが1回失敗したからといって、別の編集を POST しないでください。最終ステータスと返されたエラーはリクエスト ID とあわせて保存し、サポート担当が生成の失敗とブラウザセッションの早期終了を区別できるようにします。
完成した動画を取得して確認する
ステータスが completed になったら、結果から video.url を読み取ります。ファイルを自社で管理するストレージにダウンロードし、再生できること、意図した編集と一致していることを確認してください。API ジョブの完了は納品候補ができたことを意味するだけで、承認の判断ではありません。
サムネイルだけで済ませず、確認してください。クリップの冒頭、中盤、終盤で差し替え結果を確認します。特に、オブジェクトが別の被写体の後ろに回り込む場面や、フレームを横切る場面は要注意です。処理された長さと、送信したセグメントを比較してください。音声が機能上重要な場合は、出力の音声トラックも確認してください。Object Swap のリファレンスは、ソース音声が保持されることを保証していません。
単発の出力がうまくいっても、本番ワークフローの準備が整ったとは限りません。プロバイダーの完了は、ファイルが存在することを示すだけです。そのファイルをプロダクトに取り込めるかどうかは、自社の受け入れチェックで判断します。
本番で Object Swap を再現可能にする
再実行できる編集マニフェストを保存する
ソースアセットのバージョン、選択した時間範囲、参照画像のバージョン、プロンプト、解像度、モデル ID、冪等性キー、リクエスト ID、最終ステータスをまとめて保管します。さらに、承認済み出力の保存先も追加してください。パラメーターを覚えていられるのは1人だけです。チームでは覚えていられません。
この記録は、編集担当者から「同じスワップで、青い商品に変えたい」と頼まれたときに役立ちます。final-v3.mp4 というファイル名から前回のリクエストを復元しなくても、チームは入力を1つだけ意図的に変更できます。
元のクリップと承認済み出力をアーカイブする
ロールバック用に元のクリップを保持し、承認済みの結果はプロバイダーの一時的なメディア保存場所の外に保存してください。Higgsfield の保持と同意に関する API 規約では、生成メディアは 少なくとも7日間 利用可能ですが、その後削除される場合があるとされています。これは恒久的な URL の保証ではありません。結果が承認されたのか、却下されたのか、修正のため差し戻されたのかを、その理由とあわせて記録してください。
FAQ

Object Swap はソースクリップの音声を保持しますか?
公開されている Object Swap のリファレンスには記載がありません。プロダクトで音声のパススルーを約束しないでください。音声トラックが判別できる、使用許可済みのクリップでテストし、返されたファイルを確認してから、その機能を謳うようにしてください。
キューに入った Genjutsu リクエストはキャンセルできますか?
はい、キュー内でキャンセル可能な状態にある間は可能です。返された cancel_url にキャンセルリクエストを送信してください。ポーラーを止めるだけでは、ジョブはキャンセルされません。処理が始まると、ドキュメントに記載されたライフサイクルではキャンセルできなくなります。
準備中にソース URL の有効期限が切れるとどうなりますか?
期限付きの Object Swap 入力 URL について、ドキュメントでは、どの時点で失敗するかが一律には規定されていません。Higgsfield が取得する可能性がある間は、ソースにアクセスできる状態を保ってください。準備に失敗した場合は、実際のリクエストステータスとエラーをログに記録します。POST が受け付けられたからといって、ファイルがすでにダウンロード済みであることの証明にはなりません。
入力準備の失敗では課金単位が消費されますか?
報告された失敗の内容によります。Higgsfield の課金と保持に関するガイダンスでは、failed または nsfw で終了したリクエストには課金されず、確保されたクレジットは返金されるとされています。「入力準備の失敗」自体は課金ステータスではないため、そのようなエラーすべてに同じルールを当てはめず、レスポンスと課金記録を確認してください。
完成した動画の URL はどのくらいの期間利用できますか?
生成メディアには少なくとも7日間アクセスできますが、その後削除される場合があります。承認済みの動画は速やかにダウンロードしてください。ユーザーが数週間後に再度アクセスする可能性がある Genjutsu API 機能では、自社ストレージに保存したコピーを配信してください。
過去の記事:
/filters:quality(82)/media/images/1773962750383987480_n3hqzHRZ.webp)
/filters:quality(82)/media/images/3439779b-d7cf-42fd-958d-8711fe2abdf4.webp)