Skip to main content

Face Swap API replaces a face in a supplied photograph without a text prompt; the base version keeps the target hairstyle and scene and offers an optional seed.

From $0.013/image

Workbench

Input

Image editing
1/1

Drop files or media links, paste, or browse · 1 file · Max 10 MB · JPG · PNG · WEBP

  • 1
1 / 1 files
In the base Face Swap request, image_url is the composition that receives the new face, not the portrait supplying its identity. at least 1 characters
1/1

Drop files or media links, paste, or browse · 1 file · Max 10 MB · JPG · PNG · WEBP

  • 1
1 / 1 files
reference_image_url contributes the face for the base edit; match its light direction to the target to reduce visible joins. at least 1 characters
Seed
For the base model, an omitted seed or 0 requests a fresh random draw; reuse a nonzero seed for controlled comparisons, without expecting pixel-identical results. no lower than 0 · no higher than 2147483647
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
silver-bob-recastExample result

Related models and next tasks

Missing the model you need?

A strict three-field schema, one image back

The Face Swap edit API takes a target image in image_url and a face to transfer in reference_image_url, then returns one image with the facial features moved over. seed is the only other field the schema accepts, and anything else in the body fails validation. Each image field takes a public HTTPS URL, an uploaded file URI or an inline data URI.

Open the playground
A strict three-field schema, one image back
Required fields
image_url (the target) and reference_image_url (the face)
Optional field
seed, an integer from 0 to 2,147,483,647
How images are passed
Public HTTPS URL, uploaded file URI or inline data URI
Accepted formats
JPEG, PNG or WebP for either image field
Task deadline
1,800 seconds, after which the task expires
Billing
Per output image, one price tier, no variants to pick
Validation
Unknown fields stop a request before it becomes a taskThe schema names three fields and sets additionalProperties to false, so a key left over from another model's payload (a strength value, a prompt string) comes back as a 400 naming the field it objected to. Nothing is queued, and nothing is quietly dropped on the way through.
Seed
seed covers the full signed 32-bit rangeAny integer from 0 to 2,147,483,647 is accepted. Passing the same one twice over the same image pair holds the draw steady enough to compare two runs, which is what the field is for; it is not a promise that both images come back identical. Leaving it out draws randomly.
Deadline
1,800 seconds is the ceiling, not the expected waitEach task carries a deadline 1,800 seconds after it is accepted, reported on the task record as deadlineAt. A task that reaches it ends as expired rather than returning an image. Size the polling loop against that number instead of a guessed turnaround for one pair of photos.

What the Face Swap API does well

The whole request body is three keys

The whole request body is three keys

image_url and reference_image_url are required, seed is optional, and that is the complete list. There is no strength dial to calibrate and no region to paint, so the same request shape serves a studio portrait and a full-length frame, and a batch runner only has to vary two URLs per job.

Format choice is independent between the two images

Format choice is independent between the two images

image_url and reference_image_url each accept JPEG, PNG or WebP on their own, so a WebP target with a JPEG reference face is as valid as a matching pair, and neither file has to be converted before the call. How each one is passed is equally independent.

  • An image field takes a link, an upload or inline bytes

    A public HTTPS link needs no extra call. A file can also be uploaded to the platform first, using an upload ticket and a commit, then referenced by the URI that comes back. Small images can travel inline as a data URI, up to 1,048,576 decoded bytes and 8,192 pixels per side.

  • One task, one image

    A finished task exposes a single image asset from platform storage, and the schema has no count or batch field to ask for more. Ten pairs of photos means ten tasks, each with its own ID and poll state, which keeps a failure on one pair from holding up the other nine.

  • seed earns its place on reruns

    Leaving seed out, or sending 0, draws a fresh value on every call. Setting it matters when a later run over the same pair has to be checked against an earlier one, for instance after swapping in a better-lit reference photo. Single-shot calls can skip the field entirely.

  • Poll the task or let it call you back

    Every request is asynchronous: task creation answers with a task ID in the queued state. From there, poll the task until it settles, or pass callBackUrl on the create request and take terminal delivery there instead. That URL has to be public HTTPS, because the delivery carries signed result links.

Who Face Swap is for

  • A schema small enough to hardcode instead of templating

    Backend integration engineers

    A schema small enough to hardcode instead of templating

    With only image_url, reference_image_url and seed to populate, the request body does not need a template engine or a dynamic field list — three variables mapped directly into a JSON object cover every call this endpoint accepts.

  • Testing a look across shots that are already lit and framed

    E-commerce and catalog teams

    Testing a look across shots that are already lit and framed

    Existing product photography (garment fit, pose, backdrop) stays untouched in image_url while reference_image_url swaps in a different model's face, which avoids rebooking a shoot just to check how a listing reads with someone else on camera.

  • One face carried across frames generated elsewhere

    Character and avatar platforms

    One face carried across frames generated elsewhere

    A set of scenes produced by a separate image model can share one identity afterward by running the same reference_image_url against each frame in turn, one task per pair, with seed pinned when a rerun needs to match an earlier batch.

  • Publishing an image without the subject's real face

    Privacy and anonymization workflows

    Publishing an image without the subject's real face

    When a target photo can be published but the person's actual identity should not be, reference_image_url can point at a synthetic or cleared stand-in face instead of a second real person's likeness. The authorization rules in the FAQ below still govern both images.

How to call the Face Swap API

  1. Decide how each image reaches the endpoint

    image_url and reference_image_url are strings, so each one needs a public HTTPS link, a file URI from a platform upload, or a data URI carried inline in the request. JPEG, PNG and WebP are accepted in either field.

  2. Send only the fields the schema defines

    Build the body from image_url, reference_image_url and, if you need it, seed. Any other key fails validation because additionalProperties is false, so strip leftovers from another endpoint's payload before sending.

  3. Dry-run a new integration with a quote

    The quote endpoint runs the same input validation and admission checks as task creation without creating a task or reserving funds, and the signed quote it returns stays valid for five minutes. It is the quickest way to confirm a request body is shaped right.

  4. Submit, then poll or take the callback

    Send the request and keep the task ID it returns. Poll until the task reaches a terminal state, or register callBackUrl and wait for delivery. An Idempotency-Key makes a retry return the original task rather than creating a second one.

  5. Fetch the one output image

    A successful task exposes a single image asset served from platform storage. There is no count field, so more outputs means more tasks: one per target-and-reference pair, each polled and charged on its own.

Face Swap worked examples

  • A same-day product recast

    A retailer already has a fully lit product shot of one model and needs the identical shot to show a second, cleared model instead. image_url stays the original photograph and reference_image_url points at the second model's headshot; the task returns one image with the pose, garment and lighting untouched.

  • A batch of ten avatar frames sharing one identity

    Ten target frames generated separately by an image model each get the same reference_image_url in turn — ten tasks, one shared face. Pinning a single seed value across the batch keeps a rerun of any one frame comparable to its first pass.

  • A batch runner that survives a dropped connection

    Each pair goes out with an Idempotency-Key derived from the two source IDs. When a connection drops mid-submit and the runner retries, the key returns the original task instead of opening a second one, so a restarted batch does not pay twice for a pair it already sent.

Face Swap API questions

There is no prompt to write, so most of the integration work is inputs and plumbing. Decide early how images reach the endpoint: an HTTPS link needs no extra call, an upload needs a ticket and a commit, and a data URI has to stay under 1,048,576 decoded bytes. Put the first body through a quote before spending a real call on it, keep seed for reruns you plan to compare, and send an Idempotency-Key with every create.

Models in this series3

Image models2