角色替换 – 视频分析

namifusion/character-swap/analyze

用 SAM3 检测并跟踪视频中的所有人物,返回人物清单(含预览图)和供 generate 使用的 track manifest。

参数

名称类型默认约束说明
resolution分辨率select720p480p | 720p选择输出分辨率或供应商生成模式;较高设置可能需要更长处理时间。

输出字段

字段类型说明
objectsarray
video_infoobject
analysis_idstring
detected_objectsnumber
track_manifest_urlstring

API

通过统一 REST API 调用本模型;在 API Keys 页获取密钥。

cURL
# 1) Submit — returns { "task_uuid": "..." }
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/character-swap/analyze" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "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/character-swap/analyze",
    headers=HEADERS,
    json={
        "input": {
            "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 1800s server-side.
deadline = time.time() + 1860
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/character-swap/analyze", {
  method: "POST",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({
    "input": {
      "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 1800s server-side.
const deadline = Date.now() + 1860 * 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);

文档

Character Swap - Analyze

作为角色替换工作流的第一步,检测并持续跟踪视频中的人物。

Character Swap Analyze 会跨帧识别输入视频中的人物,并返回 Generate 阶段需要的 obj_id 与 track_manifest_url。此模型本身不会执行人物替换。请将分析结果、原始视频和所选分辨率作为同一组数据保存,确保后续生成请求使用完全一致的输入条件。

核心特性

  • 人物检测与跟踪:识别视频中的人物,并建立跨帧对应的对象轨迹。
  • 可选择的预览结果:objects 会返回每个人物的 obj_id、预览图、蒙版和覆盖率信息。
  • 生成阶段所需清单:输出 track_manifest_url,可直接传给 Character Swap Generate。
  • 视频元数据:通过 video_info 返回宽度、高度、FPS 和总帧数。
  • 480p / 720p 分析:可选择与生成阶段一致的处理分辨率。

技术规格

项目说明
工作流Character Swap 第 1 步
必填输入video_url
视频上限30 秒
分辨率480p、720p(默认)
主要输出objects、track_manifest_url、video_info
下一步模型namifusion/character-swap/generate

基本流程

  1. 将视频 URL 和所选分辨率提交给 namifusion/character-swap/analyze。
  2. 轮询任务结果接口,直到处理完成。
  3. 查看 objects 中的预览,并选择需要替换人物的 obj_id。
  4. 将同一个 video_url、返回的 track_manifest_url 和所选 ID 传给 Generate 阶段。

价格

现有 Marketplace 定价为每次分析 10 积分。本次文档更新不会修改价格。

使用建议

建议使用不超过 30 秒且人物清晰可见的视频。严重运动模糊、长时间完全遮挡或人物过小都可能降低跟踪质量。Generate 阶段必须使用本次 Analyze 对应的同一视频、分辨率和清单,不要混用其他分析任务的结果。