How to Use the FaceDetect API: face swap integration guide (2026)

2 min · Updated 2026-07-11 · By the NamiFusion team

Learn how to call the FaceDetect API on NamiFusion: parameters, pricing and runnable copy-paste code — try it in the playground first.

FaceDetect is a face swap model by NamiFusion: A face detection model used to detect facial information contained in input elements. On NamiFusion you can try it in the playground (exact quote shown before you submit), then call it through one unified REST API.

TL;DR

· Task type: face swap, provided by NamiFusion

· Pricing: pay-as-you-go credits ($1 = 100 credits), no subscription

· Getting started: playground (exact quote before submit) → create an API key → one POST request

· Tunable parameters: 3 (see the table below)

· No platform watermark; commercial use allowed (per the Terms of Service)

What can you build with FaceDetect?

Film and short-drama post-production: replace faces for reshoots or multi-language localization.

Memes and entertainment: put yourself or friends into iconic scenes — built for social sharing.

Virtual personas and privacy: use a substitute face for streams and on-camera content.

Batch production: map multiple source faces onto the same footage to mass-produce personalized versions.

How do you call this API?

1. Sign up on NamiFusion and create a key on the API Keys page (free credits on signup).

2. Submit a task with the cURL example below, passing your key as a Bearer token.

3. Poll the task status with the returned task_uuid and read the output URLs when completed.

Submit a task

# 1) Submit — returns { "task_uuid": "..." }
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/facedetect" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "frame_urls": [
      "https://assets-public.namifusion.com/marketplace/thumbnails/2026-02-25/fb559d5bc3dc.png"
    ],
    "expand_ratio": 0.3
  }
}'

# 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"

What parameters does it take?

frame_urls (Frame URLs): required

timestamps (Timestamps): optional

expand_ratio (Expand Ratio): optional, default 0.3

How much does it cost?

Pay-per-use in credits ($1 = 100 credits). The exact price varies with parameters; the playground shows the quote before you submit.

FaceDetect

Precise face detection and multi-frame tracking: supports single image / multi-frame analysis with automatic person deduplication and cross-frame tracking.

NamiFusion Face Detection is a high-performance face detection service that supports face detection and person tracking across single images or multiple video frames. It automatically identifies all faces in the scene, returns cropped face image URLs, bounding box coordinates, confidence scores, and more. For multi-frame inputs, it automatically performs cross-frame person deduplication and tracking.

Key Features

Unified single image / multi-frame API: Whether it's a single image or multiple video frames, use the same API endpoint for analysis.
Automatic person tracking: For multi-frame inputs, automatically identifies the same person across frames, merging them into a unified person record with a complete appearance timeline.
Face cropping and upload: Automatically crops detected face regions and uploads them to S3, returning ready-to-use image URLs.
Adjustable crop range: Control the face crop expansion ratio via the expand_ratio parameter to suit different use cases.
Async task: Returns a task_uuid upon submission; poll to retrieve results.

Technical Specifications

Parameter	Details
Model ID	`namifusion/facedetect`
Request Method	Async POST (submit task + poll for results)
Input	List of image URLs
Output	List of persons (with face image URL, bounding box, confidence, appearance records)
Processing Time	Typically completes within seconds

Quick Start

API Endpoints

Endpoint	Method	Description
`/api/v1/marketplace/run/namifusion/facedetect`	POST	Submit a face detection task
`/api/v1/marketplace/run/tasks/{task_uuid}`	GET	Query task status and results

Authentication

Include your API Key in the request header:

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

Full parameter reference, output schema & live pricing →

FAQ

Can I try it for free first?+

Signup gives you free credits, but they currently apply only to selected in-app face-swap features — this model is pay-as-you-go. The playground still lets you try it without code, with the exact quote shown before you submit.

Can I use the output commercially? Is there a watermark?+

Yes, outputs are yours to use commercially, and NamiFusion adds no platform watermark — subject to the Terms of Service and applicable law.

What is the content policy?+

NamiFusion is an unfiltered engine: no arbitrary restrictions and NSFW-friendly, but illegal content and non-consensual use of real people are prohibited — see the Terms of Service.

How long does a FaceDetect task take?+

It depends on parameters — images usually take seconds, videos tens of seconds to minutes. The API returns a task_uuid for polling.

What are the resolution and duration limits?+

See the parameter table above — each model lists its available resolution and duration options there and in the playground.

Try it free →