How to use our faceswap endpoints

This page walks you through everything you need to know to generate images with our FaceSwap API, using both ready-made filters and self-prompting.

1. Overview

FaceSwap image generation always follows the same basic flow:

Choose how to generate the image
Ready-made filters → POST /v1/run/faceswap
Custom text prompts → POST /v2/run/self-prompt
Send a generation request and get back a job ID (id).
Check the job status using the status endpoint (e.g. POST /v2/status/{job_id}).
Retrieve the base64-encoded image from the status response.
Decode the base64 string into an image file and use it in your app.

This article explains each step in detail, focusing first on the FaceSwap filter flow and then on self-prompting.

2. Endpoint Reference

Purpose – Method – Path

List available FaceSwap filters → GET /v1/filters/
Generate image with a filter → POST /v1/run/faceswap
Generate image with self-prompting → POST /v2/run/self-prompt
Check job status / retrieve output → POST /v2/status/{job_id}

🔐 Authentication
All requests must include your API key (see your dashboard for the exact header/format used). Requests without a valid key will be rejected.

3. Workflow A – Using FaceSwap Filters

Use this workflow when you want to apply ready-to-use FaceSwap filters.

3.1. Step 1 – Get FaceSwap Filter IDs

Open the API documentation and navigate to GET /v1/filters/.
Expand the endpoint details.
On the right-hand side, click “Try it out”.
Click “Execute”.
The server responds with:
Example cURL
Requested URL
JSON list of filter IDs

Example JSON snippet:

[
  { "id": "12", "name": "Cyberpunk Neon" },
  { "id": "34", "name": "Vintage Portrait" }
]

Valid filter IDs in this example: 12, 34, …

3.2. Step 2 – Generate an Image with a Filter

Navigate to POST /v1/run/faceswap.
Expand the endpoint.
Click “Try it out”.
Set filter_id to the integer ID you noted earlier.
Adjust optional parameters (or leave defaults).
Click “Execute”.

The response includes:

{ "id": "job-id-123", "status": "QUEUED" }

📝 Important: Save the id (example: job-id-123).

3.3. Step 3 – Check Status & Retrieve the Generated Image

Navigate to POST /v2/status/{job_id}.
Expand the endpoint → Try it out.
Enter your returned job_id.
Click Execute.

If complete:

{
  "id": "job-id-123",
  "output": { "images": [ "some-base-64-image" ] },
  "status": "COMPLETED"
}

Key fields

status → QUEUED / RUNNING / COMPLETED / FAILED
output.images → base64 image array

3.3.1. Decode the Base64 Image

Copy output.images[0]
Decode via any base64 tool or library
Save or display the generated image

4. Workflow B – Using Self-Prompting

Use this workflow when generating images from custom text prompts.

4.1. Step 1 – Send a Self-Prompt Request

Navigate to POST /v2/run/self-prompt
Click Try it out
Provide your prompt (example):

{ "prompt": "A cinematic portrait of a person in neon city lights" }

Response:

{ "id": "job-id-456", "status": "QUEUED" }

Save the id.

4.2. Step 2 – Poll Job Status

Use POST /v2/status/{job_id}
When status = COMPLETED, retrieve output.images[0]
Decode base64 as explained in Step 3.3.1

5. Putting It All Together (Quick Recipe)

Pick method:
Filter-based → get filter IDs → /v1/run/faceswap
Self-prompt → /v2/run/self-prompt
Send generation request with payload + API key
Store returned id
Poll /v2/status/{job_id} until:
COMPLETED → use output.images[0]
FAILED → inspect and retry
Decode base64 → image file → use in your product

6. Troubleshooting & Tips

I never receive COMPLETED status

Make sure you're using the correct status endpoint version (/v2/status/{job_id})
Check you’re passing the exact id returned earlier

The image output array is empty

Confirm the job actually says COMPLETED
If RUNNING, keep polling
Review inputs — invalid inputs may cause empty outputs

Base64 decoding issues

Ensure you copied the full base64 string
Remove extra quotes or whitespace
Use standard base64 decoding