namifusion 视频换脸

NamiFusion Video FaceSwap

AI 视频换脸：支持单人自动换脸与多人精确映射，搭配人脸检测实现完整视频换脸工作流。

NamiFusion Video FaceSwap 是一个高质量 AI 视频换脸服务，支持将源人脸替换到目标视频中。它提供单人换脸（自动模式）和多人换脸（精确映射模式）两种用法，并可搭配 NamiFusion Detect Faces 实现从人脸检测到换脸的完整工作流。

---

核心特性

• 单人换脸： 开启 single_face_mode 即可自动完成换脸，无需任何额外配置。
• 多人精确映射： 通过 face_mapping 精确指定源人脸与目标人脸的对应关系，支持一对一、多对多映射。
• 面部优化： 可选的高级美颜功能，自动磨皮并消除脸部瑕疵，提升换脸后的面部质量。
• 异步任务： 提交后返回 task_uuid，通过轮询或 Webhook 获取结果。

---

技术规格

参数	详情
模型 ID	namifusion/faceswap-video
请求方式	异步 POST（提交任务 + 轮询/Webhook 获取结果）
输入	源人脸图片 URL + 目标视频 URL
输出	换脸后的视频 URL
处理时间	通常 30 秒 ~ 数分钟（取决于视频时长与分辨率）

---

快速开始

API 端点

端点	方法	说明
/api/v1/marketplace/run/namifusion/faceswap-video	POST	提交视频换脸任务
/api/v1/marketplace/run/tasks/{task_uuid}	GET	查询任务状态与结果

认证

在请求 Header 中携带您的 API Key：

X-API-Key: sk-your-api-key

---

场景一：单人换脸（最简用法）

适用于源图片和目标视频中都只有一张人脸的场景。开启 single_face_mode 后无需配置 face_mapping，服务会自动完成换脸。

第 1 步：提交换脸任务

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-video" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_url": "https://example.com/source_face.jpg",
      "target_url": "https://example.com/target_video.mp4",
      "single_face_mode": true
    }
  }'

响应示例：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "cost_credits": 50
}

第 2 步：轮询任务状态

curl -X GET "https://www.namifusion.com/api/v1/marketplace/run/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: sk-your-api-key"

处理中：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

完成：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_id": "namifusion/faceswap-video",
  "status": "completed",
  "output": {
    "videos": ["https://cdn.namifusion.com/result/faceswap_abc123.mp4"]
  },
  "cost_credits": 50,
  "created_at": "2026-02-27T10:00:00Z",
  "completed_at": "2026-02-27T10:01:30Z"
}

---

场景二：多人换脸

当目标视频中有多个人脸，且需要精确控制"用哪张源脸替换哪张目标脸"时，需要先调用 Detect Faces 对视频进行人脸检测，再构建 face_mapping 提交换脸任务。

第 1 步：检测目标视频中的人脸

调用 NamiFusion Detect Faces（POST /api/v1/marketplace/run/namifusion/detect_faces）直接对视频进行人脸检测，然后轮询获取结果。

提交检测任务：

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/detect_faces" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "url": "https://example.com/target_video.mp4",
      "num_frames": 3,
      "return_face_url": true,
      "deduplicate": true
    }
  }'

轮询任务结果：

curl -X GET "https://www.namifusion.com/api/v1/marketplace/run/tasks/{task_uuid}" \
  -H "X-API-Key: sk-your-api-key"

完成响应（假设检测到 2 个人物）：

{
  "task_uuid": "...",
  "status": "completed",
  "output": {
    "error_code": 0,
    "error_msg": "SUCCESS",
    "faces_obj": {
      "0": {
        "region": [[50, 80, 150, 200], [250, 70, 350, 190]],
        "face_urls": [
          "https://s3.amazonaws.com/faces/target_face_0.jpg",
          "https://s3.amazonaws.com/faces/target_face_1.jpg"
        ],
        "landmarks": [[[...]], [[...]]],
        "frame_time": null,
        "crop_region": [[...], [...]],
        "landmarks_str": ["...", "..."],
        "crop_landmarks": ["...", "..."]
      },
      "1": {
        "region": [],
        "face_urls": [],
        "landmarks": [],
        "frame_time": 1.0,
        "crop_region": [],
        "landmarks_str": [],
        "crop_landmarks": []
      },
      "2": {
        "region": [],
        "face_urls": [],
        "landmarks": [],
        "frame_time": 2.0,
        "crop_region": [],
        "landmarks_str": [],
        "crop_landmarks": []
      }
    }
  }
}

此时你已知道目标视频中有 2 个人物（faces_obj["0"].region 长度为 2），以及他们的 face_urls。

第 2 步：检测源人脸图片

同样调用 Detect Faces 提交检测任务并轮询结果（如果你有多张源脸图片，或需要精确传递人脸坐标信息）。

