换头 – 视频生成
namifusion/head-swap/generate
用 Wan2.2-Animate 将视频中选定头部替换为参考图人物头部,保留原始音轨。
示例
参数
| 名称 | 类型 | 默认 | 约束 | 说明 |
|---|---|---|---|---|
| track_manifest_url *Track manifest URL | text | — | — | analyze 模型返回的 track_manifest_url |
| mappings *头部映射 | array<object> | — | — | {obj_id, img_urls} 数组。obj_id 来自 analyze 输出;每个头部 1-3 张参考图 URL。 |
| ↳obj_id *头部 obj_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 是换头工作流的第二步。mappings 中的每个项目会把 Analyze 返回的 obj_id 与 1 至 3 张参考图片 URL 关联起来,从而明确指定替换目标。video_url 与 track_manifest_url 必须来自同一次 Analyze 任务,生成分辨率也必须与分析阶段保持一致。
核心特性
- 按头部精确选择:使用 Analyze 返回的
obj_id,降低选错替换目标的风险。 - 支持多目标映射:可为同一视频中的多个头部分别分配不同参考图片。
- 支持多张参考图:每个目标可提供 1 至 3 张图片,补充外观和拍摄角度信息。
- 保留原始音频:完成的视频会维持输入视频的原始音轨。
- 480p / 720p 输出:可按目标质量和现有价格档位选择分辨率。
技术规格
| 项目 | 说明 |
|---|---|
| 工作流 | Head Swap 第 2 步 |
| 必填输入 | video_url、track_manifest_url、mappings |
mappings 格式 | {obj_id, img_urls} 对象数组 |
| 参考图片 | 每个目标 1 至 3 个 URL |
| 分辨率 | 480p、720p(默认) |
| 视频上限 | 30 秒 |
| 可选输入 | seed |
| 输出 | 保留原始音频的视频 URL |
基本流程
- 使用 Head Swap Analyze 处理输入视频。
- 从
objects的预览中选择目标obj_id。 - 在
mappings中为每个 ID 配置对应的头部参考图片 URL。 - 提交同一视频和 Analyze 返回的清单,并轮询到生成完成。
价格
现有 Marketplace 定价为 480p 每 5 秒 40 积分、720p 每 5 秒 75 积分,视频最长 30 秒。本次文档更新不会修改价格。
使用建议
使用清晰且头部完整可见的参考图片,并尽量选择与目标视频接近的相机角度和光照。提供多张图片时,应确保人物外观一致。视频、清单和 obj_id 必须来自同一次 Analyze 结果,不要混用不同任务的数据。
相关模型
Character SwapNamiFusion
换头 – 视频分析
用 SAM3 检测并跟踪视频中的头部,返回头部清单(含预览图)和供 generate 使用的 track manifest。
起 $0.100 / 每次
Character Swap
Character SwapNamiFusion
角色替换 – 视频生成
用 Wan2.2-Animate 将视频中选定人物替换为参考图人物,保留原始音轨。
起 $0.750 / 每次
Character Swap
Character SwapNamiFusion
角色替换 – 视频分析
用 SAM3 检测并跟踪视频中的所有人物,返回人物清单(含预览图)和供 generate 使用的 track manifest。
起 $0.100 / 每次