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

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

Learn how to call the Character Swap – Analyze API on NamiFusion: parameters, pricing (from ≈$0.100) and runnable copy-paste code — try it in the playground first.

Character Swap – Analyze is a character swap model by NamiFusion: Detect and track every person in a video with SAM3. Returns a character 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 Character 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/character-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.

Character Swap – Analyze

Detect and track every person in a video before assigning replacement character references.

Character Swap Analyze is the first stage of the two-step Character Swap workflow. It follows people across the input video and returns the obj_id values and track_manifest_url required by the Generate stage. This model does not replace anyone by itself. Keep the analysis result together with the original video and resolution so the next request uses a consistent set of inputs.

Key Features

Person detection and tracking: Identifies people in the video and builds object tracks across frames.
Selectable previews: Returns an objects list with each person's obj_id, preview, mask, and coverage information.
Generate-ready manifest: Produces a track_manifest_url that can be passed directly to Character Swap Generate.
Video metadata: Includes width, height, FPS, and frame count in video_info.
480p and 720p analysis: Lets you select the same resolution that will be used for generation.

Technical Specifications

Item	Details
Workflow	Character 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/character-swap/generate`

Basic Workflow

Send the video URL and selected resolution to namifusion/character-swap/analyze.
Poll the task result endpoint until processing completes.
Review the previews in objects and select the obj_id values to replace.
Pass the same video_url, returned track_manifest_url, and selected IDs to the Generate stage.

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 Character 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 →