{"uid":"cap_BmC9vu-b2iwn8O1-v34d5","slug":"agents-vimmerse-net-vimmerse-face-swap-f6743bf3","name":"Vimmerse Face Swap","description":"Swaps faces in a **target** image using one or more **reference** face images.\n\n- **`image_urls[0]`** — target image containing face(s) to replace  \n- **`image_urls[1:]`** — reference faces  \n- **`order_indices`** — optional mapping of target face indices (left-to-right from `0`)\n\n### Example\n\n```python\nimport requests\n\nurl = \"https://api.vimmerse.net/v2/image/face-swap\"\nheaders = {\n    \"X-Api-Key\": \"YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\",\n}\npayload = {\n    \"image_urls\": [\n        \"https://media.vimmerse.net/example/group_photo.png\",\n        \"https://media.vimmerse.net/example/face_a.png\",\n        \"https://media.vimmerse.net/example/face_b.png\",\n    ],\n    \"option\": \"NanoBananaFaceSwap\",\n    \"face_only_mode\": True,\n    \"multi_face_mode\": True,\n    \"order_indices\": [0, 1],\n}\n\nresponse = requests.post(url, headers=headers, json=payload, timeout=300)\nresponse.raise_for_status()\nprint(response.json()[\"results\"])\n```","url":"https://agents.vimmerse.net/v2/image/face-swap?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"FaceSwapRequest","required":["image_urls"],"properties":{"option":{"type":"string","title":"Face swap method","default":"NanoBananaFaceSwap","description":"Available values: `NanoBananaFaceSwap`, `SeedreamFaceSwap`, `MagicFaceSwap`, `EaselFaceSwap`, and `SegmindFaceSwap`."},"async_mode":{"type":"boolean","title":"Async Mode","default":false},"image_urls":{"type":"array","items":{"type":"string"},"title":"Image URLs","minItems":2,"description":"The first URL is the target image; the rest are human/face reference images."},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook URL"},"order_indices":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"title":"Order Indices","description":"Indices of faces in the target image to swap (left-to-right, starting at 0)."},"face_only_mode":{"type":"boolean","title":"Face swap only","default":true,"description":"When true, only the face is swapped (not the entire head)."},"multi_face_mode":{"type":"boolean","title":"Multi face swap mode","default":true}},"description":"Request body for POST /v2/image/face-swap. Content-Type: application/json."},"responseSchema":{"type":"object","title":"Response Face Swap Api V2 Image Face Swap Post","additionalProperties":true},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"unknown","displayCostAsset":"USD","priceDynamic":true,"priceHint":null,"priceStatus":"unknown_unparsed","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"unknown","summary":"price unknown","primary":{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_dT7Pe09-aC6qdE2_peHvm","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"unknown","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":"agents.vimmerse.net","brandSlug":"agents-vimmerse-net-x402","brandBaseUrl":"https://agents.vimmerse.net","brandDocsUrl":null,"whatItDoes":"Swaps faces in a target image using one or more reference face images, with support for multi-face and face-only modes.","exampleAgentPrompt":"Swap the faces in this group photo (https://media.vimmerse.net/example/group_photo.png) with two reference faces — use face_a.png for the first person on the left and face_b.png for the second person, using multi-face mode and face-only swap with the NanoBananaFaceSwap method.","exampleUseCases":[{"title":"Put user face on stock photo","prompt":"Take this stock photo at https://example.com/stock_headshot.png and swap the model's face with my reference photo at https://example.com/my_face.png — use face-only mode so only the face changes, not the whole head."},{"title":"Multi-person group photo face swap","prompt":"I have a group photo at https://example.com/team_photo.png with three people. Swap the first two faces (indices 0 and 1) using my reference images at https://example.com/person_a.png and https://example.com/person_b.png, with multi-face mode enabled."},{"title":"Creative portrait using SeedreamFaceSwap","prompt":"Swap the face in this artistic portrait at https://example.com/portrait.png with the face from https://example.com/reference_face.png using the SeedreamFaceSwap method — I want higher quality output for this one."}],"resultDescription":"A JSON object containing a 'results' field with the output face-swapped image URL(s) or image data. The response may also include status and metadata about the swap operation.","failureModes":["Image URL not accessible or returns 404 — endpoint cannot fetch source images","No face detected in target or reference image — swap cannot proceed","Reference face image too low quality or partially obscured — degraded swap quality","More order_indices specified than faces present in target image — index out of bounds error","Invalid or unsupported image format provided","API key missing or invalid — authentication error","Timeout if images are very large or server is under load","Invalid option value — must be one of NanoBananaFaceSwap, SeedreamFaceSwap, MagicFaceSwap, EaselFaceSwap, SegmindFaceSwap"],"whenToPreferThis":"Choose this endpoint when you need to replace specific faces in an existing image with reference faces from other images. It supports single and multi-face swaps, precise targeting via order_indices, and multiple swap engine options for quality/style tradeoffs. Prefer over general image editing when the task is explicitly face replacement rather than background replacement or style transfer.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-31T00:40:44.303Z","isFirstParty":false,"canonicalSlug":"agents-vimmerse-net-vimmerse-face-swap-f6743bf3"}