换脸

namifusion/faceswap-v5

NamiFusion Faceswap v5 is a high-speed, cost-effective model designed for large-scale, real-time workflows, delivering lifelike results with automatic skin tone matching and professional quality.

Examples

Parameters

Name	Type	Default	Constraints
source_imageSource Image (Face)	image_upload	—	0–1 items
target_imageTarget Image (Body/Scene)	image_upload	—	0–1 items
additional_promptAdditional Prompt	textarea	—	—
image_formatOutput Format	select	jpeg	png \| jpeg \| webp
qualityImage Quality	slider	95	10 ~ 100 · step 1
seedSeed	number	8005332	—

Output fields

Field	Type	Description
images	array<string>

API

Call this model through one unified REST API. Get a key on the API Keys page.

cURL

# 1) Submit — returns { "task_uuid": "..." }
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-v5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "source_image": [
      "https://segmind-resources.s3.amazonaws.com/input/d823dde1-aaae-4231-87b7-1d472bc71cef-faceswap-v5-input.png"
    ],
    "target_image": [
      "https://segmind-inference-inputs.s3.amazonaws.com/48892b17-762c-4de5-b6d8-f99d8e139115-black-man-image.jpeg"
    ],
    "image_format": "jpeg",
    "quality": 95,
    "seed": 8005332
  }
}'

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

Python

import time, requests

API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1) Submit
resp = requests.post(
    "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-v5",
    headers=HEADERS,
    json={
        "input": {
            "source_image": [
                "https://segmind-resources.s3.amazonaws.com/input/d823dde1-aaae-4231-87b7-1d472bc71cef-faceswap-v5-input.png"
            ],
            "target_image": [
                "https://segmind-inference-inputs.s3.amazonaws.com/48892b17-762c-4de5-b6d8-f99d8e139115-black-man-image.jpeg"
            ],
            "image_format": "jpeg",
            "quality": 95,
            "seed": 8005332
        }
    },
)
resp.raise_for_status()  # 401/402/429/5xx stop here instead of polling a bad task
task = resp.json()

# 2) Poll until a terminal state (completed / failed / cancelled).
#    This model is allowed up to 300s server-side.
deadline = time.time() + 360
while task.get("status") not in ("completed", "failed", "cancelled"):
    if time.time() > deadline:
        raise TimeoutError(f"still {task.get('status')} — keep the task_uuid and poll later")
    time.sleep(3)
    poll = requests.get(f"https://www.namifusion.com/api/v1/marketplace/run/tasks/{task['task_uuid']}", headers=HEADERS)
    poll.raise_for_status()
    task = poll.json()

print(task["status"], task.get("output"))

JavaScript

const API_KEY = "YOUR_API_KEY";
const HEADERS = { Authorization: `Bearer ${API_KEY}` };

// 1) Submit
const resp = await fetch("https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-v5", {
  method: "POST",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({
    "input": {
      "source_image": [
        "https://segmind-resources.s3.amazonaws.com/input/d823dde1-aaae-4231-87b7-1d472bc71cef-faceswap-v5-input.png"
      ],
      "target_image": [
        "https://segmind-inference-inputs.s3.amazonaws.com/48892b17-762c-4de5-b6d8-f99d8e139115-black-man-image.jpeg"
      ],
      "image_format": "jpeg",
      "quality": 95,
      "seed": 8005332
    }
  }),
});
if (!resp.ok) throw new Error(`submit failed: ${resp.status} ${await resp.text()}`);
let task = await resp.json();

// 2) Poll until a terminal state (completed / failed / cancelled).
//    This model is allowed up to 300s server-side.
const deadline = Date.now() + 360 * 1000;
while (!["completed", "failed", "cancelled"].includes(task.status)) {
  if (Date.now() > deadline) throw new Error(`still ${task.status} — keep the task_uuid and poll later`);
  await new Promise((r) => setTimeout(r, 3000));
  const poll = await fetch(`https://www.namifusion.com/api/v1/marketplace/run/tasks/${task.task_uuid}`, { headers: HEADERS });
  if (!poll.ok) throw new Error(`poll failed: ${poll.status}`);
  task = await poll.json();
}

console.log(task.status, task.output);

Documentation

NamiFusion Faceswap v5

AI Image FaceSwap v5: Ultra-fast face and smart head swapping with built-in skin tone matching for high-volume, production-ready workflows.

NamiFusion Faceswap v5 is an image face swap API designed for speed and scale. It delivers v2-level inference speed with significantly improved output quality, featuring automatic smart head swapping, built-in skin tone matching, and creative prompt support — all at the lowest cost in the NamiFusion faceswap lineup.

Key Features

