Video Head Swap API

Video Head Swap は、解析のタスク ID、そのプレビュー画像から選んだ位置、位置ごとの参照写真 1〜3 枚を受け取り、その頭部を差し替えたクリップを返します。髪・頭の形・人物像は変わりますが、体・衣装・動き・画角・元の音声トラックは撮影時のまま残ります。挙げなかった頭部には手が加わりません。

Video Head Swap は 2 回の呼び出しで完結します。1 回目は 5〜30 秒のクリップから頭部をすべて追跡し、頭部ごとのプレビュー静止画を決まった順序で返します。2 回目では選んだ位置と、それぞれに 1〜3 枚の参照写真を渡すと、その頭部だけが差し替わり、元の音声がそのまま残ったクリップが返ってきます。

Head Swap の動画解析 → Head Swap の動画編集

誰を変えるかは利用者が決めます

この種のエンドポイントの多くは、どの人物を指しているのかを推測するしかありません。ここでは 1 回目が検出した頭部を番号付きで一覧し、2 回目は返された番号だけに手を加えます。4 人が映るクリップで 1 人だけを変え、残り 3 人は撮影時のまま残せます。

動画と解像度を 2 回とも同じにする

Video Head Swap は単独のエンドポイントではなく、2 つで 1 組です。1 回目の video-analyze は 5〜30 秒のクリップ内の頭部をすべて追跡し、頭部ごとのプレビュー静止画を決まった順序で返します。課金はリクエスト単位の定額で、クリップの長さにも検出数にも左右されません。2 回目の video-edit には、その解析のタスク ID と、選んだ位置、位置ごとの参照写真 1〜3 枚を渡します。返ってくるのは元の音声トラックを保ったクリップ 1 本で、480p または 720p の解像度に応じて秒単位で課金されます。追跡データそのものが利用者側に出ることはありません。扱うのは自分のタスク ID と、見せられたプレビュー画像に対応する 0 始まりの位置番号だけです。2 回の呼び出しは同じ動画・同じ解像度で行う必要があり、食い違いは黙って通さず 2 回目を拒否します。

すでに成立しているカットのキャスト変更

照明も立ち位置もカメラワークも承認済みのテイクをそのまま活かし、演者の頭部だけを差し替えます。ショット全体を作り直して芝居を失う必要はありません。

同意を得た演者なら題材は問わない

映像に何が映っていても、リクエストの形は変わりません。同時に、下の「制限」に書かれた許諾の条件も変わりません。形式的な注意書きではなく、満たすべき条件です。

生成したシリーズ全体で同じ人物

任意の動画モデルでクリップをまとめて生成し、それぞれを解析したうえで、同意を得た同じ頭部を全編に通します。シリーズ全体が一人の人物として読めるようになります。

群衆の中で 1 人だけ変える

複数人が映るシーンを解析し、プレビューを見て、意図した位置だけを返します。ほかの人物には一切手が加わりません。

# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -d '{
  "model": "spicyapi/head-swap-video-v1/video-edit",
  "input": {
    "analysis_task_id": "example",
    "resolution": "720p",
    "swap_targets": [
      {
        "image_urls": [
          "example"
        ],
        "object_index": 0
      }
    ]
  }
}'

# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

認証、完全なスキーマ、ポーリング、エラー処理は API リファレンスを参照してください。