Skip to content

API > Integrate API into your product

How to use our faceswap endpoints

This page documents FaceSwap v6 (latest). v5 follows the same process — see the Swagger UI for v5-specific paths.

All requests require authentication. Include your API key in the Header.

Workflow

Every FaceSwap generation follows three steps:

  1. Submit a generation request → receive a job ID
  2. Poll the status endpoint → receive a base64-encoded image
  3. Decode base64 → use the image in your product

Step 1: Generate an Image

POST /v6/run/face_swap

Parameters

Parameter Type Required Description
base64 string yes Base64-encoded image or public URL
gender int yes 0 = Male, 1 = Female, 2 = Boy, 3 = Girl, 4 = Group
filter_id int or string yes Integer filter ID from the catalog, or UUID (paid/self-created/alias)
ratio string no "portrait" (1200x1800, default), "landscape" (1800x1200), "square" (1280x1280)
quality_mode string no "v6.1" (default, higher quality) or "v6" (faster). Leave at default unless you have a specific reason. Only applies to integer filter IDs; UUID filters use their built-in workflow.

Example Request

{
  "base64": "<base64_encoded_image>",
  "gender": 0,
  "filter_id": 12,
  "ratio": "portrait"
}

Example Response

{
  "id": "job-abc-123",
  "status": "IN_QUEUE"
}

Save the id — you need it for the next step.

Notes

  • Group mode (gender=4) only supports integer filter IDs. More group options are under construction.
  • Cost: 2 credit per request.

Step 2: Check Status & Retrieve Image

POST /v6/status/{job_id}

POST to this endpoint with your job ID syncronus await until the status is COMPLETED or FAILED.

Response

{
  "id": "job-abc-123",
  "status": "COMPLETED",
  "output": {
    "images": ["<base64_encoded_image>"]
  }
}

Status Values

Status Meaning
COMPLETED Done — image available in output.images
FAILED Generation failed — check your inputs

Step 3: Decode Base64

Take the string from output.images[0] and decode it with any standard base64 library. The result is a PNG image.

Quick Recipe

  1. POST /v6/run/face_swap with base64, gender, filter_id → save returned id
  2. POST /v6/status/{id} → POST wait until status = COMPLETED
  3. Read output.images[0] → base64 decode → image file

FaceSwap v5

Same workflow. You can use the same faceswap filter IDs, but visual results will differ between v5 and v6.

Purpose Endpoint
Generate POST /v5/run/face_swap
Status POST /v5/status/{job_id}

See Swagger UI for v5 parameter details.

Error Reference

Error Code Meaning
FILTER_BLOCKED 422 Filter not available for the selected mode (single/group)
FILTER_NOT_FOUND 422 Integer filter ID does not exist
WORKFLOW_FETCH_FAILED 422 UUID filter workflow could not be loaded
INVALID_QUALITY_MODE 422 quality_mode must be "v6" or "v6.1"
INVALID_IMAGE 400 Image input is empty or invalid

Troubleshooting

I never receive COMPLETED status

  • Verify you are using the correct status endpoint for your model.
  • Check that you are passing the exact id returned by the generation endpoint.

Base64 decoding issues

  • Make sure you copied the full base64 string without extra quotes or whitespace.