Cast Swap

Cast Swap API は、短い動画の人物、場所、またはその両方を、あなた自身のリファレンス画像に置き換えます。動画の動き、構図、タイミング、音声はそのまま残ります。実行の見積もりを無料で出し、実行を開始して、ほかのジョブと同じようにそのジョブを追跡します。

Cast Swap は Nodaro Cloud でのみ動作します。セルフホスティング環境では、どちらのルートも 404 を返します。これらのルートは Bearer トークンを受け取ります。認証を参照してください。

エンドポイント

リクエストボディ

どちらのルートも同じボディを受け取ります。

ロールは、動画の中の誰か、または舞台を指し、1 人の人物か 1 か所の場所の画像を 0〜3 枚受け取ります。

• 人物： { kind: "person", name, images, body?, outfit?, hair? }。name は動画の中の誰かを示します。たとえば "the woman dancing"（踊っている女性）です。body、outfit、hair はそれぞれ、デフォルトの "new" ならあなたの画像から取り、"original" なら動画のまま残します。
• 場所： { kind: "location", name?, images }。デフォルトの名前は "the setting"（舞台）です。

画像のないロール（空または null）は、その人物や場所を動画のまま残します。画像のあるロールが少なくとも 1 個、または postPrompt が必要です。

{
  "videoUrl": "https://example.com/clip.mp4",
  "roles": [
    { "kind": "person", "name": "the woman dancing", "images": ["https://example.com/me.jpg"], "outfit": "original" }
  ],
  "preview": true
}

見積もり

POST /v1/cast-swap/estimate は { totalCredits, breakdown: { castSwap, seedance }, settlesLower } を返します。

• totalCredits は、実行そのものである breakdown.castSwap と、呼び出す動画モデルである breakdown.seedance の合計です。
• settlesLower: true は、結果の長さがモデルに任されることを意味します。そのため、最終的な請求は見積もりより低くなる見込みです。

繰り返し

実行を再試行するときは、同じ Idempotency-Key ヘッダー（8〜200 文字）を送ります。約 10 秒以内の繰り返しは、X-Dedup-Hit: 1 ヘッダー付きで 200 { jobId, deduped: true } を返します。それより後の繰り返しは、最初の実行のジョブで 202 { jobId } を返します。どちらの場合も、新しく開始や課金されるものはありません。キーがない場合、リクエストはすべて新しい実行になります。

エラー

拒否はすべて、何かが課金される前に行われます。ボディは { error: { code, message } } です。

SDK から

client.castSwap は両方のルートをラップします。@nodaro/sdk/cast-swap としてインポートすることもできます。

run(params: CastSwapParams, options?: { idempotencyKey?: string }): Promise<{ jobId: string; deduped?: boolean }>
estimate(params: CastSwapParams): Promise<CastSwapEstimate>

CastSwapParams は上記のリクエストボディです。CastSwapEstimate は見積もりです。run() は idempotencyKey をそのまま Idempotency-Key ヘッダーとして送ります。指定しない場合、ヘッダーは送られません。

const params: CastSwapParams = {
  videoUrl,
  roles: [{ kind: "person", name: "the woman dancing", images: [myPhotoUrl], outfit: "original" }],
  preview: true,
}
const quote = await client.castSwap.estimate(params)
const { jobId } = await client.castSwap.run(params, { idempotencyKey: crypto.randomUUID() })

client.jobs.get(jobId) でジョブを追跡します。プレビューのジョブは、すべての入力を input_data に保持します。そのため、preview: false でもう一度実行すれば、同じ選択でクリップ全体をレンダリングできます。

MCP から

MCP ツールは cast_swap です。confirm を指定しない場合は、見積もりを返し、何も課金しません。ユーザーが料金を承認した後に confirm: true で呼び出すと、実行を開始してジョブ ID を返します。