VidMage

VidMage is an AI video and image creation platform for creators. Turn your ideas and images into videos and fresh visuals.

Open the creator tools
Explore APIs
AI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
Build with VidMage
QuickstartAPI keysVidMage MCPError reference
Your account
Developer consoleAbout VidMagePlans and creditsAPI billingContact support
© 2026 VidMage. All rights reserved.
Privacy PolicyTerms of ServiceReport Abuse
Skip to content
VidMage/Developers
Overview
APIs
All APIsAI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
DocumentationVidMage MCPOpen console
Developers/AI Multi Face Swap API for Photos and Videos

AI Multi Face Swap API for Photos and Videos

Add multi-face swapping to your photo and video app. Map each target face to a reference image, with support for up to 20 mappings per photo and four per video.

Get API keyView API docs
Abstract illustration for AI Multi Face Swap API for Photos and Videos
PlaygroundAPIPricingGuideFAQs

AI Multi Face Swap API Playground

Use your existing API key and subscription. Submitting a generation uses credits; uploading and preparing a request does not start a generation.

API access is available to subscribers only. Your subscription credits are shared across the website and the API.

View plans

Parameter

2 parameters

Publicly reachable URL of the target photo.

One to 20 reference mappings. Omit targetFaceIndex/referenceFaceIndex until get_task_result returns indexed previews, or provide explicit stable indexes.

minItems 1maxItems 20

Request code

#!/usr/bin/env bash
set -euo pipefail
# Set this once per intended task; preserve it and the body for transport retries.
: "${VIDMAGE_IDEMPOTENCY_KEY:?Set a unique key for this task}"

SUBMIT_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/multiple-face-swap/submit" \
  -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "targetImageUrl": "https://vidmage.ai/assets/images/ai-tools/close-up-group-people.webp",
  "faceMappings": [
    {
      "referenceFaceImageUrl": "https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp"
    }
  ]
}')"
TASK_ID="$(printf '%s' "$SUBMIT_RESPONSE" | jq -er '.["taskId"]')"

while true; do
  QUERY_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/multiple-face-swap/query" \
    -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-raw "{\"taskId\":\"${TASK_ID}\"}")"
  STATUS="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.status // .data.status // "") | ascii_downcase')"
  case "$STATUS" in
    success|succeeded|completed)
      RESULT="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.result // .["imageUrl"] // .data["imageUrl"] // empty)')"
      if [ -z "$RESULT" ]; then
        printf '%s' "Result missing; preserve task $TASK_ID and query the same task again. Do not resubmit." >&2
        exit 2
      fi
      printf '%s\n' "$RESULT"
      break
      ;;
    needs_input)
      printf '%s' "Face selection required; preserve task $TASK_ID" >&2
      exit 2
      ;;
    failed|error)
      printf '%s' "$QUERY_RESPONSE" | jq -r '(.message // .error // .data.error // "Task failed")' >&2
      exit 1
      ;;
  esac
  sleep 5
done

Response data

Submit the task to see the API response here.
PlaygroundCapabilities

API documentation

Submit a request, track the task, and retrieve your result.

EndpointMultiple Face Swap ↓
Required inputs
targetImageUrl faceMappings
Output
Image·imageUrl
EndpointMultiple Face Swap Video ↓
Required inputs
targetVideoUrl faceMappings
Output
Video·videoUrl
Request setup & limitsHeaders, input options and media limits

Request headers

Authorization
Bearer YOUR_API_KEY

Keep your API key on your server.

Content-Type
application/json
Idempotency-Key
YOUR_UNIQUE_KEY

Use a new key per task. Reuse it only when retrying the same submission.

Input options & limits

Request controls follow each task's parameter rules; they do not guarantee output properties.

Multiple Face Swap

RequiredtargetImageUrl faceMappings
Request controls
  • faceMappings: see parameter rules

Output dimensions and format are not specified in this reference.

Multiple Face Swap Video

RequiredtargetVideoUrl faceMappings
Request controls
  • faceMappings: see parameter rules

Output dimensions and format are not specified in this reference.

Input retention and output-link lifetime depend on the API contract. Confirm API-specific retention terms before making promises to your users. Upload guide ↗

