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

Head Swap – Generate is a character swap model by NamiFusion: Replace selected heads in the video with your reference images using Wan2.2-Animate. Keeps the original audio track. 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.750.

TL;DR

· Task type: character swap, provided by NamiFusion

· Pricing: about $0.750 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: 4 (see the table below)

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

What can you build with Head Swap – Generate?

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/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "track_manifest_url": "value",
    "mappings": [
      {
        "obj_id": 1,
        "img_urls": [
          "https://example.com/input.jpg"
        ]
      }
    ],
    "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?

track_manifest_url (Track manifest URL): required

mappings (Head mappings): required

resolution (Resolution): optional, default "720p"

seed (Seed): optional

How much does it cost?

Pay-per-use in credits. A typical run costs about $0.750 ($1 = 100 credits); the exact price varies with parameters like resolution or duration, and the playground shows the exact quote before you submit.