How to Use the Head Swap – Analyze API: character swap integration guide (2026)
Learn how to call the Head Swap – Analyze API on NamiFusion: parameters, pricing (from ≈$0.050) and runnable copy-paste code — try it in the playground first.
Head Swap – Analyze is a character swap model by NamiFusion: Detect and track heads in a video with SAM3. Returns a head list with preview images and a track manifest for the generate step. On NamiFusion you can try it in the playground (exact quote shown before you submit), then call it through one unified REST API — a typical run costs about $0.050.
TL;DR
· Task type: character swap, provided by NamiFusion
· Pricing: about $0.050 per typical run ($1 = 100 credits), pay-as-you-go
· Getting started: playground (exact quote before submit) → create an API key → one POST request
· Tunable parameters: 1 (see the table below)
· No platform watermark; commercial use allowed (per the Terms of Service)
What can you build with Head Swap – Analyze?
Content automation: wire this model into your workflow and call it on demand through one unified API.
How do you call this API?
1. Sign up on NamiFusion and create a key on the API Keys page (signup bonus credits can only be used on selected models).
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.
# 1) Submit — returns { "task_uuid": "..." }
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/head-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"What parameters does it take?
resolution (Resolution): optional, default "720p"
How much does it cost?
Pay-per-use in credits. A typical run costs about $0.050 ($1 = 100 credits); the exact price varies with parameters like resolution or duration, and the playground shows the exact quote before you submit.
Head Swap – Analyze
Head Swap – Analyze
Step 1 of the head swap pipeline. Detects and tracks heads in the input video.
Input
| Field | Type | Required | Notes |
|---|---|---|---|
| video_url | string (video URL) | yes | Up to 30 seconds, 480p/720p processing |
| resolution | "480p" | "720p" | no | Default 720p; must match the generate step |
Output
objects[]: detected heads —obj_id, previewurl,masked_url,coveragetrack_manifest_url: pass this tonamifusion/head-swap/generatevideo_info: width/height/fps/frame_count
Typical flow
- POST /run/namifusion/head-swap/analyze with your video
- Poll GET /run/tasks/{task_uuid} until completed
- Pick the obj_id(s) you want to replace from
objects - Call namifusion/head-swap/generate with
track_manifest_url+mappings
Pricing: 5 credits per call.
FAQ
Can I try it for free first?+
Signup bonus credits can only be used on selected models, and eligibility may change. The playground shows the exact quote before submission.
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 Head Swap – Analyze 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.