キャラクター置き換え（リキャスト、recast とも呼ばれます）は、動画を別の人物で撮り直します。動画をアップロードすると、API がショットとそこに映る全員を見つけます。あとは誰を誰にするかを指定するだけです。保存済みのキャラクター、画像、またはそのまま。置き換える人物が映るショットはすべて、元の人物とまったく同じ動きのまま、あなたのキャラクターで描き直されます。それ以外のショットには一切手を加えません。動き、構図、カメラワーク、カット、サウンドトラックはすべてそのままです。シーンの撮り直し、流行りのダンスを踊るマスコット、実写の製品デモのバーチャルプレゼンター、自分のキャストでのプリビズなどに使えます。API 呼び出しひとつで、またはコードなしで Playground から。
AI エージェントに任せる
このプロンプトを Claude Code、Cursor、Codex などのコーディングエージェントに貼り付けてください。ドキュメントの場所と API キーの使い方をエージェントに伝えます。
Replace people in a video with my own character using the Lovely Router video replacement API: it finds the shots and everyone in them for free, re-renders only the shots with a swapped person, and joins them back over the original sound.
- Docs (read first): https://lovelyrouter.com/docs/api/video-replacements.md and https://lovelyrouter.com/docs/api/characters.md
- Upload: POST https://lovelyrouter.com/v1/videos/replacements (multipart) with `video` (MP4/MOV/WebM up to 95 MB, or a URL), `model=minimax-h3-character-swap`, optional `start`/`end` (seconds, up to 3 minutes) and `consent=true` (confirms everyone shown is 18+ and agreed, and accepts the model's terms; read the licence linked in the docs first and tell me if my use might not be allowed).
- Poll GET https://lovelyrouter.com/v1/videos/replacements/<id>?wait=60 until `ready`, then show me the `cast` (face_url / body_url per person) and ask who becomes who before rendering.
- Render: POST https://lovelyrouter.com/v1/videos/replacements/<id>/render with `cast` (cast id → {"character_id"} or {"image"} or "keep"), `mode` (`person` or `face`) and optionally `background: "new"` with a `scene`. Billed per second swapped; the most it can cost is reserved when it starts.
- Poll until `succeeded`, then download GET https://lovelyrouter.com/v1/videos/replacements/<id>/content (kept 7 days). If a piece missed someone, POST .../pieces/<n>/retry with a short `search` description.
- For a recurring character, save it once with POST https://lovelyrouter.com/v1/characters and use its `character_id`.
- Auth: read my API key from the LOVELY_API_KEY environment variable and send it as `Authorization: Bearer $LOVELY_API_KEY`. Never print or commit the key. If it is not set, ask me to create one at https://lovelyrouter.com/app/keys.
- Billing is prepaid: every call is charged to my balance, so test with a small request before running anything large.
- Every docs page is plain Markdown; the full index is https://lovelyrouter.com/llms.txt.
My task: <the video, who in it should be replaced, and a picture or saved character for each>仕組み
動画をアップロード
MP4・MOV・WebM ファイル（最大 95 MB）を
POST /v1/videos/replacementsに送ります。必要な部分だけ（最大 3 分）でも構いません。動画はショットに分割され、映っている人はキャスト（p1、p2…）にまとめられます。各キャストには顔画像、上半身画像、登場するショットが付きます。この分析は無料です。誰を誰にするか指定
各キャストにキャラクターを割り当てます。保存済みキャラクターの
character_id、画像、またはkeep。personは人物全体（顔・髪・体・服）を、faceは頭部だけを置き換え、服はそのまま残します。元の背景を残すことも、background: "new"にして各ショットの新しいsceneを記述することもできます。ショットごとに描き直し、残りはそのまま
置き換える人物が映るショットは、キャラクターの画像から、元の動きとカメラワークに沿って描き直されます。最初にビジョンモデルが各キャラクターの見た目を記録するので、どのショットでも髪型・メガネ・服が揃います。さらに各ショットで誰が話しているかを確認するので、話していない置き換え対象が他人のセリフに口を合わせることはありません。置き換える人物がいないショットは元のままです。
1 本の動画、音声はそのまま
ショットは元の順番で、元の音声の上につなげられます。置き換えた部分は完成した順に再生でき、誰かを見逃した部分は再試行できます。完成した mp4 は 7 日間ダウンロードできます。
2 回のリクエストで置き換え
# 1. アップロード：ショットとキャストを無料で検出
curl https://lovelyrouter.com/v1/videos/replacements \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-F model=minimax-h3-character-swap \
-F video=@party.mp4 -F start=12 -F end=72 \
-F consent=true
# 2. レンダリング：p1 を保存済みキャラクターに、p2 はそのまま
curl https://lovelyrouter.com/v1/videos/replacements/RPL_ID/render \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "content-type: application/json" \
-d '{"cast": {"p1": {"character_id": "chr_3b9e1f0c7a2d4e58b6c1a9f2"}, "p2": "keep"}, "mode": "person"}'アップロードはすぐに 202 を返します。GET /v1/videos/replacements/{id}?wait=60 を ready になるまでポーリングし、shots と cast を確認します。レンダリングを呼び出したら、succeeded になるまで再度ポーリングし、GET /v1/videos/replacements/{id}/content でダウンロードします。同じ流れの Python 版は動画置き換え API リファレンスにあります。
使うツール
POST /v1/videos/replacements は、カットや複数のショット、最大 8 人が映る動画を扱い、必要なショットだけを置き換えます。リファレンス：動画置き換えエンドポイント。
最長 10 秒の連続したクリップなら、POST /v1/videos に video と input_reference を渡すだけで、新しいキャラクターになった同じクリップが 1 回の呼び出しで返ります。キャラクター置き換えを参照。
POST /v1/characters でキャラクター（名前、説明、三面図）を一度保存すれば、すべての動画でその character_id を使えます。マスコットやプレゼンターの見た目がどこでも揃います。保存は無料。キャラクターを参照。
POST …/{id}/outfit は動画のフレームからある人物の服を切り抜きます。レンダリング前に、その服を着たキャラクターを描くのに使えます。無料。
誰かを見逃した部分は、POST …/{id}/pieces/{n}/retry でその部分だけを描き直せます。短い説明（"man in a black suit"）か、画面上のタップで人物を指定します。誰かを置き換えた場合にだけ課金されます。
後ろ姿だけの人や小さく映る人は、added で位置を指定して追加し、他の人と同じように割り当てられます。低解像度の preview 動画で見つけられます。
料金
| 内容 | 料金 | 補足 |
|---|---|---|
| 動画全体の置き換え | 置き換え 1 秒あたり $0.2 | 実際に人物を置き換えた秒数のみ。置き換えた部分は 1 つあたり最低 5 秒として計算。ショットとキャストの検出は無料で、変更のないショットも無料です。 |
| 単一クリップの置き換え | 返される動画 1 秒あたり $0.1 | 1 クリップ、最長 10 秒。 |
60 秒の動画で、あなたのキャラクターが 25 秒映る場合、料金は約 $5 です。レンダリング開始時に最大額がプリペイド残高から確保され、終了時に残りが戻ります。割り当てた人物が見つからなかったショットは課金されません。各キャラクターの見た目の記録と各ショットの話者確認は、小さなチャット呼び出しとしてあなたのキーで課金されます。すべての料金は料金ページにあります。
活用例
編集済みの映像をアップロードし、主役を出演者の保存済みキャラクターに mode: "person" で割り当て、他の人はそのままに。主役が映るショットだけが撮り直され、残りは一切変わりません。
ダンスやミームのクリップで、踊っている人をマスコットのキャラクターに割り当て、background: "new" とブランドカラーの scene を指定します。
実写の製品デモを一度撮影し、mode: "face" で各市場のプレゼンターに頭部だけを置き換えます。手・服・製品は撮影したままです。
無料の分析後に cast の画像をユーザーに見せ、誰を誰にするか選んでもらってからレンダリングします。分析済みの動画を破棄しても費用はかかりません。
このページのプロンプトを Claude Code や Cursor に渡せば、Markdown のドキュメントを読み、あなたのキーで API を呼び出します。
同意と責任ある利用
置き換えるのは権利がある場合だけにしてください。自分の映像、同意を得た出演者やクリエイター、または自分が権利を持つキャラクターです。すべてのアップロードで consent: true を指定し、映っている全員が 18 歳以上で肖像の利用に同意していることを確認するとともに、MiniMax H3 の利用規約に同意します。この規約では EU、英国、韓国、米国での利用は認められていません。実在の人物へのなりすまし、欺瞞的または同意のないコンテンツ、未成年者が関わるものは利用規定で禁止されています。不正利用は誰でも報告ページから報告でき、すべての報告が確認されます。完成した動画は 7 日間保存された後、削除されます。
よくある質問
リキャスト（recast）とは？+
リキャストとは、すでに撮影された役を別の人物に置き換えることです。同じシーン、同じ動き、同じタイミングのまま、顔と体だけが新しくなります。ここでは API 呼び出しひとつ：動画の誰をどのキャラクターにするか指定すれば、その人物が映るショットだけが描き直されます。
顔交換アプリとの違いは？+
顔交換は、フレームごとに顔を別の顔に貼り付けます。キャラクター置き換えは、あなたのキャラクターでショットを描き直します。人物全体でも頭部だけでもよく、髪・体・服・光の当たり方まで合います。カットや複数の人が含まれる動画全体を扱え、関係のないショットはそのまま残ります。
音声やタイミングは保たれますか？+
はい。ショットは元の長さで描き直され、元のサウンドトラックの上に順番につなげられるので、カット、音楽、セリフはすべて同期したままです。
複数の人を置き換えられますか？+
はい。1 回のレンダリングで最大 8 人のキャストをそれぞれ別のキャラクターに割り当てられ、誰でもそのまま残せます。
どのくらい時間がかかりますか？+
無料の分析は通常 1〜2 分です。その後、置き換えるショットは 5 秒あたり約 1 分で、ショットは順番にレンダリングされます。置き換える人物がほとんどのショットに映る 30 秒の動画なら、約 6〜10 分で完成します。GPU が起動していない場合は約 1 分追加されます。
どんなキャラクター画像がよいですか？+
1 人だけが映り、顔がはっきり見え、均一に照らされ、背景が無地の画像です。保存済みキャラクターの三面図（正面・横・後ろ）を使うと、どの角度でも最も安定して似せられます。
ショットが変わらずに返ってきたら？+
人物は顔で照合されるため、ショット中ずっと後ろ姿の人は見つからないことがあります。その部分は元のまま返され、課金されません。説明文か画面上のタップで再試行してください。
API の全体は動画置き換えリファレンスを、同じキャラクターでミュージックビデオを作るならミュージックビデオをご覧ください。