Video Face Swap

Face-Swap.co API Tutorial

End-to-end guide to generate face-swapped videos with simple HTTP calls.

1) Get an API key

Visit /api and start a free trial or buy credits. Your API key will be emailed to you. Keep it secret (don’t commit it to GitHub).

Python: load API key
import os
API_KEY = os.getenv("FACE_SWAP_API_KEY", "YOUR_API_KEY")  # set in your shell or .env

2) Get a public URL for your image & video

The API needs directly downloadable URLs (HTTP 200 without auth). Test your links in an incognito window.

  • Hugging Face Hub: upload and use /resolve/<branch>/file.ext URLs.
  • S3 / R2: make objects public or generate a pre‑signed URL.
  • Dropbox: change ?dl=0?dl=1 for direct download.
  • GitHub: use the raw.githubusercontent.com link.
Optional: generate an S3 pre‑signed URL (Python)
# Requires: pip install boto3
import boto3
from botocore.client import Config

s3 = boto3.client("s3", config=Config(signature_version="s3v4"))
url = s3.generate_presigned_url(
    ClientMethod="get_object",
    Params={"Bucket": "YOUR_BUCKET", "Key": "path/to/face.jpg"},
    ExpiresIn=3600
)
print(url)  # use as input_image_url

3) Start a generation

Allowed durations (seconds): 4 (trial), 60, 120, 180.

Python
import os, requests

API_KEY = os.getenv("FACE_SWAP_API_KEY", "YOUR_API_KEY")
IMAGE_URL = "https://tinyurl.com/elonmusk-faceswap"
VIDEO_URL = "https://tinyurl.com/ironman-faceswap"

payload = {
    "key": API_KEY,
    "input_image_url": IMAGE_URL,
    "input_video_url": VIDEO_URL,
    "duration": 120,       # 4 | 60 | 120 | 180
    "gender": "all"       # optional: all | female | male
}

r = requests.post("https://www.face-swap.co/api/generate", json=payload, timeout=60)
r.raise_for_status()
resp = r.json()
print(resp)
job_id = resp.get("job_id")  # Save this for polling

4) Check status

Poll until the job is completed or failed; wait 3–5s between requests.

Python
import time, requests

assert job_id, "job_id missing from generate response"
status_url = f"https://www.face-swap.co/api/status/{job_id}"

while True:
    s = requests.get(status_url, timeout=30)
    s.raise_for_status()
    data = s.json()
    print(data)

    state = str(data.get("status", "")).lower()
    if state in {"succeeded", "completed", "done"}:
        print("✅ Finished.")
        break
    if state in {"failed", "error"}:
        raise SystemExit("❌ Job failed: " + str(data))
    time.sleep(5)

5) Check remaining credits

Endpoint: GET /api/credits/{API_KEY}

Python
import os, requests
API_KEY = os.getenv("FACE_SWAP_API_KEY", "YOUR_API_KEY")

r = requests.get(f"https://www.face-swap.co/api/credits/{API_KEY}", timeout=30)
r.raise_for_status()
print(r.json())

6) List recent jobs

Endpoint: GET /api/jobs/{API_KEY}

Python
import os, requests
API_KEY = os.getenv("FACE_SWAP_API_KEY", "YOUR_API_KEY")

r = requests.get(f"https://www.face-swap.co/api/jobs/{API_KEY}", timeout=30)
r.raise_for_status()
print(r.json())

Security & troubleshooting

  • Keep your API key out of client-side JS and public repos.
  • If generation fails, verify your URLs return HTTP 200 without auth; avoid Google Drive viewer links.
  • Use duration=4 while testing to conserve credits.
  • Poll every 3–5 seconds to be kind to the API.

Questions? Email face.swapper.app@gmail.com