提交检测任务：

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/detect_faces" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "url": "https://example.com/source_face.jpg",
      "return_face_url": true
    }
  }'

完成响应：

{
  "task_uuid": "...",
  "status": "completed",
  "output": {
    "error_code": 0,
    "error_msg": "SUCCESS",
    "faces_obj": {
      "0": {
        "region": [[100, 50, 200, 180]],
        "face_urls": ["https://s3.amazonaws.com/faces/source_face_0.jpg"],
        "landmarks": [[[...]]],
        "frame_time": null,
        "crop_region": [[...]],
        "landmarks_str": ["..."],
        "crop_landmarks": ["..."]
      }
    }
  }
}

第 3 步：构建 face_mapping

根据检测结果，构建源人脸到目标人脸的映射关系。

将 Detect Faces 返回的 face_urls 中对应的 URL 分别作为 source_face_info.face_url 和 target_face_info.face_url 填入 face_mapping：

"face_mapping": [
  {
    "source_face_info": {
      "face_url": "https://s3.amazonaws.com/faces/source_face_0.jpg"
    },
    "target_face_info": {
      "face_url": "https://s3.amazonaws.com/faces/target_face_0.jpg"
    }
  }
]

其中 face_url 直接使用第 1、2 步中 Detect Faces 返回的 output.faces_obj["0"].face_urls[i] 值即可。

face_mapping 中还支持 source_face_index、target_face_index、bbox 等参数，详见后文「face_mapping 详解」章节。

第 4 步：提交多人换脸任务

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-video" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_url": "https://example.com/source_face.jpg",
      "target_url": "https://example.com/target_video.mp4",
      "single_face_mode": false,
      "face_mapping": [
        {
          "source_face_info": {
            "face_url": "https://s3.amazonaws.com/faces/source_face_0.jpg"
          },
          "target_face_info": {
            "face_url": "https://s3.amazonaws.com/faces/target_face_0.jpg"
          }
        }
      ]
    }
  }'

响应：

{
  "task_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "pending",
  "cost_credits": 50
}

第 5 步：获取换脸结果

轮询任务状态直到 status 变为 completed：

curl -X GET "https://www.namifusion.com/api/v1/marketplace/run/tasks/b2c3d4e5-f6a7-8901-bcde-f12345678901" \
  -H "X-API-Key: sk-your-api-key"

完成响应：

{
  "task_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "model_id": "namifusion/faceswap-video",
  "status": "completed",
  "output": {
    "videos": ["https://cdn.namifusion.com/result/faceswap_def456.mp4"]
  },
  "cost_credits": 50,
  "created_at": "2026-02-27T10:05:00Z",
  "completed_at": "2026-02-27T10:07:30Z"
}

---

Python 完整示例：多人视频换脸工作流

以下示例演示了从人脸检测到多人视频换脸的完整流程：

import requests
import time

API_KEY = "sk-your-api-key"
BASE_URL = "https://www.namifusion.com/api/v1/marketplace/run"
HEADERS = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
}

source_url = "https://example.com/source_face.jpg"
target_url = "https://example.com/target_video.mp4"


def detect_faces(media_url, num_frames=None):
    """Submit face detection task and poll for result."""
    input_params = {"url": media_url, "return_face_url": True}
    if num_frames:
        input_params["num_frames"] = num_frames
    task = requests.post(
        f"{BASE_URL}/namifusion/detect_faces",
        headers=HEADERS,
        json={"input": input_params},
    ).json()

    while True:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task['task_uuid']}",
            headers=HEADERS,
        ).json()

        if resp["status"] == "completed":
            return resp["output"]
        elif resp["status"] == "failed":
            raise Exception(resp.get("error_message", "Unknown error"))

        time.sleep(3)


# Step 1: detect faces in target video
target_detect = detect_faces(target_url, num_frames=3)
target_frame = target_detect["faces_obj"]["0"]

print(f"Target has {len(target_frame['face_urls'])} faces")
for i, face_url in enumerate(target_frame["face_urls"]):
    print(f"  Face {i}: region={target_frame['region'][i]}")

# Step 2: detect faces in source image
source_detect = detect_faces(source_url)
source_frame = source_detect["faces_obj"]["0"]

# Step 3: build face_mapping (replace target face 0 with source face 0)
face_mapping = [
    {
        "source_face_info": {"face_url": source_frame["face_urls"][0]},
        "target_face_info": {"face_url": target_frame["face_urls"][0]},
    }
]

# Step 4: submit video faceswap task
task_resp = requests.post(
    f"{BASE_URL}/namifusion/faceswap-video",
    headers=HEADERS,
    json={
        "input": {
            "source_url": source_url,
            "target_url": target_url,
            "single_face_mode": False,
            "face_mapping": face_mapping,
        }
    },
).json()

task_uuid = task_resp["task_uuid"]
print(f"Task submitted: {task_uuid}")

