---
title: "Face Swap Photo"
method: POST
path: "/v1/face-swap-photo"
tags: ["Image Projects"]
---

# Face Swap Photo

`POST /v1/face-swap-photo`

Create a face swap photo. Each photo costs 10 credits. The height/width of the output image depends on your subscription. Please refer to our [pricing](https://magichour.ai/pricing) page for more details

## Request body

- object
  - `name` string — Give your image a custom name for easy identification.
  - `assets` object, required — Provide the assets for face swap photo
    - `face_swap_mode` 'all-faces' | 'individual-faces' — Choose how to swap faces: **all-faces** (recommended) — swap all detected faces using one source image (`source_file_path` required) +- **individual-faces** — specify exact mappings using `face_mappings`
    - `source_file_path` string — This is the image from which the face is extracted. The value is required if `face_swap_mode` is `all-faces`. This value is either - a direct URL to the video file - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls). See the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.
    - `face_mappings` object[] — This is the array of face mappings used for multiple face swap. The value is required if `face_swap_mode` is `individual-faces`.
      - `original_face` string, required — The face detected from the image in `target_file_path`. The file name is in the format of `<face_frame>-<face_index>.png`. This value is corresponds to the response in the [face detection API](https://docs.magichour.ai/api-reference/files/get-face-detection-details). * The face_frame is the frame number of the face in the target image. For images, the frame number is always 0. * The face_index is the index of the face in the target image, starting from 0 going left to right.
      - `new_face` string, required — The face image that will be used to replace the face in the `original_face`. This value is either - a direct URL to the video file - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls). See the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.
    - `target_file_path` string, required — This is the image where the face from the source image will be placed. This value is either - a direct URL to the video file - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls). See the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.

## Response `200`

Success

- object — Success
  - `id` string, required — Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads.
  - `credits_charged` integer, required — The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. If an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund.

## Other responses

- `400` — Invalid Request
- `401` — Unauthorized
- `402` — Payment Required
- `404` — Not Found
- `422` — Unprocessable Entity

---

[API](https://skmtc.net/magichourhq/apis/magic-hour-api.md) · [All operations](https://skmtc.net/magichourhq/apis/magic-hour-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/magichourhq/magic-hour-api/revisions/379ec88a7e47/schema)