ヘッドスワップ – 生成
namifusion/head-swap/generate
namifusion/head-swap/generate. 画像・動画・顔交換のモデル API を閲覧。試してから統一 REST API で統合。
サンプル
パラメータ
| 名前 | 型 | 既定 | 制約 | 説明 |
|---|---|---|---|---|
| track_manifest_url *トラックマニフェスト URL | text | — | — | 対応する analyze リクエストで返された track_manifest_url です。別の動画のマニフェストは使用しないでください。 |
| mappings *置換マッピング | array<object> | — | — | 分析結果の obj_id と 1 枚以上の参照画像 URL を関連付けるマッピングオブジェクトです。 |
| ↳obj_id *オブジェクト ID | number | — | — | 対応する analyze リクエストで返されたオブジェクト識別子です。 |
| ↳img_urls *参照画像 | image_upload | — | 1–3 items | この検出オブジェクトに関連付ける参照画像 URL です。 |
| resolution解像度 | select | 720p | 480p | 720p | 出力解像度またはプロバイダーの生成モードを選択します。高い設定ほど処理時間が長くなる場合があります。 |
| seedシード値 | number | — | — | 結果を再現するための任意の乱数シードです。空欄の場合はランダム値を使用します。 |
出力フィールド
| フィールド | 型 | 説明 |
|---|---|---|
| videos | array |
API
統一 REST API でこのモデルを呼び出せます。API Keys ページでキーを取得してください。
cURL
# 1) Submit — returns { "task_uuid": "..." }
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/head-swap/generate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"track_manifest_url": "ANALYZE_OUTPUT.track_manifest_url",
"mappings": [
{
"obj_id": 0,
"img_urls": [
"https://assets-public.namifusion.com/marketplace/images/2026-06-12/638e1ee18ac7.jpeg"
]
}
],
"resolution": "720p"
}
}'
# 2) Poll until status is "completed", then read the output URLs
curl "https://www.namifusion.com/api/v1/marketplace/run/tasks/TASK_UUID" \
-H "Authorization: Bearer YOUR_API_KEY"Python
import time, requests
API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# 1) Submit
resp = requests.post(
"https://www.namifusion.com/api/v1/marketplace/run/namifusion/head-swap/generate",
headers=HEADERS,
json={
"input": {
"track_manifest_url": "ANALYZE_OUTPUT.track_manifest_url",
"mappings": [
{
"obj_id": 0,
"img_urls": [
"https://assets-public.namifusion.com/marketplace/images/2026-06-12/638e1ee18ac7.jpeg"
]
}
],
"resolution": "720p"
}
},
)
resp.raise_for_status() # 401/402/429/5xx stop here instead of polling a bad task
task = resp.json()
# 2) Poll until a terminal state (completed / failed / cancelled).
# This model is allowed up to 7200s server-side.
deadline = time.time() + 7260
while task.get("status") not in ("completed", "failed", "cancelled"):
if time.time() > deadline:
raise TimeoutError(f"still {task.get('status')} — keep the task_uuid and poll later")
time.sleep(3)
poll = requests.get(f"https://www.namifusion.com/api/v1/marketplace/run/tasks/{task['task_uuid']}", headers=HEADERS)
poll.raise_for_status()
task = poll.json()
print(task["status"], task.get("output"))JavaScript
const API_KEY = "YOUR_API_KEY";
const HEADERS = { Authorization: `Bearer ${API_KEY}` };
// 1) Submit
const resp = await fetch("https://www.namifusion.com/api/v1/marketplace/run/namifusion/head-swap/generate", {
method: "POST",
headers: { ...HEADERS, "Content-Type": "application/json" },
body: JSON.stringify({
"input": {
"track_manifest_url": "ANALYZE_OUTPUT.track_manifest_url",
"mappings": [
{
"obj_id": 0,
"img_urls": [
"https://assets-public.namifusion.com/marketplace/images/2026-06-12/638e1ee18ac7.jpeg"
]
}
],
"resolution": "720p"
}
}),
});
if (!resp.ok) throw new Error(`submit failed: ${resp.status} ${await resp.text()}`);
let task = await resp.json();
// 2) Poll until a terminal state (completed / failed / cancelled).
// This model is allowed up to 7200s server-side.
const deadline = Date.now() + 7260 * 1000;
while (!["completed", "failed", "cancelled"].includes(task.status)) {
if (Date.now() > deadline) throw new Error(`still ${task.status} — keep the task_uuid and poll later`);
await new Promise((r) => setTimeout(r, 3000));
const poll = await fetch(`https://www.namifusion.com/api/v1/marketplace/run/tasks/${task.task_uuid}`, { headers: HEADERS });
if (!poll.ok) throw new Error(`poll failed: ${poll.status}`);
task = await poll.json();
}
console.log(task.status, task.output);ドキュメント
Head Swap - Generate
分析済み動画で選択した頭部を参照画像へ置き換え、元の音声を保持して出力します。
Head Swap Generate は、Head Swap Analyze が返した追跡結果を使う第 2 段階のモデルです。mappings の各項目で obj_id と 1~3 枚の参照画像 URL を関連付け、置換する頭部を明示します。video_url と track_manifest_url は同じ Analyze タスクに由来する必要があり、解像度も分析時と一致させます。
主な特長
- 頭部単位の明示的な選択:分析結果の
obj_idを指定し、対象を取り違えにくいワークフローです。 - 複数対象のマッピング:複数の頭部へそれぞれ異なる参照画像を割り当てられます。
- 複数参照画像:1 対象あたり 1~3 枚を指定し、外観や角度の情報を補えます。
- 元の音声を保持:完成動画では入力動画の音声トラックを維持します。
- 480p / 720p 出力:必要な品質と既存の料金区分に合わせて選択できます。
技術仕様
| 項目 | 内容 |
|---|---|
| ワークフロー | Head Swap のステップ 2 |
| 必須入力 | video_url、track_manifest_url、mappings |
mappings | {obj_id, img_urls} の配列 |
| 参照画像 | 1 対象あたり 1~3 URL |
| 解像度 | 480p、720p(デフォルト) |
| 動画の上限 | 30 秒 |
| 任意入力 | seed |
| 出力 | 元の音声を保持した動画 URL |
基本フロー
- Head Swap Analyze で入力動画を処理します。
objectsのプレビューから対象のobj_idを選びます。- 各 ID と対応する頭部参照画像を
mappingsに設定します。 - 同じ動画と Analyze が返したマニフェストを送信し、完了までポーリングします。
価格
既存文書の価格は 480p が 5 秒単位で 40 クレジット、720p が 5 秒単位で 75 クレジットです。動画は最大 30 秒です。この日本語文書の追加では価格設定を変更しません。
活用のポイント
鮮明で頭部全体が見える参照画像を使い、可能であれば対象動画に近いカメラ角度と照明を選んでください。複数画像を使う場合は、同じ人物で一貫した外観の素材を指定します。動画、マニフェスト、obj_id は同じ Analyze 結果から取得し、異なるタスクの値を混在させないでください。
関連モデル
ヘッドスワップ – 解析
namifusion/head-swap/analyze. 画像・動画・顔交換のモデル API を閲覧。試してから統一 REST API で統合。
キャラクター置換 – 生成
namifusion/character-swap/generate. 画像・動画・顔交換のモデル API を閲覧。試してから統一 REST API で統合。
キャラクター置換 – 解析
namifusion/character-swap/analyze. 画像・動画・顔交換のモデル API を閲覧。試してから統一 REST API で統合。