Multiple Face Swap

POST /api/v1/multiple-face-swap/submit

Full API documentation ↗

targetImageUrl is required and faceMappings is required.

Required inputs

targetImageUrlstring
Publicly reachable URL of the target photo.
faceMappingsobject[]
One to 20 reference mappings. Omit targetFaceIndex/referenceFaceIndex until get_task_result returns indexed previews, or provide explicit stable indexes.

Edit the sample inputs for your own task before submitting.

Multiple Face Swap request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/multiple-face-swap/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"targetImageUrl":"https://vidmage.ai/assets/images/ai-tools/close-up-group-people.webp","faceMappings":[{"referenceFaceImageUrl":"https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp"}]}'
# -> { "success": true, "taskId": "...", "creditsRequired": ..., "creditsConsumed": 0, "usageDeferred": true }
Parameters and input rules2 fields
FieldTypeRequiredDefaultMeaning and limits
targetImageUrlstringYesNot specifiedPublicly reachable URL of the target photo. No additional field constraint listed.
faceMappingsobject[]YesNot specifiedOne to 20 reference mappings. Omit targetFaceIndex/referenceFaceIndex until get_task_result returns indexed previews, or provide explicit stable indexes. Minimum items: 1 · Maximum items: 20

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/multiple-face-swap/query

Use the same Bearer API key. On completion, read the imageUrl result field.

Task states and recovery ↗
Multiple Face Swap query
curl -X POST "https://vidmage.ai/api/v1/multiple-face-swap/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }

Multiple Face Swap Video

POST /api/v1/multiple-face-swap-video/submit

Full API documentation ↗

targetVideoUrl is required and faceMappings is required.

Required inputs

targetVideoUrlstring
Target-video fileUrl returned by upload_files.
faceMappingsobject[]
One to four reference mappings. Omit indexes until get_task_result returns indexed previews, or provide explicit stable indexes.

Edit the sample inputs for your own task before submitting.

Multiple Face Swap Video request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/multiple-face-swap-video/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"targetVideoUrl":"https://vidmage.ai/assets/models/hailuo-ai-video-generator/skincare-ad.mp4","faceMappings":[{"referenceFaceImageUrl":"https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp"}]}'
# -> { "success": true, "taskId": "...", "creditsRequired": ..., "creditsConsumed": 0, "usageDeferred": true }
Parameters and input rules2 fields
FieldTypeRequiredDefaultMeaning and limits
targetVideoUrlstringYesNot specifiedTarget-video fileUrl returned by upload_files. No additional field constraint listed.
faceMappingsobject[]YesNot specifiedOne to four reference mappings. Omit indexes until get_task_result returns indexed previews, or provide explicit stable indexes. Minimum items: 1 · Maximum items: 4

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/multiple-face-swap-video/query

Use the same Bearer API key. On completion, read the videoUrl result field.

Task states and recovery ↗
Multiple Face Swap Video query
curl -X POST "https://vidmage.ai/api/v1/multiple-face-swap-video/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "videoUrl": "https://..." } }

Pricing

See what one image, video, or generation costs in credits. Your API and website activity share the same credit balance.

API credit rates and calculated example request costs
API / workflowExample requestPrice (credits)
Multiple Face Swapimage API1 image request: 1 credit
How this is calculated
  • Per request: 1 credit / image

A fixed credit charge applies to this API request.

Estimate your own request ↗
1 credit / imageSee calculation details
Multiple Face Swap Videovideo API5.875-second video: 6 credits
How this is calculated
  • Video duration: 1 credit / second

The example uses the duration shown above. The server measures uploaded media for billing; this duration is only supplied to the estimate.

Duration × rate is rounded up to whole credits; the applicable minimum charge is enforced.

Estimate your own request ↗
1 credit / secondSee calculation details
Billed in credits. Shared with the website.Active subscription required. Unit rates and examples follow current API credit rules.Billing details⌄

Examples show the charge for the inputs listed above. Resolution, duration, audio, output count and reference media can change the total. Minimum charges and rounding follow the selected API.

Use the Playground to estimate your request before submitting it. Estimates do not start a generation. Subscription and credit-pack prices are listed on the plans page.

