Face swap
A SEPARATE endpoint from /v1/videos —
not reachable through it. Replaces the face throughout an existing video with a source face photo. See the
Face swap guide for the full model list and
a worked example.
POST/v1/face-swap
Requires explicit consent on the source face — a request without source_face_consent: true is rejected before any pricing or upstream call.
Parameters
modelstringRequired. No default and no auto-router — pin segmind/hyperswap-video-faceswap, the only candidate today.video_urlstringRequired. Public https:// URL to the target video whose face gets replaced. Output duration matches this file's own probed length.face_image_urlstringRequired. Public https:// URL to the source face photo.source_face_consentbooleanRequired, must be true. Affirms you have the right to use the source face photo. Missing or false returns 400 consent_required.resolution / height / widthstring / integerOptional output-size hints, same precedence as /v1/videos.provider / failoverobjectOptional. Same provider-preference shape as /v1/videos — there is exactly one candidate model today, so there's nothing to fail over to yet.Example response (202, job just created)
{
"id": "fal:...",
"status": "queued",
"data": null,
"error": null
}Billed reserve-then-settle — the reservation is sized from a pre-call estimate, the real charge settles from the provider's own completed-job invoice. Polling is free.
GET/v1/face-swap/{id}
Identical job-id scheme and settlement logic as GET /v1/videos/{id} (a face-swap job is still a video job once submitted).
Parameters
idstring (path)The id returned by POST /v1/face-swap.Example response (status: "completed")
{
"id": "fal:...",
"status": "completed",
"data": [{ "url": "https://..." }],
"error": null
}status is one of queued → in_progress → completed/failed. On failure, error carries the provider's message and data is null.