Ultra-Fast Inference: Matches Faceswap v2's speed while delivering substantially better visual quality.
Smart Head Swap: Automatically determines whether face-only or full-head blending produces the most natural result — no manual mode selection required.
Built-In Skin Tone Matching: Adapts skin tones automatically for natural, seamless results without manual correction.
Creative Prompt Support: Use additional_prompt to guide subtle attribute changes like "wearing a hat" or "smiling".
Reproducible Outputs: Seed-based generation ensures consistent results across runs, ideal for A/B testing and batch workflows.
Cost-Optimized: The most affordable faceswap option in the NamiFusion lineup without sacrificing professional-level quality.

Technical Specifications

Parameter	Details
Core input fields	`source_image`, `target_image`, `seed`
Optional fields	`additional_prompt`, `image_format`, `quality`
Image format options	`png`, `jpeg`, `webp`
Quality range	10 – 100 (default: `95`)
Seed default	`8005332`
Average inference time	~9.63s

Quick Start

API Endpoint

Endpoint	Method	Description
`/api/v1/marketplace/run/namifusion/faceswap-v5`	POST	Submit a Faceswap v5 task (synchronous)

Faceswap v5 uses a synchronous response model — the result is returned directly in the response body, no polling required.

Request Parameter Overview

The core Faceswap v5 fields in the request body are as follows:

{
  "source_image": "string (URL)",
  "target_image": "string (URL)",
  "additional_prompt": "string",
  "image_format": "png | jpeg | webp",
  "quality": 95,
  "seed": 8005332
}

Authentication

Include your API Key in the request header:

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

Standard Call Flow

Faceswap v5 uses a synchronous workflow — the result image is returned directly:

Call POST /api/v1/marketplace/run/namifusion/faceswap-v5 with your input parameters.
The response contains the result image directly.
No polling step is needed.

Submit the Task and Get the Result

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-v5" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_image": "https://example.com/source.jpg",
      "target_image": "https://example.com/target.jpg",
      "image_format": "png",
      "quality": 95,
      "seed": 8005332
    }
  }'

Example successful response:

{
  "status": "completed",
  "output": {
    "image_url": "https://cdn.namifusion.com/result/faceswap_v5_abc123.png"
  }
}

Example failed response:

{
  "status": "failed",
  "output": null,
  "error_message": "Face swap failed because no valid face was detected in source_image."
}

Scenario 1: Basic Face Swap (Minimal Parameters)

Suitable for quick testing or simple single-face swap scenarios where default quality and format are acceptable.

Request Example

{
  "source_image": "https://example.com/source.jpg",
  "target_image": "https://example.com/target.jpg"
}

Behavior

image_format defaults to png.
quality defaults to 95.
seed defaults to 8005332.
Smart head swap runs automatically — no mode selection needed.
Built-in skin tone matching is always active.

Scenario 2: Production Face Swap (Full Parameters)

Suitable for production pipelines, marketing campaigns, or content creation where output format, quality, and reproducibility matter.

Request Example

{
  "source_image": "https://example.com/source_face.jpg",
  "target_image": "https://example.com/target_person.jpg",
  "additional_prompt": "wearing a hat",
  "image_format": "jpeg",
  "quality": 95,
  "seed": 2023
}

Behavior

additional_prompt guides subtle attribute changes in the output (e.g., accessories, expressions).
image_format: "jpeg" produces smaller files, ideal for web delivery.
quality: 95 ensures production-grade output fidelity.
A fixed seed guarantees identical results on repeated calls with the same inputs.

Scenario 3: High-Volume Batch Processing (Speed-Optimized)

Suitable for automation pipelines, dataset anonymization, or real-time applications where throughput and cost matter more than maximum quality.

Request Example

{
  "source_image": "https://example.com/source.jpg",
  "target_image": "https://example.com/target.jpg",
  "image_format": "webp",
  "quality": 75,
  "seed": 42
}

Behavior

quality: 75 reduces processing time and output size while maintaining acceptable visual quality.
image_format: "webp" offers the best balance of compression and quality for web-scale delivery.
A consistent seed across batch runs ensures reproducible outputs for caching and A/B testing.

Parameter and Return Value Details

Request Parameters

Parameter	Type	Required	Default	Description
`source_image`	`string`	Yes	—	URL of the source image providing the face identity.
`target_image`	`string`	Yes	—	URL of the target image where the face will be replaced.
`additional_prompt`	`string`	No	`""`	Short descriptive prompt for subtle attribute guidance (e.g., `"wearing a hat"`, `"smiling"`).
`image_format`	`string`	No	`"png"`	Output image format. Accepted values: `"png"`, `"jpeg"`, `"webp"`.
`quality`	`integer`	No	`95`	Output quality from `10` to `100`. Higher values produce better fidelity at the cost of file size.
`seed`	`integer`	No	`8005332`	Random seed for reproducibility. Use the same seed with the same inputs to get identical outputs.

