はじめに
Video Character Swap は、解析のタスク ID、そのプレビュー画像から選んだ位置、位置ごとの参照写真 1〜3 枚を受け取り、その人物を入れ替えたクリップを返します。衣装も体格も含めた人物まるごとが変わり、セット・カメラワーク・振り付け・元の音声トラックは撮影時のまま残ります。挙げなかった人物には手が加わりません。
Video Character Swap は 2 回の呼び出しで完結します。1 回目は 5〜30 秒のクリップから人物をすべて追跡し、人物ごとのプレビュー静止画を決まった順序で返します。2 回目では選んだ位置と、それぞれに 1〜3 枚の参照写真を渡すと、その人物だけが入れ替わり、元の音声がそのまま残ったクリップが返ってきます。
主な機能とハイライト
誰を変えるかは利用者が決めます
この種のエンドポイントの多くは、どの人物を指しているのかを推測するしかありません。ここでは 1 回目が検出した人物を番号付きで一覧し、2 回目は返された番号だけに手を加えます。4 人が映るシーンで 1 人だけを入れ替え、残り 3 人は撮影時のまま残せます。
首から下の情報を渡す
Video Character Swap は単独のエンドポイントではなく、2 つで 1 組です。1 回目の video-analyze は 5〜30 秒のクリップ内の人物をすべて追跡し、人物ごとのプレビュー静止画を決まった順序で返します。課金はリクエスト単位の定額で、クリップの長さにも検出数にも左右されません。2 回目の video-edit には、その解析のタスク ID と、選んだ位置、位置ごとの参照写真 1〜3 枚を渡します。返ってくるのは元の音声トラックを保ったクリップ 1 本で、480p または 720p の解像度に応じて秒単位で課金されます。頭部だけを変える head swap と違い、こちらは衣装も体格も含めた人物まるごとを入れ替え、セット・カメラワーク・振り付けは撮影時のまま残します。追跡データそのものが利用者側に出ることはなく、扱うのは自分のタスク ID と 0 始まりの位置番号だけです。
リクエストパラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
analysis_task_id | はい | このクリップを解析した呼び出しのタスク ID です。プレビュー画像は |
swap_targets | はい | 入れ替えたい人物ごとに 1 エントリです。挙げなかった人物には手が加わりません。 1 件以上 · 10 件以内 |
video_url | いいえ | 省略できます。省けば解析側の動画が使われます。 1 文字以上 |
resolution | いいえ | 解析時の解像度と一致している必要があります。料金の段を決めるのもこの項目です。 |
seed | いいえ | 乱数シードです。0 を渡すとランダムになります。 |
料金
元のクリップを 5 秒単位で切り上げて課金します。6 秒のクリップは 10 秒分です。送信前の見積もりは、アップロードしたクリップなら実際の長さ、動画 URL なら上限の 30 秒で計算し、差額があれば精算時に解放されます。
| 仕様 | 料金 |
|---|---|
| $0.064 / 秒 |
| $0.12 / 秒 |
ユースケース
撮り直さずにキャストを変える
セットもカメラワークも振り付けもすでに狙いどおりです。ショット全体を作り直してルック開発をやり直すのではなく、それを演じている人物だけを入れ替えます。
同意を得た演者なら題材は問わない
映像に何が映っていても、リクエストの形は変わりません。同時に、下の「制限」に書かれた許諾の条件も変わりません。形式的な注意書きではなく、満たすべき条件です。
生成したシリーズ全体で同じキャラクター
任意の動画モデルでクリップをまとめて生成し、それぞれを解析したうえで、同じキャラクターを全編に通します。シリーズ全体がひと続きの演者として読めるようになります。
群衆の中で 1 人だけ変える
複数人が映るシーンを解析し、プレビューを見て、意図した位置だけを返します。ほかの人物には一切手が加わりません。
プロンプトガイドと実践のヒント
関係するすべての人物について権利を確認する
映像にも参照写真にも人物が写っています。移す側の肖像と、移し先の映像の双方について許諾が必要です。許諾の記録はジョブの記録と一緒に保管してください。
先に解析し、プレビューの順序を読む
解析はプレビュー静止画を決まった順序で返します。1 枚目が object_index 0、2 枚目が 1 という並びです。必要な手がかりはこの位置番号だけで、そのまま swap_targets に戻します。
首から下の情報を渡す
このエンドポイントは人物をまるごと入れ替えるため、胸から上だけの写真では体格も衣装も推測任せになります。非常に鮮明な接写 1 枚より、角度の違う全身写真 2〜3 枚のほうが役に立ちます。
API クイックスタート
# 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/character-swap-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 リファレンスを参照してください。