How to Use the Head Swap (Image) API: image to image integration guide (2026)
Learn how to call the Head Swap (Image) API on NamiFusion: parameters, pricing (from ≈$0.220) and runnable copy-paste code — try it in the playground first.
Head Swap (Image) is an image to image model by NamiFusion: Swap the head in a photo with the head from a reference image. Upload the target photo first, then the head reference. 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.220 per typical run.
TL;DR
· Task type: image to image, provided by NamiFusion
· Pricing: about $0.220 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 (Image)?
Social media visuals and covers: batch-generate on-theme images and schedule them straight away.
E-commerce and ad creatives: product scenes, banner backgrounds, and multi-variant visuals for A/B tests.
Concept art and ideation: characters, environments and style boards, iterated cheaply and fast.
Pipeline chaining: outputs feed directly into image-to-video or face swap as source material.
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.
# 1) Submit — returns { "task_uuid": "..." }
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/head-swap/image-edit" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"images": [
"https://assets-public.namifusion.com/uploads/images/2026-04-21/76c1186af77d.png",
"https://assets-public.namifusion.com/uploads/images/2026-04-21/149467630166.png"
]
}
}'
# 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?
images (Images): required
How much does it cost?
Pay-per-use in credits. About $0.220 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 (Image)
Transfer a head from one reference image onto a target photo while preserving the target body, pose, and scene.
Head Swap Image Edit is a focused two-image workflow for replacing the head in a target photograph. The first image supplies the head reference and identity; the second image supplies the body, pose, clothing, lighting context, and background that should remain. The fixed input order makes the model straightforward to use, but respecting that order is essential for a correct result.
Key Features
- Dedicated head replacement: Changes the head region while retaining the target photograph as the visual base.
- Two-image control: Separates identity reference from target composition instead of relying on a text prompt.
- Pose and scene preservation: Designed to keep the target body, clothing, framing, and background intact.
- Simple deterministic contract: Exactly two image URLs are required in a documented order.
- Square output: Produces a 1024 x 1024 edited image for consistent downstream use.
Technical Specifications
| Item | Details |
|---|---|
| Task | Head replacement / image editing |
| Required input | images, exactly two image URLs |
| Image 1 | Head and identity reference |
| Image 2 | Target photograph and base composition |
| Input order | Reference first, target second |
| Prompt | Not required |
| Output | Edited image URL |
| Output dimensions | 1024 x 1024 |
Input Guidance
Use a sharp reference image with a clearly visible head and minimal occlusion. For the target image, choose a photo where the head, neck, and surrounding hair or clothing boundaries are readable. Similar camera angles and compatible lighting generally produce a more natural blend. The two URLs must remain in the exact documented order.
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 (Image) 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.