Skip to main content

Video Character Swap API

Uncensored — This model declares no content filter. SpicyAPI forwards the request without adding a platform content scan; legal and consent duties remain with the customer.Browse every model at this filtering level
spicyapi/character-swap-v1/video-analyze

Video Character Swap analysis is the first of two calls: it tracks every person in a 5 to 30 second MP4 and returns one numbered preview still per person. Pick 480p or 720p; the swap call must use the same value.

From $0.08/request
Run model

Workbench

Input

Subject detection
1/1

Drop a video here, or browse · 1 file · Max 90 MB · MP4

  • 1
1 / 1 files
The clip to analyse, 5 to 30 seconds. Keep this exact URL: the swap call has to run on the same video, and it is copied over automatically when you leave it out there. It has to be a direct link to the video file itself — a page that plays the video hands us HTML instead, the input check reads no duration from it, and the call fails with the charge refunded. Uploading the file is the most reliable route. at least 1 characters
Tracking resolution. The swap call must use the same value, so choose the resolution you want the finished clip to have. It does not change what this call costs.
Safety checkerOff

SpicyAPI does not run a safety checker on this model. Your prompt and media go to the model as written, and the model itself decides what comes back.

Checking your account before enabling submission and pricing.

Output

Ready for a new run
night-market-three-peopleExample result
Video upscaling
Video editing
Video translation

Related models and next tasks

Missing the model you need?

Tell us what to add and where you would use it. Requests go to the people who decide what gets onboarded next.

Track everyone in the clip, then replace only the ones you name

Video Character Swap splits the job in two. The first call analyses a clip of 5 to 30 seconds and returns one numbered preview still per person it found, in a fixed order. The second call takes that analysis, the positions you picked and one to three reference photos for each, and returns the clip with those people replaced. Everyone you leave out is untouched, the camera move survives, and the original audio comes back with it.

Open the playground
Call one
video-analyze: video_url plus a tracking resolution, 480p or 720p
Call two
video-edit: analysis_task_id, swap_targets, and the same resolution
Targets per call
1 to 10 swap_targets, each with 1 to 3 reference photos
Analysis shelf life
24 hours; one analysis can feed several swap calls
Audio
The source track is carried through untouched
Content policy
Uncensored: no platform content filter on either call
Why two calls
You see who was found before you spend on the swapThe analysis hands back a preview still per person. Picking by position off those stills is cheap and unambiguous, which is what lets the expensive call replace exactly the people you meant.
Scope
The whole person changes, not just the faceEach target's appearance comes from the reference photos you supply. Their blocking, the camera move and everyone else in the frame stay where they were.
Cost shape
Analysis is flat, the swap is by the clipThe analysis costs the same whatever the clip's length; the swap is billed by duration in five-second blocks, so a shorter cut is the lever that moves the bill.

What the Video Character Swap API does well

  • Numbered targets instead of guesswork

    The analysis returns the detected people in a fixed order, and swap_targets addresses them by object_index starting at zero. There is no prompt to describe who you mean and no mask to draw: position zero is the first preview still that came back, every time.

  • Replace some people, keep the rest

    Only the positions listed in swap_targets are touched. In a three-person scene you can replace the one on the left and leave the other two exactly as shot, which is what makes this usable on footage where only one performer needs to change.

  • One to three references per person

    Each target takes an image_urls array of one to three photographs of the same replacement. More than one angle gives the model more to work from; all of them should show the same person, because the array describes one identity, not a choice between several.

  • One analysis, several swaps

    The tracking result stays usable for 24 hours, so the same analysis_task_id can feed one swap call after another. Trying a different reference photo, or swapping a different subset of the people found, does not mean paying to track the clip again.

  • The take survives the replacement

    Camera movement, framing, the other people in the shot and the original audio all come back unchanged. What changes is who is standing in the positions you named, which is why this fits footage you have already edited.

  • seed compares runs, it does not lock them

    seed takes any integer from 0 to 2,147,483,647, and passing the same one keeps two calls on the same draw so a change of reference photo is the only thing that differs between them. An identical output is still not promised, and 0 or an omitted seed asks for a fresh draw.

Who Video Character Swap is for

  • Localisation and versioning

    One master cut, a different cast per market

    The clip is analysed once and the analysis is reused for each market's approved performer. Because the swap only touches the positions you name, the edit, the timing and the sound design stay identical across every version.

  • Post-production

    Replace a performer without reshooting the scene

    When one person in an otherwise finished shot has to change, the alternative is a reshoot or a rotoscope. Here the take stays and the identity moves: the camera move, the blocking and the other performers are carried through untouched.

  • Synthetic talent

    Put a recurring character into real footage

    Nothing in the schema asks whether the reference photographs are of a real person, so a consistent generated character can be dropped into a photographed scene and inherit its lighting, wardrobe and motion.

  • Pipeline engineers

    A two-step call with a cheap decision point in the middle

    The analysis is a flat-rate call whose output is small and inspectable, so a pipeline can put a human or a rule between the two steps: look at who was found, decide, then pay for the swap only when the targets are right.

How to call the Video Character Swap API

  1. Send the clip to the analysis call

    video_url takes a public HTTPS address, a spicy:// file URI from the platform's upload flow, or a data URI for a small file. Pick the tracking resolution now: whatever you choose here has to be repeated in the swap call.

  2. Read the preview stills in order

    The analysis returns one still per person it found. Their order is the numbering: the first still is object_index 0, the second is 1, and so on. That order is what the next call addresses, so keep it with the task ID.

  3. Name the positions you want replaced

    Build swap_targets with one entry per person you are changing: object_index for who, image_urls for who they become. Positions you leave out of the array are not touched, so there is no way to accidentally replace the rest of the cast.

  4. Repeat the resolution and submit

    Pass the same resolution as the analysis and the analysis_task_id it returned. video_url is optional in this call: leave it out and the source from the analysis is used. Save the returned task ID and poll until it settles.

  5. Reuse the analysis while it is warm

    The tracking result lives for 24 hours. If the first reference photo did not land, send a second swap call against the same analysis_task_id instead of re-analysing, and fix a seed if you want the two attempts to differ only by the reference.

Video Character Swap worked examples

  • Three people in frame, one of them replaced

    The analysis comes back with three stills. swap_targets carries a single entry, object_index 1, with two photographs of the replacement from slightly different angles. The other two performers are absent from the array and come back exactly as shot, which is the whole point of addressing targets by position.

  • One analysis, four candidate faces

    A casting pass sends four swap calls against the same analysis_task_id, one per candidate, with seed pinned to the same integer. The tracking was paid for once, the four results differ only by the reference photographs, and the comparison answers the question that was actually asked.

  • A cut down to length before anything is sent

    A 40-second rush is trimmed to the 8 seconds that matter before it goes to the analysis. The clip is now inside the 5 to 30 second window the tracker wants, and the swap is billed on 8 seconds instead of 40 — the trim is the cheapest optimisation available on this endpoint.

Video Character Swap API questions

Two things decide the result, and neither is a parameter. The first is the clip: the tracker wants each person reasonably large and reasonably continuous in frame, so trim to the section that matters and avoid long stretches where a subject is fully hidden. The second is the reference photographs, which carry the whole appearance of the replacement, wardrobe included — match their lighting to the footage rather than picking the sharpest portrait, and put whatever look you want the finished clip to have straight into the photo, since there is no prompt to ask for it separately. Read the preview stills before spending on the swap; if the person you wanted is not among them, no choice of reference photo will fix it.