はじめに
Video Character Swap Analysis はクリップを読み取り、追跡できた人物ごとにプレビュー静止画を 1 枚ずつ、決まった順序で返します。1 枚目が位置 0、2 枚目が位置 1 と続きます。この位置番号がそのまま入れ替えの呼び出しへの入力です。画像を見て、番号を返してください。
ここでは何も生成されず、クリップにも手は加わりません。この呼び出しは入れ替え側が使う対象リストを作るためのもので、ショットに何人映っていて、どれが誰なのかを知る方法はこれだけです。
主な機能とハイライト
座標ではなく、画像から選びます
この種のエンドポイントの多くは、誰を指しているのかを説明させるか、そうでなければ推測に頼ります。ここでは解析が候補を番号付きの画像として手渡します。誰を入れ替えるのかという曖昧さは、何かが生成される前に解消されます。つまり、間違えてもまだ費用のかからない時点で片が付きます。
1 回の解析で何度でも入れ替えられます
結果は 24 時間そのまま使えます。1 人を当ててみて仕上がりを確かめ、同じ解析のまま別の参照写真を送り直せます。解析の料金は 1 回きりです。24 時間を過ぎると参照は失効し、クリップを解析し直すことになります。
撮影されたままの映像を読みます
追跡はカットの切り替わり、振り向き、部分的な遮蔽をまたいで各人物を追い続けます。5〜30 秒のクリップを受け付け、手前の 1 人だけでなく、ショットの長さのあいだ捉え続けられた人物をすべて報告します。
リクエストパラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
video_url | はい | 解析するクリップです。5〜30 秒。 1 文字以上 |
resolution | いいえ | 追跡解像度です。入れ替え側も同じ値を使う必要があるため、完成クリップに持たせたい解像度を選んでください。 |
料金
$0.08 / 解析
解析と差し替えは別々に課金されます。
ユースケース
料金を払って入れ替える前にクリップを確かめる
入れ替えの呼び出しは解析よりも高くつきます。先に解析しておけば、目当ての人物がこの映像で実際に追跡できるのかが分かります。強いブレ、長い遮蔽、フレームから出ていく被写体は、プレビューが欠けるか不安定になるという形で現れます。
群衆の中から 1 人だけ選ぶ
複数人が映るシーンを解析し、プレビューを読み、意図した位置だけを返します。ほかの人物に入れ替えの手は加わりません。
シリーズ全体で同じキャストを通す
任意の動画モデルでクリップをまとめて生成し、それぞれを解析して、プレビューを頼りに全ショットで同じ対象をそろえます。シリーズがひと続きに読めるようになります。
同意を得た演者なら題材は問わない
映像に何が映っていても、リクエストの形は変わりません。下の「制限」にある許諾の条件も変わりません。これはコンテンツの区分ではなく、満たすべき条件です。
プロンプトガイドと実践のヒント
解像度は両方の呼び出しで同じにします
完成クリップに持たせたい解像度を決め、ここでも同じ値を使ってください。入れ替えの呼び出しは同じ値で動かす必要があります。この呼び出しが何を検出するかは変わらず、変わるのは入れ替え側が作業するフレームだけです。
プレビューの順序は読み取るもので、推測するものではありません
静止画は順序を保って返りますが、その順序は追跡の結果であって、画面上の位置や目立ち方ではありません。画面のいちばん左にいる人物が位置 0 とは限りません。画像を見てください。
同じ動画を両方の呼び出しに渡します
入れ替えの呼び出しには同一のクリップ、つまり同じファイル・同じエンコードが必要です。入れ替えのリクエストで video_url を省略すると解析側の値が引き継がれます。両者の一致を保証する方法としては、これがいちばん安全です。
映像が変わったら解析し直します
再エンコード、トリミング、書き出し直しは解析を無効にします。位置番号が同じ人物を指さなくなるためです。実際に入れ替えるファイルそのものを解析してください。
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-analyze",
"input": {
"resolution": "720p",
"video_url": "https://example.com/reference.mp4"
}
}'
# 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 リファレンスを参照してください。