Your task’s recorded usage is the source of truth for the final charge.

View plans ↗Billing guide ↗

About AI Multi Face Swap API

VidMage's AI Multi Face Swap API is an interface for replacing multiple faces in a photo or video. It accepts a target asset and a set of face mappings, each linked to a reference image. The result is an edited image or video for group face editing workflows. To try multiple face replacements in a group photo, open VidMage's Multi Face Swap Photo.

AI Multi Face Swap API capabilities

Photo face mapping
Assign separate reference faces to as many as 20 target faces within a single photo request.
Video face mapping
Map up to four target faces in one video, using individual reference images for each replacement.
Explicit face selection
Use target and reference face indices to identify which people belong together in each mapping.

What you can build

Personalized team posters

Build a team poster around the actual club members. Each portrait maps to a selected person in the template, and the combined edit becomes the base for a season announcement or match-day graphic. Names can be added in your design layer.

Ensemble casting previews

A scene with several performers calls for separate face assignments. Map consenting actors' portraits to the people in test footage, within the video mapping limit, to explore how an ensemble might look together during a casting discussion.

Group photo booth souvenirs

Friends pick a themed group scene and match their selfies to its faces. One edited image brings the group into the chosen setting, giving an event booth a shared souvenir alongside its individual portraits.

How to use AI Multi Face Swap API

  1. Get an API key

    Create a key in the Developer Console and store it on your server. Use it in the Authorization: Bearer header.

  2. Prepare and submit your inputs

    Set up your inputs in the Playground, then copy the matching API request. Send it from your server with a unique Idempotency-Key.

  3. Track the task

    Save the returned taskId and query the same operation until it completes. Keep that identifier if your app stops waiting.

  4. Retrieve the result

    Read imageUrl or videoUrl from the completed task. Preview the result in your app and save a copy to your own storage for later use.

Input tips
Validate the selected media mode
Photo requests allow 1 to 20 mappings, while video requests allow 1 to 4. Apply the matching limit when users switch media types.
Keep indices tied to the asset
Face indices select faces within the supplied file. Review them for every new target or reference instead of treating an index as a saved person identifier.

Input requirementsUpload local files

Task fields and results

Keep the task identifier with its original request and Idempotency-Key. Query the same capability until it completes, then read the documented result field.

Task identifier
taskId
Query route
POST /api/v1/multiple-face-swap/query
Completed result
imageUrl
Task states and response structure ↗
Errors, retries and limits

Retry transport failures with the same idempotency key only when the original submission may not have reached the server. For a confirmed task, keep querying the original task instead of submitting a duplicate.

Read error recovery guidance ↗

FAQs

Is multi-face swap the same as batch face swap?

Multi-face editing handles one target per task. A batch needs a separate job for each target file. Use a single-face endpoint when a target only needs one replacement.

Are failed or timed-out requests charged?

A client timeout is not a confirmed task failure. Confirmed failures are automatically refunded only when the refund outcome is certain. Unknown charges or refunds remain pending reconciliation.

Failure and refund handling ↗
How long should my app wait for a result?

The checked contract does not establish a fixed completion time. Choose a local wait budget for your app; it is not an API completion deadline.

Polling and wait budgets ↗
What are the rate and concurrency limits?

Request-rate limits control how often you can call the API; concurrency limits control simultaneous work. The documentation ties both to the stable API key but does not publish numeric limits for this operation. Confirm account limits before planning parallel jobs.

Rate-limit recovery ↗
Can I receive results through a webhook?

The checked request contract documents status queries and does not list a webhook or callback field for these routes. Check the current authenticated OpenAPI contract before making a callback part of your integration.

Query task results ↗Check the current contract ↗

Explore more APIs on VidMage

  • AI Video Face Swap API for Clip Workflows↗
  • AI GIF Face Swap API for Animated Images↗
  • AI Photo Face Swap API↗
  • AI Head Swap API for Photos and Videos↗
  • AI Video Watermark Remover API for Two Inputs↗
  • AI Object Remover API for Masked Image Cleanup↗
  • AI Video Background Remover API for Clips↗
  • Hailuo API↗