AI Tools
Image Face Swap

Image Face Swap

Overview

An advanced AI tool for face detection and face swapping between images.

Process Flow

  1. Upload images to storage:
    • Upload source image & target image to S3 or other storage provider
    • Get the generated public URLs for both images
  2. Detect faces in the images using the face detection API
  3. Use the detected face coordinates to perform face swap
  4. Monitor the job status until completion

1. Face Detection API

API Reference

  • URL: https://api.maxstudio.ai/detect-face-image
  • Method: POST

Important Notes

  • The input image must contain at least one clear, visible human face.
  • Faces should be well-lit and not obscured by objects, masks, or extreme angles.
  • The API can detect multiple faces in a single image.

Request Parameters

NameTypeRequiredDescription
imageUrlstringyesYou must first upload your image to our server before processing. Use the URL received from the upload API response - external URLs are not supported.

Headers

NameTypeRequiredDescription
x-api-keystringyesYour API key obtained from the MaxStudio APIs Dashboard (opens in a new tab). Generate this key by logging into your account and navigating to the API Keys section.

Response Format

{
  "faces": [
    {
      "x": 100,        // X coordinate of face
      "y": 150,        // Y coordinate of face
      "width": 200,    // Width of detected face
      "height": 200    // Height of detected face
    },
    // Multiple faces may be detected
  ]
}

Code Examples

// TypeScript implementation
interface FaceDetection {
  x: number;
  y: number;
  width: number;
  height: number;
}
async function detectFaces(imageUrl: string): Promise<FaceDetection[]> {
  try {
    const response = await fetch('https://api.maxstudio.ai/detect-face-image', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ imageUrl })
    });
    const jobId = await response.json();
    return jobId;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

2. Face Swap API

API Reference

  • URL: https://api.maxstudio.ai/faceswap
  • Method: POST

Request Parameters

NameTypeRequiredDescription
mediaUrlstringyesURL of the target image
facesarrayyesAn array that defines which faces to swap and where to place them. Each item in the array contains:
  • newFace: Specifies the face you want to use
    • imageUrl: URL of the image containing the face you want to swap in
  • originalFace: Specifies where to place the face in the main image
    • x: Position from left edge (in pixels)
    • y: Position from top edge (in pixels)
    • width: Width of the face area
    • height: Height of the face area

Tip: Use the Face Detection API first to get the correct target coordinates for faces in your main image.

Headers

NameTypeRequiredDescription
x-api-keystringyesYour API key obtained from the MaxStudio APIs Dashboard (opens in a new tab). Generate this key by logging into your account and navigating to the API Keys section.

Request Body Example

{
  "mediaUrl": "https://example.com/target-image.jpg",
  "faces": [
    {
      "originalFace": {
        "x": 300,
        "y": 400,
        "width": 250,
        "height": 250
      }
      "newFace": "https://example.com/source-face1.jpg",
    },
    {
      "originalFace": {
        "x": 800,
        "y": 500,
        "width": 220,
        "height": 220
      }
      "newFace": "https://example.com/source-face2.jpg",
    }
  ]
}

Code Examples for Swap Image

// TypeScript implementation
interface Face {
  newFace: {
    imageUrl: string;
  };
  originalFace: {
    x: number;
    y: number;
    width: number;
    height: number;
  };
}
interface SwapImageParams {
  mediaUrl: string;
  faces: Face[];
}
async function swapImage(params: SwapImageParams): Promise<any> {
  try {
    const response = await fetch('https://api.maxstudio.ai/swap-image', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(params)
    });
    const jobId = await response.json();
    return jobId;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

Important Notes

  • You can swap multiple face in single image if there are multiple faces in the image

Success Response

{
  "jobId": "<job_id>",
  "status": "pending"
}

Error Response Examples

// Rate Limit Error
{
  "status": 429,
  "error": "Rate limit exceeded. Please try again later."
}
// Insufficient Credits
{
  "status": 402,
  "error": "Insufficient credits. Please Buy credits."
}
// Invalid Input
{
  "status": 400,
  "error": "Image size must be less than 5MB"
}

Get Job Status

Headers

NameTypeRequiredDescription
x-api-keystringyesYour API key obtained from the MaxStudio APIs Dashboard (opens in a new tab). Generate this key by logging into your account and navigating to the API Keys section.

To check the status of your job, use the following examples:

// TypeScript implementation
async function getJobStatus(jobId: string): Promise<void> {
  const url = `https://api.maxstudio.ai/swap-image/${jobId}`;
  try {
    const response = await axios.get(url);
    const jobId = response.data;
    return jobId;
  } catch (error) {
    console.error('Error:', error);
  }
}

Job Status Reference

StatusDescription
creatingJob is being initialized
pendingJob is in processing queue
runningJob is actively processing
completedProcessing finished successfully
failedProcessing encountered an error
not-foundInvalid or expired job ID

Output

{
  "status": "<status>",  // One of the status values from the table above
  "result": {
    "mediaUrl": "<media_url>",
  }
}
AI ToolsVideo Face Swap