{"openapi":"3.1.0","info":{"title":"FaceSwapAI Face Swap API","version":"1.0.0","description":"Production REST API for asynchronous image, video, GIF and multiple-face swaps. Every generation requires a verified account, an API key, sufficient credits or an eligible photo trial, and explicit consent.","termsOfService":"https://faceswapai.com/terms","contact":{"name":"FaceSwapAI support","url":"https://faceswapai.com/contact"},"license":{"name":"FaceSwapAI API Terms","identifier":"Proprietary"}},"servers":[{"url":"https://faceswapai.com","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Face swap","description":"Submit and poll face-swap generation tasks."},{"name":"Tasks","description":"List tasks owned by the authenticated account."}],"paths":{"/api/v1/face-swap/image":{"post":{"operationId":"createImageFaceSwap","summary":"Create an image face swap","tags":["Face swap"],"description":"13 credits per paid result. An eligible account may receive one watermarked trial result that visibly includes the full account email.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["sourceImage","targetImage","consent"],"properties":{"sourceImage":{"type":"string","format":"binary","description":"Image containing the face to apply. Maximum 30 MB."},"targetImage":{"type":"string","format":"binary","description":"Image containing the face to replace. Maximum 30 MB."},"consent":{"type":"boolean","enum":[true],"description":"Must be true. Confirms permission to use every uploaded face."},"faceRestoreVisibility":{"type":"number","default":1,"minimum":0,"maximum":1},"restoreVisibility":{"type":"number","default":1,"minimum":0,"maximum":1}}}}}},"responses":{"200":{"description":"Task accepted for asynchronous processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAccepted"}}}},"400":{"description":"Invalid form data, consent or media metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The account email must be verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request or one of its files exceeds the published limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Authenticated request limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The task could not be queued. Reserved credits are refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The requested processing provider is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getimagefaceswapStatus","summary":"Get image face swap task status","tags":["Face swap"],"description":"Poll until status is COMPLETED or FAILED. Result media URLs are temporary and follow the published retention policy.","security":[{"bearerAuth":[]}],"parameters":[{"name":"taskId","in":"query","required":true,"description":"Task ID returned by the matching POST request.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current task state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Missing taskId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Task not found for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Authenticated request limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/face-swap/video":{"post":{"operationId":"createVideoFaceSwap","summary":"Create a video face swap","tags":["Face swap"],"description":"Costs max(5, ceil(duration in seconds)) credits. Videos may be at most 300 seconds and 100 MB.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["sourceImage","targetVideo","consent"],"properties":{"sourceImage":{"type":"string","format":"binary","description":"Image containing the face to apply. Maximum 30 MB."},"targetVideo":{"type":"string","format":"binary","description":"MP4, MOV, WebM or AVI target video. Maximum 100 MB and 300 seconds."},"consent":{"type":"boolean","enum":[true],"description":"Must be true. Confirms permission to use every uploaded face."},"faceRestoreVisibility":{"type":"number","default":0.85,"minimum":0,"maximum":1},"restoreVisibility":{"type":"number","default":0.7,"minimum":0,"maximum":1}}}}}},"responses":{"200":{"description":"Task accepted for asynchronous processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAccepted"}}}},"400":{"description":"Invalid form data, consent or media metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The account email must be verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request or one of its files exceeds the published limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Authenticated request limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The task could not be queued. Reserved credits are refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The requested processing provider is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getvideofaceswapStatus","summary":"Get video face swap task status","tags":["Face swap"],"description":"Poll until status is COMPLETED or FAILED. Result media URLs are temporary and follow the published retention policy.","security":[{"bearerAuth":[]}],"parameters":[{"name":"taskId","in":"query","required":true,"description":"Task ID returned by the matching POST request.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current task state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Missing taskId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Task not found for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Authenticated request limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/face-swap/gif":{"post":{"operationId":"createGifFaceSwap","summary":"Create a GIF face swap","tags":["Face swap"],"description":"Costs max(10, ceil(duration), ceil(frames/10)) credits. GIFs may be at most 30 seconds and 30 MB.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["sourceImage","targetGif","consent"],"properties":{"sourceImage":{"type":"string","format":"binary","description":"Image containing the face to apply. Maximum 30 MB."},"targetGif":{"type":"string","format":"binary","description":"GIF target. Maximum 30 MB and 30 seconds."},"consent":{"type":"boolean","enum":[true],"description":"Must be true. Confirms permission to use every uploaded face."},"faceRestoreVisibility":{"type":"number","default":0.85,"minimum":0,"maximum":1},"restoreVisibility":{"type":"number","default":0.7,"minimum":0,"maximum":1}}}}}},"responses":{"200":{"description":"Task accepted for asynchronous processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAccepted"}}}},"400":{"description":"Invalid form data, consent or media metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The account email must be verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request or one of its files exceeds the published limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Authenticated request limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The task could not be queued. Reserved credits are refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The requested processing provider is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getGIFfaceswapStatus","summary":"Get GIF face swap task status","tags":["Face swap"],"description":"Poll until status is COMPLETED or FAILED. Result media URLs are temporary and follow the published retention policy.","security":[{"bearerAuth":[]}],"parameters":[{"name":"taskId","in":"query","required":true,"description":"Task ID returned by the matching POST request.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current task state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Missing taskId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Task not found for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Authenticated request limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/face-swap/multiple":{"post":{"operationId":"createMultipleFaceSwap","summary":"Create a multiple-face image swap","tags":["Face swap"],"description":"13 credits per task for one to 10 selected faces. Use the public detector or your own boxes to populate faceBox0 through faceBox9.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["sourceImage","targetFace0","consent"],"properties":{"sourceImage":{"type":"string","format":"binary","description":"Group image containing the faces to replace. Maximum 15 MB."},"consent":{"type":"boolean","enum":[true],"description":"Must be true. Confirms permission to use every uploaded face."},"targetFace0":{"type":"string","format":"binary","description":"Replacement image for selected face 1. Maximum 15 MB."},"faceBox0":{"type":"string","description":"Optional JSON box for selected face 1: {\"x\":0,\"y\":0,\"width\":100,\"height\":100}."},"targetFace1":{"type":"string","format":"binary","description":"Replacement image for selected face 2. Maximum 15 MB."},"faceBox1":{"type":"string","description":"Optional JSON box for selected face 2: {\"x\":0,\"y\":0,\"width\":100,\"height\":100}."},"targetFace2":{"type":"string","format":"binary","description":"Replacement image for selected face 3. Maximum 15 MB."},"faceBox2":{"type":"string","description":"Optional JSON box for selected face 3: {\"x\":0,\"y\":0,\"width\":100,\"height\":100}."},"targetFace3":{"type":"string","format":"binary","description":"Replacement image for selected face 4. Maximum 15 MB."},"faceBox3":{"type":"string","description":"Optional JSON box for selected face 4: {\"x\":0,\"y\":0,\"width\":100,\"height\":100}."},"targetFace4":{"type":"string","format":"binary","description":"Replacement image for selected face 5. Maximum 15 MB."},"faceBox4":{"type":"string","description":"Optional JSON box for selected face 5: {\"x\":0,\"y\":0,\"width\":100,\"height\":100}."},"targetFace5":{"type":"string","format":"binary","description":"Replacement image for selected face 6. Maximum 15 MB."},"faceBox5":{"type":"string","description":"Optional JSON box for selected face 6: {\"x\":0,\"y\":0,\"width\":100,\"height\":100}."},"targetFace6":{"type":"string","format":"binary","description":"Replacement image for selected face 7. Maximum 15 MB."},"faceBox6":{"type":"string","description":"Optional JSON box for selected face 7: {\"x\":0,\"y\":0,\"width\":100,\"height\":100}."},"targetFace7":{"type":"string","format":"binary","description":"Replacement image for selected face 8. Maximum 15 MB."},"faceBox7":{"type":"string","description":"Optional JSON box for selected face 8: {\"x\":0,\"y\":0,\"width\":100,\"height\":100}."},"targetFace8":{"type":"string","format":"binary","description":"Replacement image for selected face 9. Maximum 15 MB."},"faceBox8":{"type":"string","description":"Optional JSON box for selected face 9: {\"x\":0,\"y\":0,\"width\":100,\"height\":100}."},"targetFace9":{"type":"string","format":"binary","description":"Replacement image for selected face 10. Maximum 15 MB."},"faceBox9":{"type":"string","description":"Optional JSON box for selected face 10: {\"x\":0,\"y\":0,\"width\":100,\"height\":100}."}}}}}},"responses":{"200":{"description":"Task accepted for asynchronous processing.","content":{"application/json":{"schema":{"type":"object","required":["code","data"],"properties":{"code":{"type":"integer","const":200},"data":{"$ref":"#/components/schemas/TaskAccepted"}}}}}},"400":{"description":"Invalid form data, consent or media metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The account email must be verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request or one of its files exceeds the published limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Authenticated request limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The task could not be queued. Reserved credits are refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The requested processing provider is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getmultiplefaceswapStatus","summary":"Get multiple-face swap task status","tags":["Face swap"],"description":"Poll until status is COMPLETED or FAILED. Result media URLs are temporary and follow the published retention policy.","security":[{"bearerAuth":[]}],"parameters":[{"name":"taskId","in":"query","required":true,"description":"Task ID returned by the matching POST request.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current task state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Missing taskId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Task not found for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Authenticated request limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tasks":{"get":{"operationId":"listFaceSwapTasks","summary":"List account tasks","tags":["Tasks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/TaskStatus"}},{"name":"taskType","in":"query","schema":{"type":"string","enum":["IMAGE_SWAP","VIDEO_SWAP","GIF_FACE_SWAP","MULTI_FACE_SWAP"]}}],"responses":{"200":{"description":"Paginated task history.","content":{"application/json":{"schema":{"type":"object","required":["tasks","total","page","pageSize","totalPages"],"properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Authenticated request limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"FaceSwapAI API key","description":"Create a key in the FaceSwapAI API key manager. Keep it on your server and send it as Authorization: Bearer YOUR_API_KEY."}},"schemas":{"TaskStatus":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED","CANCELLED"]},"TaskAccepted":{"type":"object","required":["taskId"],"properties":{"taskId":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/TaskStatus"},"credits":{"type":"integer","description":"Remaining account credits after reservation."},"requiredCredits":{"type":"integer"}}},"Task":{"type":"object","required":["id","taskType","status"],"properties":{"id":{"type":"string","format":"uuid"},"taskType":{"type":"string","enum":["IMAGE_SWAP","VIDEO_SWAP","GIF_FACE_SWAP","MULTI_FACE_SWAP"]},"status":{"$ref":"#/components/schemas/TaskStatus"},"costCredits":{"type":"integer"},"result":{"type":["object","null"],"properties":{"url":{"type":"string","description":"Temporary result URL when completed."},"watermarked":{"type":"boolean","description":"True for an eligible free photo trial."},"error":{"type":"string","description":"Actionable public error when failed."}},"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}},"additionalProperties":true},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"required":{"type":"integer"},"available":{"type":"integer"}},"additionalProperties":true}}},"externalDocs":{"description":"Localized FaceSwapAI API guide and code examples","url":"https://faceswapai.com/face-swap-api"}}