Validation Rules and Common Errors

`source_image` / `target_image`

Must be publicly accessible URLs.
The face in source_image provides the identity; the face in target_image is the one being replaced.
Use clear, front-facing images with visible facial features for best results.

`additional_prompt`

Keep prompts short and descriptive (e.g., "wearing sunglasses", "different hairstyle").
Avoid long or complex prompts — v5 is optimized for subtle, controlled variations.
Leave blank if no attribute modification is needed.

`image_format`

Accepted values: "png", "jpeg", "webp".
jpeg is recommended for speed and size efficiency.
png is recommended when maximum detail or post-editing flexibility is required.
webp offers the best balance of quality and compression.

`quality`

Integer between 10 and 100.
Recommended: 95 for production and final assets; 75–85 for fast testing and iteration.

Impact of Parameters on Output

Parameter combination	Impact on result
`quality: 95`	Production-grade fidelity; larger file size.
`quality: 75–85`	Faster processing and smaller files; suitable for testing.
`image_format: "jpeg"`	Fastest processing and smallest file size.
`image_format: "png"`	Maximum detail; best for post-editing.
`image_format: "webp"`	Best quality-to-size ratio for web delivery.
`additional_prompt` provided	Guides subtle attribute changes in the swapped face output.
`additional_prompt` empty	No attribute modification; pure face/head swap.
Fixed `seed`	Identical outputs on repeated calls with the same inputs.
Random `seed`	Slight variation in output across runs.

Recommended Settings by Use Case

Use Case	`quality`	`image_format`	`seed`	`additional_prompt`
Content Creation (Thumbnails, Social Media)	`85`	`webp`	`1001`	`"wearing sunglasses"`
Marketing & Advertising (Campaign Mockups)	`95`	`jpeg`	`2023`	`"different hairstyle"`
Privacy Protection (Dataset Anonymization)	`90`	`png`	`31415`	(leave blank)
Real-Time / High-Volume Batch Processing	`75`	`jpeg` or `webp`	`42`	(leave blank)

Notes

Smart head swap is always on: Faceswap v5 automatically decides between face-only and full-head blending — no configuration needed.
Skin tone matching is built-in: Manual color correction is rarely needed; the model adapts skin tones automatically.
Keep images reasonably aligned: Source and target images with similar head angles and lighting produce the most natural results.
Use fixed seeds for consistency: For A/B testing, caching, and batch pipelines, lock the seed to ensure reproducible outputs.
Prefer publicly accessible URLs: This helps the service fetch image resources reliably.
Avoid complex prompts: additional_prompt is designed for short, subtle attribute hints — not detailed scene descriptions.

Related models

Face SwapNamiFusion

namifusion Image/Video Face Swap

NamiFusion Video Face Swap Model Supports images and videos, easy single or multi-person face swapping. Compatible with multiple model_style options, can output realistic results or one-click beauty-enhanced versions — natural and great-looking!

from $0.400 / per run

Face SwapNamiFusion

Image FaceSwap Pro

Image FaceSwap Pro supports single-face automatic detection and multi-face precise mapping with keypoint pairs.

from $0.200 / per run

Face SwapNamiFusion

namifusion Image Face Swap

NamiFusion Face Swap Model Easy single or multi-person face swapping. Compatible with multiple model_style options, can output realistic results or one-click beauty-enhanced versions — natural and great-looking!

from $0.150 / per run

Face SwapNamiFusion

FaceDetect

A face detection model used to detect facial information contained in input elements.

from $0.000 / per run

换脸

Examples

Parameters

Output fields

API

Documentation

NamiFusion Faceswap v5

Key Features

Technical Specifications

Quick Start

API Endpoint

Request Parameter Overview

Authentication

Standard Call Flow

Submit the Task and Get the Result

Scenario 1: Basic Face Swap (Minimal Parameters)

Request Example

Behavior

Scenario 2: Production Face Swap (Full Parameters)

Request Example

Behavior

Scenario 3: High-Volume Batch Processing (Speed-Optimized)

Request Example

Behavior

Parameter and Return Value Details

Request Parameters

Validation Rules and Common Errors

source_image / target_image

additional_prompt

image_format

quality

Impact of Parameters on Output

Recommended Settings by Use Case

Notes

Related models

namifusion Image/Video Face Swap

Image FaceSwap Pro

namifusion Image Face Swap

FaceDetect

`source_image` / `target_image`

`additional_prompt`

`image_format`

`quality`