被写体の入れ替え

新しい場面を生成するのではなく、写っている人物を入れ替えるモデルがあります。ある写真の顔を別の写真へ移す、頭部ごと差し替える、動画クリップの中の人物を丸ごと置き換える、といったものです。カタログではこれらを toolkit: "subject-swap" という一つのラベルでまとめており、形は 2 種類あります。1 回の呼び出しで終わるものと、途中に選択を挟む 2 回呼び出しです。

それ以外に特別なところはありません。ふつうの非同期タスクであり、パラメーターはそれぞれの inputSchema が定め、結果は output.assets[] に入ります。

toolkit でこの種類のモデルを見分ける

toolkit はカタログ項目に付く分類ラベルで、認証付きの GET /api/v1/models の応答にも公開カタログにも含まれます。現在の値は subject-swap の一つだけで、どのツールキットにも属さないモデルではこのフィールド自体が存在しません。キーの有無ではなく、値で判定してください。

これは情報提供のためだけのフィールドです。どのキーがそのモデルを呼べるか、リクエストがどう課金されるか、モデルが何を受け付けるかには影響しません。見覚えのない値が来たときは、見覚えのない badges の項目と同じように無視してください。

curl -s "https://api.spicyapi.ai/api/v1/models?modality=video" \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  | jq -r '.data.items[]
      | select(.toolkit == "subject-swap" and .enabled and .available)
      | [.model, (.tasks | join(",")), .family] | @tsv'

1 行が呼び出せるエンドポイント 1 つです。このページの残りを決めるのは tasks の列です。video-analyze エンドポイントを持つ family は 2 回呼び出しの family であり、対になる video-edit エンドポイントは単独では呼び出せません。

どちらの形か見分ける

どちらも async: true です。タスクを作成し、ポーリングまたは webhook で結果を受け取ります。

1 回呼び出し

ほかの編集モデルと変わるところはありません。エンドポイントの inputSchema を読み、値を埋めて、タスクを作成します。

const created = await fetch('https://api.spicyapi.ai/api/v1/jobs/createTask', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPICY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-8814-swap-1',
  },
  body: JSON.stringify({
    model: swap.model, // 上のカタログ照会で得た項目の一つ
    input: {
      image_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
      reference_image_url: 'spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m',
    },
  }),
});

フィールド名はエンドポイントごとに異なります。prompt や seed、出力形式を受け取るものもあれば、2 枚の画像しか受け取らないものもあります。何を送れるかはスキーマがすべてです。あるエンドポイントのフィールド名を別のエンドポイントへ持ち込まないでください。参照画像には、公開された HTTPS URL、小さな画像ならインラインの Base64、アップロード済みの spicy:// URI が使えます。メディアを参照してください。

2 回呼び出し

1 回目の呼び出しはクリップを見て、何を見つけたかを順序の付いたプレビュー静止画として返します。そのうちどれを入れ替えるかを決めるのはあなたです。実際の作業を行うのは 2 回目の呼び出しです。

あなたのクリップ ──▶ video-analyze ──▶ output.assets[0], [1], [2] …（対象 1 件につき静止画 1 枚）
                                             │
                       位置 0 と 2 を選ぶ ──▶│
                                             ▼
             video-edit（analysis_task_id + swap_targets）──▶ 完成したクリップ

なぜ 1 回で済ませないのか。4 人が写っている場面では、1 回呼び出しのモデルはあなたがどの人物を指しているかを推測するしかなく、推測を外せば、別人が入れ替わった動画が完成し、そのまま課金されます。作業を分ければ、選択は明示的になり、目で確かめられるようになります。

const analysis = await createTask({
  model: analyze.model, // tasks に "video-analyze" を含む項目
  input: {
    video_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
    resolution: '720p',
  },
});
const analysisTaskId = analysis.taskId;

{
  "state": "succeeded",
  "output": {
    "assets": [
      { "url": "https://…", "expiresAt": "2026-09-20T09:32:11Z", "mime": "image/jpeg" },
      { "url": "https://…", "expiresAt": "2026-09-20T09:32:11Z", "mime": "image/jpeg" }
    ]
  },
  "settled": true
}

const swapped = await createTask({
  model: edit.model, // 同じ family の "video-edit" の項目
  input: {
    analysis_task_id: analysisTaskId,
    resolution: '720p', // 解析を実行したときと同じ値
    swap_targets: [
      { object_index: 0, image_urls: ['spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m'] },
    ],
  },
});

2 回目の呼び出しが受け付ける前に確認すること

これらの確認は作成時に行われるため、拒否されたリクエストは何も作らず、何も仮押さえしません。

2 回目の呼び出しが拒否されたとき

いずれも HTTP 400 で、業務コードも code: 400 です。msg は次のいずれかになります。

2 回の呼び出しの料金

解析と入れ替えはそれぞれ別の料金を持つ 2 つのタスクで、仮押さえも精算も別々に行われます。2 回目が拒否されたときは料金がかかりません。解析が成功していれば、そのあと入れ替えをやめても解析分は課金されます。

• 解析はふつう per_request です。クリップの長さにも、見つかった対象の数にもよらず、1 回の呼び出しにつき 1 件の課金です。
• 入れ替えはふつう per_second で、まとまった単位（ブロック）ごとに数えます。長さはあなたが指定するフィールドではなくクリップ自体から決まるため、事前に提示される金額はそのエンドポイントが受け付ける最長のクリップを前提にした金額になります。提示された金額がそのまま仮押さえ額になり、最終的な請求額は切り上げた長さから計算され、仮押さえ額を超えることはありません。差額はタスクの精算時に残高へ戻ります。ここで仮押さえ額が最終請求額より大きく見えるのは、想定どおりの挙動です。予算を組む前に課金を読んでください。

どちらの料金も推測せずカタログから読み、正確な金額が必要なら呼び出しごとに見積もりを取ってください。

次のステップ