Head Swap API

About Head Swap

Head Swap transfers an entire head from a reference photo onto the person in a target image, hair and head shape included, keeping the target's body, wardrobe, pose and background. Two URLs and an optional seed.

Call it with the model name popnow/head-swap-v1/edit on POST /jobs/createTask, from 2 credits per image ($0.02). New accounts get 30 free credits to try it in the Playground first.

Introduction

Head Swap replaces the entire head of the person in the target image with the head from a reference photo. Face, hairstyle, hair colour and skull silhouette all transfer; the target's body, wardrobe, pose, lighting and background stay as they were.

The request is two image URLs and an optional seed: image_url is the body being kept and reference_image_url supplies the head. There is no prompt, no mask and no strength control, and one image comes back per request.

Key features

Move a full character head into an existing plate

Head Swap changes more than facial identity: it is the right scope when the incoming character's hair, colour and head silhouette must travel with them. That makes it useful for character recasting, costume concepts and continuity treatments where the target hairstyle should not survive.

Treat the neck transition as the acceptance test

Choose source material with compatible camera angle, light direction and visible neck area. Review the hairline, ears, jaw, neck seam and shadow continuity at full size before accepting a result; these boundaries reveal whether the two assets truly belong together.

Use a controlled source pair

Start with a single clear subject in each image and avoid severe blur, occlusion or extreme profiles. When the target's own hair and silhouette are essential to the shot, choose Face Swap instead of forcing a full-head treatment.

Request parameters

Pricing

Prices are in credits, the same credits you use on the website (1 credit = $0.01). The hold is taken when the task is accepted and settled to the actual charge when it finishes; failed tasks are refunded.

Each task is rounded up to whole credits, so one run at the lowest tier costs 2 credits per image ($0.02).

For an exact number before you run, send the same body to POST /jobs/quote.

Use cases

Replace the whole head, not just the face

Use this endpoint when the incoming person's hairstyle, hair colour and head silhouette have to arrive with them. Review the hairline, ears and neck seam at full size before accepting the result; if the target's own hair belongs to the shot, Face Swap is the narrower tool.

Costume and cosplay plates

Put a character's own head and hairstyle onto a body wearing the costume you generated. The maid uniform, the pose and the cafe set stay exactly as they were, so the outfit work you produced survives the pass.

Any scene, with a consented likeness

Move a head you are authorised to use onto frames you produced yourself, whatever they show. The endpoint treats the material no differently — the consent requirement in the limits below is what governs, and it is not a formality.

Prompt guide & pro tips

Confirm you hold the rights to both people

Both images depict a person, and you need authorisation for the head you are moving and for the frame you are moving it into. Keep the release alongside the job record before any integration work starts.

Match the angles, then send the pair

image_url is the body being kept; reference_image_url supplies the head. A general editor would need an instruction such as: "Head swap: replace the entire head of the person in the first image — face, hairstyle and hair colour — with the head from the second image, keeping the first image's body, maid outfit, pose, cafe background, lighting and colour grade unchanged. Match the neck seam, skin tone and lighting direction so the result reads as one photograph." — here there is no prompt field at all.

Check the result before iterating

The neck seam is the failure mode: a target whose neck is hidden by a high collar, a scarf or hair, or whose head is at a sharply different angle from the reference, produces a visible join. Match the lighting direction and skin tone between the two sources, and prefer similar head angles. Both images want one clearly visible, reasonably frontal, well-lit head of a decent size; group shots give the endpoint no way to know which person you meant. If the target's own hairstyle needs to stay, use Face Swap instead — no parameter here will keep it. There is no prompt, no mask and no strength control, so a wrong result is fixed with a different input pair.

API quick start

Call the Head Swap API in three steps

1. Create an API key. Sign in to PopNow and create a key in the API console. Keys start with sk-popnow- and use the same credits as the website.
2. Send the request. POST /jobs/createTask with model popnow/head-swap-v1/edit and an input object that follows the parameter table. The response returns a task ID straight away.
3. Get the result. Poll GET /jobs/recordInfo with the task ID, or pass a callBackUrl and we post the result to it. Download the output links when the task succeeds.

# 1. Create the task. Keep the Idempotency-Key if you retry after a network error.
export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.popnow.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
  "model": "popnow/head-swap-v1/edit",
  "input": {
    "image_url": "https://media.popnow.ai/influencer/examples/marco.webp",
    "reference_image_url": "https://media.popnow.ai/influencer/examples/ava.webp"
  }
}'

# 2. Copy data.taskId from the response, then poll until state is succeeded, failed, canceled or expired.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

Replace the prompt and any links with your own. The API tab has the response, polling and callback reference.

Head Swap API questions

Other image APIs

• Face Swap Pro APIPrecise face swap that keeps natural skin textureFrom 24 credits per image
• Celebrity Look-Alike APIFind your celebrity look-alike from one portraitFrom 8 credits per image
• Face Swap Plus APIFace swap with automatic skin-tone matchingFrom 24 credits per image
• Face Swap APISwap just the face, keep hair, pose and backgroundFrom 2 credits per image

More about Head Swap

Try it

Head Swap AI Face Swap onlineCreate images with Head Swap in PopNow

Docs

Head Swap model ID and input schema in the API docsPopNow API quickstart: your first request in five minutesImage generation guide for the PopNow APIWebhooks: get Head Swap results without polling