Video Head Swap API：解析、対象選択、編集

Video Head Swap は2段階のAPIワークフローです。5〜30秒のMP4を解析し、番号付きの頭部プレビューを確認し、選んだ位置と差し替え用のポートレートを編集に送信します。顔、髪型、髪の色、頭部の形は変わります。体、服装、動き、音声、そして選択しなかった他の人はすべてそのまま残ります。

ここでは、編集の料金を支払う前に、まず追跡された各頭部を見て、欲しいものを指名します。既存の動画を編集する処理です。静止画2枚を演技として動かすものではありません。それには画像から動画へのモデルを使ってください。

適切な差し替えを選ぶ

元の映像の髪を残せるなら、顔の差し替えのほうが安価でかんたんです。頭部の差し替えは、新しい髪がキャラクターの一部であるときに元が取れます。ただし代償として首の接合部が生じるので、そこは確認する必要があります。

ソースと参照ポートレートを準備する

処理する権限のある肖像だけを使ってください。自分自身、署名済みの許諾書のある演技者、または生成した頭部のいずれかです。写っている全員は成人でなければなりません。両方の呼び出しは規制なしで、SpicyAPI はコンテンツフィルターを追加しないため、この確認は利用者側の責任です。

この例では、錆色のジャケットを着た架空の成人が、12秒の会話の中でもう一人の成人に顔を向けます。置き換えるのは一人目の頭部だけ。二人目の人物、服、会話はそのまま残します。

解析の前に最終ソースを書き出してください。MP4、最大90 MB、5〜30秒。video_url には、MP4そのものを返す公開HTTPSリンク（HTMLプレーヤーページではなく）、または無料のアップロード手順からの spicy:// URI を渡します。ローカルファイルにはこれが最も確実です。後からトリミング、クロップ、再エンコードしてもう一度解析を実行してください。

同じ差し替え先の成人のポートレートを1〜3枚用意します。最初の組み合わせは正面と3/4正面です。ソースに大きな頭部の回転が含まれているなら、プロフィールを追加します。一連の写真の中で髪型と見かけの年齢を揃えます。映像にも合わせましょう。写真の照明は映像が照らされている方向から当て、頭部も似た角度にしてください。首の接合部には不整合が露出し、リクエスト項目でその不揃いを補うことはできません。全身の服装の参照はキャラクター差し替えの範疇です。このタスクには、意図した頭部と髪が明瞭に見える必要があります。

架空の参照画像には、次のようなブリーフを使ってください。

架空の成人男性、およそ35歳、短い暗い髪、整えられたひげ、無表情で、ボタンをすべて留めた無地のシャツを着ている。柔らかく均一な光、顔と髪は遮るものなし、単純な背景。正面像、他の人はいない、文字は入れない。

他のアングルは、承認したその人物像から作成してください。関係のない人物を別々に独立して依頼しないでください。編集には prompt 項目がないため、参照画像が結果のすべてを左右します。

正面・3/4正面・プロフィールの参照セットのイラスト。

まず Playground で試す

1. Video Head Swap の編集ページを開き、Playground タブの Form ビューのまま進みます。実行するには残高のあるアカウントでログインします。
2. ステップ1、Find the people in your clip. クリップを Input video に追加し（MP4 をドロップするか Asset URL を使う）、Resolution で 480p か 720p かを選びます。編集側でも同じ値を使う必要があるため、完成したクリップに持たせたい解像度を選んでください。Find people in this clip を押します（$0.08）。
3. ステップ2、Choose who to replace. 追跡された各頭部は、番号付きのプレビューとして表示されます。欲しいものを選び、差し替え先の成人の参照写真を1〜3枚追加します。Seed を設定するのは、参照セットを公平に比較したい場合だけです。そうでなければ省略します。
4. 編集を実行し、音を有効にした状態で結果の顎、首、髪、襟を確認します。

解析結果は24時間再利用できます。同じプレビューから別の参照セットを試せます。追跡にもう一度支払う必要はありません。受理された編集は、新しい参照セットや新しいシードであっても、新しい課金対象のタスクです。どのプレビューにも対象の人物が写っていない場合は、よりクリアなカットを撮り直してください。一度も鮮明に写らない頭部は追跡できず、追跡できる頭部のないクリップは失敗し、確保された金額は解放されます。

解析ページはステップ1だけを単独で実行します。解析が成功した時点で請求されるので、そこで止めた場合でも料金がかかります。

コードから実行する

Python SDK（pip install spicyapi）をインストールし、環境で SPICY_API_KEY を設定して、これを swap.py として保存します。analyze はプレビューのURLを出力し、edit は解析のタスクIDと、選んだプレビューの位置を受け取ります。編集は解析と同じAPIキーと同じ解像度を使う必要があり、video_url は渡しません。解析済みのクリップを引き継ぎます。

