DocumentationMCPLicenseForumPricing
v1.0.0
OpenAPI 2.0

Face Swapper API

This is a public version of the Face Swapper API

Server:https://api-faceswapper.icons8.com/api
Client Libraries
Node.js undici

Process images

​

Operations about process images

Process images Operations

Detect faces on images

​

Finds the faces on each image and tells where they are: a box around each face with the detection confidence, and five landmark points. The landmarks of a face let a face swap choose which face to take and which face to replace. The answer comes back at once, and nothing is stored.

Body

required
application/json
  • urls
    Type: array of string
    required

    http(s) image urls

Responses

  • application/json
  • application/json
  • application/json
Request Example for post/v1/get_bbox
import { request } from 'undici'

const { statusCode, body } = await request('https://api-faceswapper.icons8.com/api/v1/get_bbox?token=YOUR_SECRET_TOKEN', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Api-Key': 'YOUR_SECRET_TOKEN'
  },
  body: JSON.stringify({
    urls: ['https://example.com/photos/portrait.jpg', 'https://example.com/photos/group.png']
  })
})

[
  {
    "img_url": "https://example.com/photos/portrait.jpg",
    "faces": [
      {
        "bbox": [
          412.64,
          188.31,
          598.07,
          437.92,
          0.8742
        ],
        "landmarks": [
          468.21,
          289.74,
          551.36,
          285.93,
          511.82,
          337.48,
          476.95,
          382.61,
          545.27,
          379.36
        ]
      }
    ]
  },
  {
    "img_url": "https://example.com/photos/group.png",
    "faces": [
      {
        "bbox": [
          986.4,
          331.08,
          1131.77,
          541.26,
          0.9127
        ],
        "landmarks": [
          1021.48,
          402.17,
          1098.62,
          398.85,
          1062.9,
          447.31,
          1030.12,
          489.64,
          1093.05,
          486.72
        ]
      },
      {
        "bbox": [
          254.19,
          297.55,
          392.83,
          498.14,
          0.8561
        ],
        "landmarks": [
          291.36,
          372.9,
          356.08,
          370.41,
          324.77,
          414.62,
          297.53,
          452.18,
          351.2,
          450.07
        ]
      }
    ]
  }
]

Response

Start a face swap

​

Starts a face swap that puts faces from one or more source photos onto a target photo. The swap runs in the background, so the answer comes back at once, without a result. Check the job until it is ready or has failed.

Body

required
application/json
  • target_url
    Type: string
    required

    jpg/jpeg/webp/png image url

  • face_tasks
    Type: array of object
    required
    Properties: 4

Responses

  • application/json
  • application/json
  • application/json
Request Example for post/v1/process_image
import { request } from 'undici'

const { statusCode, body } = await request('https://api-faceswapper.icons8.com/api/v1/process_image?token=YOUR_SECRET_TOKEN', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Api-Key': 'YOUR_SECRET_TOKEN'
  },
  body: JSON.stringify({
    target_url: 'https://example.com/photos/group.png',
    face_tasks: [
      {
        source_url: 'https://example.com/photos/portrait.jpg',
        source_landmarks: [468.21, 289.74, 551.36, 285.93, 511.82, 337.48, 476.95, 382.61, 545.27, 379.36],
        target_landmarks: [1021.48, 402.17, 1098.62, 398.85, 1062.9, 447.31, 1030.12, 489.64, 1093.05, 486.72],
        boundary_adjustments: {
          emotion_fear: 0,
          emotion_anger: 0,
          emotion_disgust: 0,
          emotion_surprise: 0,
          emotion_contempt: 0,
          emotion_happiness: 0,
          age: 0,
          gender: 0
        }
      }
    ]
  })
})

{
  "id": "66f2a1c4e8b1d20007a3f9c2",
  "status": 0,
  "statusName": "queue",
  "processed": null
}

Response

Get a face swap result

​

Shows the state of a face swap job and, when the job is finished, the resulting image. A job waits in the queue, then runs, then ends as ready or as an error. A failed job does not change again; start a new one to retry. Only the jobs you started through this API are found.

Path Parameters

  • id
    Type: string
    required

    ID

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/v1/process_image/{id}
import { request } from 'undici'

const { statusCode, body } = await request('https://api-faceswapper.icons8.com/api/v1/process_image/5a26a7d177840430d1af749e?token=YOUR_SECRET_TOKEN', {
  headers: {
    'Api-Key': 'YOUR_SECRET_TOKEN'
  }
})

{
  "id": "66f2a1c4e8b1d20007a3f9c2",
  "status": 2,
  "statusName": "ready",
  "processed": {
    "width": 1200,
    "height": 800,
    "type": ".jpg",
    "url": "https://ai-cdn.icons8.com/Wq3oZr1bXk9TfA2mYd7LsN4vC8eHjP0uGxRtB6nKiQs/skp:jpg/czM6Ly9yMi1haS1n/ZW5lcmF0ZWQtcGhv/dG9zL2ZhY2Vzd2Fw/cGVyLXVwbG9hZHMv/cmVzdWx0cy80MjQv/M2YyYjdjMWUtOGQ0/YS00ZTZmLTliMWMt/MmE1ZDdlOWYwYzMx/LmpwZw.jpg"
  }
}

Response

List your face swap jobs

​

Lists the face swap jobs you started through this API, newest first, page by page. Each job shows its state and, when it is finished, the resulting image.

Query Parameters

  • page
    Type: integerFormat: int32
    min:  
    1

    Page number

  • perPage
    Type: integerFormat: int32
    min:  
    1
    max:  
    100

    Number of results per page. Max: 100

Responses

  • application/json
  • application/json
  • application/json
Request Example for get/v1/process_images
import { request } from 'undici'

const { statusCode, body } = await request('https://api-faceswapper.icons8.com/api/v1/process_images?page=1&perPage=10&token=YOUR_SECRET_TOKEN', {
  headers: {
    'Api-Key': 'YOUR_SECRET_TOKEN'
  }
})

{
  "total": 3,
  "images": [
    {
      "id": "66f2a1c4e8b1d20007a3f9c2",
      "status": 0,
      "statusName": "queue",
      "processed": null
    },
    {
      "id": "66f29e7be8b1d20007a3f9b8",
      "status": 1,
      "statusName": "processing",
      "processed": null
    },
    {
      "id": "66f29c02e8b1d20007a3f9a1",
      "status": 2,
      "statusName": "ready",
      "processed": {
        "width": 1200,
        "height": 800,
        "type": ".jpg",
        "url": "https://ai-cdn.icons8.com/Wq3oZr1bXk9TfA2mYd7LsN4vC8eHjP0uGxRtB6nKiQs/skp:jpg/czM6Ly9yMi1haS1n/ZW5lcmF0ZWQtcGhv/dG9zL2ZhY2Vzd2Fw/cGVyLXVwbG9hZHMv/cmVzdWx0cy80MjQv/M2YyYjdjMWUtOGQ0/YS00ZTZmLTliMWMt/MmE1ZDdlOWYwYzMx/LmpwZw.jpg"
      }
    }
  ]
}

Response