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 Photo Face Swap API

AI Photo Face Swap API

Add photo face swapping to your app with a target image URL and a reference face image. Select one face from each input and retrieve the edited image through an asynchronous task.

Get API keyView API docs
Abstract illustration for AI Photo Face Swap API
PlaygroundAPIPricingGuideFAQs

AI Photo 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

4 parameters

Publicly reachable URL of the target photo.

Publicly reachable URL of the photo containing the replacement face.

Optional explicit zero-based target index. Omit to auto-select only when exactly one face is detected.(Optional)

min 0

Optional explicit zero-based reference index. Omit to auto-select only when exactly one face is detected.(Optional)

min 0

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/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/samples/blue-eyed-woman-sunlight.webp",
  "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/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.

Required inputs
targetImageUrl referenceFaceImageUrl
Output
Image·imageUrl
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.

Photo Face Swap

RequiredtargetImageUrl referenceFaceImageUrl
Request controls
  • targetFaceIndex: range 0 to ∞
  • referenceFaceIndex: range 0 to ∞

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 ↗

Photo Face Swap

POST /api/v1/face-swap/submit

Full API documentation ↗

targetImageUrl is required and referenceFaceImageUrl is required.

Required inputs

targetImageUrlstring
Publicly reachable URL of the target photo.
referenceFaceImageUrlstring
Publicly reachable URL of the photo containing the replacement face.

Edit the sample inputs for your own task before submitting.

Photo 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/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/samples/blue-eyed-woman-sunlight.webp","referenceFaceImageUrl":"https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp"}'
# -> { "success": true, "taskId": "...", "creditsRequired": ..., "creditsConsumed": 0, "usageDeferred": true }
Parameters and input rules4 fields
FieldTypeRequiredDefaultMeaning and limits
targetImageUrlstringYesNot specifiedPublicly reachable URL of the target photo. No additional field constraint listed.
referenceFaceImageUrlstringYesNot specifiedPublicly reachable URL of the photo containing the replacement face. No additional field constraint listed.
targetFaceIndexnumberNoNot specifiedOptional explicit zero-based target index. Omit to auto-select only when exactly one face is detected. Minimum: 0 · Whole numbers only
referenceFaceIndexnumberNoNot specifiedOptional explicit zero-based reference index. Omit to auto-select only when exactly one face is detected. Minimum: 0 · Whole numbers only

Retrieve the result

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

POST /api/v1/face-swap/query

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

Task states and recovery ↗
Photo Face Swap query
curl -X POST "https://vidmage.ai/api/v1/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://..." } }

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)
Photo 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
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 Photo Face Swap API

VidMage's AI Photo Face Swap API is an image editing interface that replaces one selected face in a still photo. It uses a target photo and a reference image containing the replacement face. Optional face indices identify one person in each image, including photos with multiple people. To swap a face in your browser, use VidMage's Photo Face Swap.

AI Photo Face Swap API capabilities

Replace one face
Send a target photo and a separate reference face image for an edited still. For footage, use AI Video Face Swap, which accepts targetVideoUrl and a reference photo.
Select the target person
Use targetFaceIndex to identify one detected face when the photo contains more than one person.
Select the reference face
Use referenceFaceIndex to choose the replacement identity from the faces detected in your reference photo.

What you can build

Personalized event posters

Put a guest into the starring role of an event poster by pairing their selfie with a themed template. The personalized still can become an invitation or event souvenir.

Virtual photo booths

Visitors choose a costume or travel scene and take a portrait at the booth. Face swapping turns that pairing into a photo souvenir, ready for your app to display with the other images from their session.

One-person edits in group photos

Sometimes only one person in a family photo needs a face replacement. Select that face and an approved reference photo, keeping the rest of the group outside the requested swap. A comparison view makes the selection easy to check.

How to use AI Photo 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 from the completed task. Preview the result in your app and save a copy to your own storage for later use.

Input tips
Indices select one pair
Face indices are whole numbers starting at zero. They select one target and one reference, not a mapping for replacing everyone in a group photo.
Check selection with real photos
If the wrong face is replaced, check target/reference roles and both indices. The detected list has no documented left-to-right order. Test one clearly visible face first to separate input quality from selection issues.
Upload local photos before submitting
For a local file, request temporary upload instructions, upload the bytes with the returned headers, then put fileUrl in its image field. A local file path is not an image URL.

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/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

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 ↗

Put your inputs to the test.

Review the inputs, then use your subscription to test in the live playground.

Build a request ↑

Explore more APIs on VidMage

  • AI Multi Face Swap API for Photos and Videos↗
  • AI Video Face Swap API for Clip Workflows↗
  • AI Head Swap API for Photos and Videos↗
  • AI GIF Face Swap API for Animated Images↗
  • AI Clothes Changer API for Outfit Previews↗
  • AI Girl Generator API for Portrait Briefs↗
  • GPT Image API↗
  • Seedream API↗