import sys
import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

def run(model: str, input_data: dict) -> tuple[str, list]:
    task = client.create_task(model=model, input_data=input_data,
                              idempotency_key=str(uuid.uuid4()))
    final = client.wait_for_terminal(task["taskId"])
    if final["state"] != "succeeded":
        raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
    return task["taskId"], output_assets(final)

if sys.argv[1] == "analyze":
    task_id, previews = run("spicyapi/head-swap-video-v1/video-analyze", {
        "video_url": "https://your-media.example/conversation.mp4",
        "resolution": "720p",
    })
    print("analysis task:", task_id)
    for position, asset in enumerate(previews):   # position 0 is the first image returned
        print(position, asset["url"])
else:  # python swap.py edit <analysis_task_id> <position>
    _, outputs = run("spicyapi/head-swap-video-v1/video-edit", {
        "analysis_task_id": sys.argv[2],
        "resolution": "720p",
        "swap_targets": [{
            "object_index": int(sys.argv[3]),
            "image_urls": [
                "https://your-media.example/replacement-front.png",
                "https://your-media.example/replacement-three-quarter.png",
            ],
        }],
        "seed": 42,
    })
    print(outputs[0]["url"])  # copy the video to your own storage now

python swap.py analyze を実行し、すべてのプレビューを開いて、欲しい成人の番号を書き留めます。位置0は最初に返ってきた画像であり、左から右という規則ではありません。対象が見つからないときに0へ戻してはいけません。次に python swap.py edit <analysis_task_id> 1 を実行します。編集は1〜10の対象を受け取り、各対象につき同じ人物の参照画像を1〜3枚使います。マスク、服装、音声、プロンプトの入力はありません。作成、待機、リトライ、冪等性キー、ダウンロードについてはタスクガイドとPython SDKリファレンスを参照してください。ローカルファイルは無料アップロード手順を通り、video_url に使う spicy:// URI として返ります。

Agent に実行させる

アシスタントに2つの呼び出しを実行させる場合、3つの公式ツールはいずれも価格を表示し、有料呼び出しの前に確認を求めます。

• CLI. 解析の input オブジェクト（video_url、resolution）を analysis.json に置いてから、次を実行します。

``bash spicyapi tasks create --model spicyapi/head-swap-video-v1/video-analyze --input-file analysis.json --wait ``

編集も同じ手順で edit.json を使って実行します。CLI ドキュメントも確認してください。npx @spicyapi/cli はインストールなしでも動きます。

• MCP サーバー。 MCP サーバーを追加して、次のように依頼します。"Analyse conversation.mp4 with Video Head Swap at 720p and show me the numbered previews." ファイルは spicyapi_upload_file でアップロードされ、spicyapi_task_create（価格確認のためここで停止します）を呼び、その後 spicyapi_task_wait を呼びます。位置は自分で選び、そのあと編集を依頼します。
• Skill. npx skills add spicyapi-ai/spicy-skill は Agent Skillをインストールし、コーディングアシスタントが項目名を推測せずに最新のモデルスキーマを読むようにします。

完成した編集の様子

下記の公開モデル例は、10秒のソースクリップと、1枚の参照ポートレートを使った480pの編集です。髪と顔は変わり、ドレス、歩き方、逆光、カメラはそのままです。まず顎と首のラインを確認してください。光の向きやアングルの不整合はそこに出ます。

費用

編集は480pで請求秒あたり$0.064、720pで$0.12です。課金は5秒単位のブロックで行われ、5秒が最低、30秒が上限です。480pの10秒クリップは合計$0.72、解析$0.08に編集$0.64を加えた金額です。

精算前の編集は30秒ぶん、つまり480pで$1.92、720pで$3.60を予約します。720pの12秒クリップは、編集料金が$1.80でも$3.60が確保されます。残額はタスクの精算時に解放されます。

選択、同一性、配信を分けて診断する

髪、襟、手前の手を確認する イラスト。

返ってきた映像は音声つきで再生してください。編集はソースの音声と体の動きを保ち、話者の声は変えず、背景がピクセル単位で完全に一致する保証もありません。選択しなかった人物も確認してください。差し替えた顔に手が重なった場面はとくに注意が必要です。手が横切るなら、最初の見栄えの良い1コマだけを承認するのではなく、接触と再出現の瞬間をコマ送りで確認してください。

承認した映像はすぐに自分のストレージへ保存してください。結果リンクは20分ほどしか保持されず、結果は最大14日しか保存されないため、解析ID、プレビュー画像、一時的なメディアURLは永続的なコピーを意味しません。