---
title: "Head Swap"
method: POST
path: "/v1/head-swap"
tags: ["Image Projects"]
---

# Head Swap

`POST /v1/head-swap`

Swap a head onto a body image. Each image costs 10 credits. Output resolution depends on your subscription; you may set `max_resolution` lower than your plan maximum if desired.

## Request body

- object
  - `name` string — Give your image a custom name for easy identification.
  - `max_resolution` integer — Constrains the larger dimension (height or width) of the output. Omit to use the maximum allowed for your plan (capped at 2048px). Values above your plan maximum are clamped down to your plan's maximum.
  - `assets` object, required — Provide the body and head images for head swap
    - `body_file_path` string, required — Image that receives the swapped head. 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.
    - `head_file_path` string, required — Image of the head to place on the body. 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)