如何使用 人脸检测 API：换脸接入指南（2026）

精准人脸检测与多帧跟踪：支持单图/多帧分析，自动人物去重与跨帧追踪。

NamiFusion Face Detection 是一个高性能人脸检测服务，支持对单张图片或多张视频帧进行人脸检测与人物追踪。它能自动识别画面中的所有人脸，返回裁剪后的人脸图片 URL、边界框坐标、置信度等信息，并在多帧场景下自动完成跨帧人物去重与追踪。

核心特性

• 单图 / 多帧统一接口： 无论是单张图片还是多张视频帧，使用同一个 API 端点即可完成分析。
• 自动人物追踪： 多帧输入时自动识别同一人物，合并为统一的 person 记录，包含完整的出现时间线。
• 人脸裁剪与上传： 自动裁剪检测到的人脸区域并上传至 S3，返回可直接使用的图片 URL。
• 可调节裁剪范围： 通过 expand_ratio 参数控制人脸裁剪的扩展比例，满足不同场景需求。
• 同步响应： 无需轮询或 Webhook，请求即时返回结果。

技术规格

快速开始

1. API 端点

POST /api/v1/marketplace/run/namifusion/face-detection

2. 认证

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

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

3. 最简调用示例

单张图片检测

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/face-detection" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "frame_urls": ["https://example.com/photo.jpg"]
    }
  }'

响应示例

{
  "success": true,
  "frame_count": 1,
  "persons": [
    {
      "person_id": "person_0",
      "index": 0,
      "face_url": "https://s3.amazonaws.com/faces/face_abc123.jpg",
      "bbox": [120, 80, 220, 200],
      "confidence": 0.97,
      "first_seen": 0,
      "last_seen": 0,
      "appearances": [
        {
          "timestamp": 0,
          "frame_idx": 0,
          "bbox": [120, 80, 220, 200]
        }
      ]
    }
  ]
}

4. 多帧检测示例

当传入多张图片（如视频抽帧）时，服务会自动进行跨帧人物追踪与去重。

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/face-detection" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "frame_urls": [
        "https://example.com/frame_0.jpg",
        "https://example.com/frame_1.jpg",
        "https://example.com/frame_2.jpg"
      ],
      "timestamps": [0, 30, 60]
    }
  }'

响应示例

{
  "success": true,
  "frame_count": 3,
  "persons": [
    {
      "person_id": "person_0",
      "index": 0,
      "face_url": "https://s3.amazonaws.com/faces/face_def456.jpg",
      "bbox": [100, 50, 200, 180],
      "confidence": 0.95,
      "first_seen": 0,
      "last_seen": 60,
      "appearances": [
        {"timestamp": 0, "frame_idx": 0, "bbox": [100, 50, 200, 180]},
        {"timestamp": 30, "frame_idx": 1, "bbox": [105, 52, 205, 182]},
        {"timestamp": 60, "frame_idx": 2, "bbox": [108, 55, 208, 185]}
      ]
    },
    {
      "person_id": "person_1",
      "index": 1,
      "face_url": "https://s3.amazonaws.com/faces/face_ghi789.jpg",
      "bbox": [400, 60, 500, 190],
      "confidence": 0.92,
      "first_seen": 0,
      "last_seen": 30,
      "appearances": [
        {"timestamp": 0, "frame_idx": 0, "bbox": [400, 60, 500, 190]},
        {"timestamp": 30, "frame_idx": 1, "bbox": [405, 62, 505, 192]}
      ]
    }
  ]
}

5. Python 调用示例