How to Use the Image FaceSwap Pro API: face swap integration guide (2026)

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

Learn how to call the Image FaceSwap Pro API on NamiFusion: parameters, pricing (from ≈$0.200) and runnable copy-paste code — try it in the playground first.

Image FaceSwap Pro is a face swap model by NamiFusion: Image FaceSwap Pro supports single-face automatic detection and multi-face precise mapping with keypoint pairs. 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.200.

TL;DR

· Task type: face swap, provided by NamiFusion

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

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

What can you build with Image FaceSwap Pro?

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/faceswap-image-pro" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "sourceImage": "https://kaito-1328216764.cos.ap-tokyo.myqcloud.com/marketplace/thumbnails/2026-01-27/d0328839a75f.png",
    "targetImage": "https://kaito-1328216764.cos.ap-tokyo.myqcloud.com/marketplace/thumbnails/2026-02-24/94a3eefdb397.png",
    "face_enhance": false
  }
}'

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

sourceImage (Source Image): required

targetImage (Target Image): required

face_enhance (Face Enhance): optional, default false

How do you write prompts for Image FaceSwap Pro?

1. Subject first: lead with the actor and action, then add environment, lighting and style ("an astronaut sprinting through a neon street in the rain, cinematic, shallow depth of field").

2. Concrete nouns beat stacked adjectives: "85mm portrait lens, golden-hour backlight" works far better than "very beautiful, ultra high quality".

3. Change one variable per iteration: pin the seed to reproduce a result, tweak a single phrase at a time so you know what actually moved the output.

4. State negatives positively: instead of "no blur", ask for "sharp focus, crisp details".

How much does it cost?

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

Image FaceSwap Pro

AI Image FaceSwap Pro: Supports single-person automatic face swap and multi-person precise keypoint mapping for highly controllable face swap scenarios.

NamiFusion Image FaceSwap Pro is an image face swap API designed for high-precision scenarios. It supports two input modes: single-person automatic mode (string URL) and multi-person precise mode (object arrays + keypoints), allowing you to balance ease of use and controllability across different business scenarios.

Key Features

Single-Person Automatic Face Swap: Pass sourceImage and targetImage directly as string URLs, and the system automatically detects facial keypoints.
Multi-Person Precise Mapping: Use ImageWithKeypoints[] and provide keypoints in opts to process pairs one by one by index.
Optional Face Enhancement: face_enhance only supports boolean values. When enabled, it removes facial blemishes and improves facial appearance.
Unified Input Structure: Supports both string input and object-array input.

Technical Specifications

Parameter	Details
Core input fields	`sourceImage`, `targetImage`, `face_enhance`
Image object structure	`ImageWithKeypoints` (`path` + `opts`)
Single-person mode input	String URL / path
Multi-person mode input	`ImageWithKeypoints[]` array

Quick Start

API Endpoint

Endpoint	Method	Description
`/api/v1/marketplace/run/namifusion/faceswap-image-pro`	POST	Submit a FaceSwap Pro task
`/api/v1/marketplace/run/tasks/{task_uuid}`	GET	Query task status and result

Request Parameter Overview

The core FaceSwap Pro fields in the request body are as follows:

{
  "sourceImage": "string | ImageWithKeypoints[]",
  "targetImage": "string | ImageWithKeypoints[]",
  "face_enhance": "boolean"
}

Authentication

Include your API Key in the request header if required by your service gateway:

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

Standard Call Flow

FaceSwap Pro uses an asynchronous task workflow:

Call POST /api/v1/marketplace/run/namifusion/faceswap-image-pro to submit a task.
Get the task_uuid from the response.
Call GET /api/v1/marketplace/run/tasks/{task_uuid} to poll the task status.
When status becomes completed, read the result from output; if it becomes failed, check error_message.

Step 1: Submit the Task

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-image-pro" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "sourceImage": "https://example.com/source.jpg",
      "targetImage": "https://example.com/target.jpg",
      "face_enhance": false
    }
  }'

Example successful submission response:

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "estimated_time": 150,
  "cost_credits": 10
}

Step 2: Query the Result

curl -X GET "https://www.namifusion.com/api/v1/marketplace/run/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: sk-your-api-key"

Example processing response:

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_id": "namifusion/faceswap-image-pro",
  "status": "processing",
  "output": null,
  "error_message": null,
  "created_at": "2026-04-13T10:00:00Z",
  "completed_at": null
}

Example completed response:

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 Image FaceSwap Pro 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 →