# Step 5: poll for result
while True:
    status_resp = requests.get(
        f"{BASE_URL}/tasks/{task_uuid}",
        headers=HEADERS,
    ).json()

    status = status_resp["status"]
    print(f"Status: {status}")

    if status == "completed":
        result_url = status_resp["output"]["videos"][0]
        print(f"Result: {result_url}")
        break
    elif status == "failed":
        print(f"Failed: {status_resp.get('error_message', 'Unknown error')}")
        break

    time.sleep(10)

---

参数与返回值详解

请求参数

请求体格式为 JSON，所有参数放在 input 对象中：

{
  "input": {
    "source_url": "https://...",
    "target_url": "https://...",
    "single_face_mode": true,
    "face_enhance": false,
    "face_mapping": [],
    "model_style": "realistic"
  }
}

参数	类型	必填	默认值	说明
source_url	string	是	-	源人脸图片 URL（要换上去的脸）。必须可公开访问。
target_url	string	是	-	目标视频 URL（被换脸的视频）。必须可公开访问。
single_face_mode	boolean	否	true	单人脸模式。开启时自动完成换脸，无需配置 face_mapping。
face_enhance	boolean	否	false	是否启用面部优化。开启后自动磨皮并消除脸部瑕疵，面部质量更高，但会增加处理时间。
face_mapping	array	否	null	人脸映射配置。仅在 single_face_mode: false 时生效。详见下方说明。
model_style	string	否	"realistic"	换脸风格。可选值："realistic"（写实）、"beautify"（美颜）、"lossless"（无损）。详见「参数对输出结果的影响」章节。

face_mapping 详解

face_mapping 是一个数组，每个元素定义一组源人脸到目标人脸的映射关系：

字段	类型	必填	说明
source_face_index	integer	是	源图片中人脸的索引（0-based，从左到右排序）。
target_face_index	integer	是	目标视频中人脸的索引（0-based，从左到右排序）。
source_face_info	object	否	源人脸的坐标信息。传入后跳过内部重新检测，保证人脸顺序一致。
target_face_info	object	否	目标人脸的坐标信息。传入后提升匹配精度。

source_face_info 字段

字段	类型	说明
bbox	number[]	人脸边界框 [x1, y1, x2, y2]。
kps	number[][]	人脸 5 个关键点坐标。传入后后端直接使用，跳过重新检测。

target_face_info 字段

字段	类型	说明
bbox	number[]	目标人脸边界框 [x1, y1, x2, y2]。

任务状态

提交任务后通过轮询获取状态，建议轮询间隔 10 秒：

状态	说明
pending	任务已创建，等待处理。
processing	任务正在处理中。
completed	任务已完成，可从 output.videos 获取结果 URL。
failed	任务失败，查看 error_message 了解原因。

返回值结构

提交任务响应

字段	类型	说明
task_uuid	string	任务唯一标识，用于后续查询状态。
status	string	初始状态，通常为 pending。
cost_credits	number	本次任务消耗的积分。

任务完成响应

字段	类型	说明
task_uuid	string	任务唯一标识。
model_id	string	模型 ID（namifusion/faceswap-video）。
status	string	任务状态。
output.videos	string[]	换脸结果视频 URL 列表。
cost_credits	number	消耗积分。
created_at	string	任务创建时间（ISO 8601）。
completed_at	string	任务完成时间（ISO 8601）。
error_message	string	错误信息（仅 failed 时返回）。

---

参数对输出结果的影响

参数	对结果的影响
single_face_mode: true	自动完成换脸，适合单人场景，无需配置 face_mapping。
single_face_mode: false + face_mapping	精确控制替换哪些人脸。未在 mapping 中指定的人脸保持原样不变。
face_enhance: true	开启面部优化，自动磨皮并消除脸部瑕疵，面部更精致自然，但处理时间增加约 20~50%。
face_enhance: false	默认模式，不做额外面部处理，处理速度更快。
model_style: "realistic"	写实风格。呈现接近真实人脸的自然风格，保留生活化的肤色与质感。
model_style: "beautify"	美颜风格。自动磨皮提亮，带来精致柔嫩的观感。
model_style: "lossless"	无损风格。极致无损模式，完美保留原始脸部所有细节，真实度最高且几乎难以辨别。

---

注意事项

1. URL 必须可公开访问：source_url 和 target_url 都必须是可直接下载的公开 URL。
2. 人脸索引排序规则：source_face_index 和 target_face_index 都从 0 开始，按人脸 bbox 左上角的 x 坐标从左到右排序。
3. 强烈建议传递 face_info：如果你已经调用过 Detect Faces，将检测到的 bbox 传入 face_mapping，可以避免换脸服务内部重新检测导致的索引不一致问题。
4. 轮询间隔：建议每 10 秒轮询一次任务状态。视频换脸通常 30 秒 ~ 数分钟完成，取决于视频时长与分辨率。
5. 结果字段名：输出字段名为 output.videos，返回换脸后的视频 URL。