Introduction
The video-analyze stage builds the head selection list for Video Head Swap without editing the footage. Send a 5–30 second MP4 and choose 480p or 720p for the subsequent replacement. In the Video Head Swap previews, object_index counts from zero: the first preview identifies target 0 and the next identifies target 1. Match a portrait to its preview rather than assuming the order follows where people stand.
| Field | Value |
|---|---|
| Input | Text |
| Output | Video |
| Calls | Two: video-analyze, then video-edit |
| Clip length | 5 to 30 seconds |
| Resolution | 480p or 720p, identical in both calls |
| References | One to three photos per head, up to 10 heads per request |
| Authorisation | Only likenesses you are authorised to process |
Key features & highlights
You choose who changes
A head replacement carries the reference hairstyle and head outline into the shot. Choose this scope when changing facial features alone would leave the wrong hair on the character; review the neck transition and the moving hair together.
Request parameters
| Parameter | Required | Description |
|---|---|---|
video_url | Yes | The video-analyze stage builds the head selection list for Video Head Swap without editing the footage. at least 1 characters |
resolution | No | Choose 480p or 720p for head analysis and reuse that choice for the edited clip. |
Pricing
$0.08 / analysis
Video Head Swap has two charges: a flat analysis fee and a separate duration charge for replacement at the selected resolution. Editing uses full 5-second blocks of source footage, so 6 seconds is billed as 10 seconds.
Use cases
Recast a shot that already works
Use Video Head Swap to change a performer’s head after the costume, camera move and setting have been chosen. Inspect turns and neck edges across the whole clip before accepting the recast.
Any subject matter, with a consented performer
Video Head Swap is listed as unrestricted for NSFW video on SpicyAPI; the platform adds no separate content filter to this head replacement workflow. That classification does not remove the adult-only and informed-consent requirements.
One person through a generated series
For a series with the same authorized character, analyze each shot separately and reuse that character’s head references. Preview indices belong to their own analysis and must not be carried from one shot into another.
Crowds where only one person changes
In a shared shot, use the head previews to select the intended performer and leave the other indices out of swap_targets. This gives Video Head Swap a specific replacement list instead of treating everyone as a target.
Prompt guide & pro tips
Confirm you hold the rights to every head involved
Use Video Head Swap only for adult likenesses and footage you are authorized to edit. Obtain informed consent for the intended context; a publicly accessible portrait does not grant permission to impersonate or defame its subject.
Analyse first, then read the preview order
In the Video Head Swap previews,
object_indexcounts from zero: the first preview identifies target 0 and the next identifies target 1. Match a portrait to its preview rather than assuming the order follows where people stand.Keep the video and the resolution identical
Keep the analyzed clip and its resolution together throughout Video Head Swap. Omitting
video_urlduring editing reuses the analyzed video; an explicit URL must match, and resolution must also remain unchanged.
video-analyze — Video Head Swap
The video-analyze stage builds the head selection list for Video Head Swap without editing the footage. Send a 5–30 second MP4 and choose 480p or 720p for the subsequent replacement.
In the Video Head Swap previews, object_index counts from zero: the first preview identifies target 0 and the next identifies target 1. Match a portrait to its preview rather than assuming the order follows where people stand.
Head tracking can lose a subject behind an obstruction, in heavy motion blur or when the head is too small to identify. Video Head Swap can address only heads returned by analysis; an absent preview cannot be added manually.
Keep the analyzed clip and its resolution together throughout Video Head Swap. Omitting video_url during editing reuses the analyzed video; an explicit URL must match, and resolution must also remain unchanged.
A Video Head Swap analysis can be reused for 24 hours to try different head references against that clip. Once it expires, analyze the source again before requesting another replacement.
Give Video Head Swap a direct MP4 file URL or upload the clip. A watch page returns HTML instead of footage and cannot supply a usable duration; preserve the analyzed file rather than trimming or re-encoding it between stages.
Use Video Head Swap only for adult likenesses and footage you are authorized to edit. Obtain informed consent for the intended context; a publicly accessible portrait does not grant permission to impersonate or defame its subject.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/head-swap-video-v1/video-analyze",
"input": {
"resolution": "720p",
"video_url": "https://example.com/reference.mp4"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.


