MeduxMedux

Ai Avatar > Image Head Swap

Image Head Swap

Replace the target head with the source head while keeping the target body and scene.

POST/api/app/v1/process/image/head_swap

Examples

curl -X POST https://api.medux.io/api/app/v1/process/image/head_swap \
  -H 'Authorization: Bearer $MEDUX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model_id":"image-head-swap-default","source_image_file_id":"FILE_ID","target_head_image_file_id":"FILE_ID"}'

Media Samples

Approved examples for understanding request inputs, response shape, and official example output.

Official image head swap sample

This example uses image-head-swap-default.

Sample request

Example input for this capability.

source_image_file_id{file_id}target_head_image_file_id{file_id}

Sample response

Official example output for preview only. It is not a user Media Result.

Example output

Official example output

Auth Requirements

Authentication is required via Authorization header.

Preconditions

Upload the source file and create a file reference before calling this endpoint.

Successful requests return a Medux task record immediately. Use the task query or sync endpoints to track completion.

All file inputs must be uploaded and persisted as file references before submission.

Request

Body

application/json
Authorizationstringrequired

Bearer token or API key.

Location: HEADER

source_image_file_idstringrequired

Source image file_id.

Location: BODY

target_head_image_file_idstringrequired

Target head image file_id.

Location: BODY

model_idstringoptional

Head swap model id. Default: image-head-swap-default.

Location: BODY

titlestringoptional

Optional task title.

Location: BODY

Response

Response

application/json
codeint32optional

response code enums:
.. 0: ok
.. 12: invalid input
.. 1410: invalid model
.. 1409: paid plan required
.. 1401: insufficient credits
.... 1401 ~ 1499 是 media
.. 1404: provider error
.. 1405: provider timeout
.. 13: unauthenticated
.. 16: rate limit
.. 99: server error

Available options: 0 12 1410 1409 1401 1404 1405 13 16 99

Location: RESPONSE

data.assetobjectoptional

No description provided.

Location: RESPONSE

data.paid_plan_requiredobjectoptional

No description provided.

Location: RESPONSE

data.taskobjectoptional

No description provided.

Location: RESPONSE

messagestringoptional

No description provided.

Available options: ok invalid input invalid model paid plan required insufficient credits provider error provider timeout unauthenticated rate limit server error

Location: RESPONSE

MCP Tool

This endpoint is also available through the Medux-hosted remote MCP service.

Image Head Swap

Replace the target head with the source head while keeping the target body and scene.

Invocation Example

Replace the target head with the source head while keeping the target body and scene.