How to Use the Head Swap – Analyze API: character swap integration guide (2026)

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

Learn how to call the Head Swap – Analyze API on NamiFusion: parameters, pricing (from ≈$0.100) 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 — about $0.100 per typical run.

TL;DR

· Task type: character swap, provided by NamiFusion

· Pricing: about $0.100 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?

Sign up on NamiFusion and create a key on the API Keys page (signup bonus credits can only be used on selected models).
Submit a task with the cURL example below, passing your key as a Bearer token.
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/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. About $0.100 per typical run ($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

Detect and track heads in a video as the first stage of the Head Swap workflow.

Head Swap Analyze follows visible heads across the input video and creates the obj_id values and track_manifest_url required by the Generate stage. The result also includes previews and video metadata for review. This model does not produce the final swapped video, so keep the original video, resolution, and analysis output together as one workflow unit.

Key Features

Head detection and tracking: Identifies targets and builds tracking data across video frames.
Target selection previews: Returns each head's obj_id, preview, mask, and coverage in objects.
Generate-ready tracking data: Produces a track_manifest_url for Head Swap Generate.
Video metadata: Includes width, height, FPS, and frame count in video_info.
480p and 720p analysis: Tracks targets at the same resolution used for generation.

Technical Specifications

Item	Details
Workflow	Head Swap step 1
Required input	`video_url`
Maximum video length	30 seconds
Resolution	`480p`, `720p` (default)
Main outputs	`objects`, `track_manifest_url`, `video_info`
Next model	`namifusion/head-swap/generate`

Basic Workflow

Send the video URL and selected resolution to namifusion/head-swap/analyze.
Poll the task result endpoint until analysis completes.
Review the previews in objects and select the head obj_id values to replace.
Pass the same video, returned manifest, and selected IDs to Head Swap Generate.

Full parameter reference, output schema & live pricing →

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?+

Pornographic content, sexualized content involving a minor, unauthorized use of real people, deceptive impersonation, fraud and false endorsements are prohibited. Lawful, consensual, non-explicit adult themes may be permitted; 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.

Try it free →