Batch face anonymization tool using PiktID APIs. Given a folder of user profiles, anonymize each user's profile image and consistently apply that new identity across all their other images.

Local folders in, local folders out. No cloud storage dependencies.

• Python 3.10+
• uv (recommended) or pip
• PiktID API credentials (access token + refresh token)

Copy .env.example to .env and fill in your tokens:

cp .env.example .env

PIKTID_ACCESS_TOKEN=your_access_token_here
PIKTID_REFRESH_TOKEN=your_refresh_token_here

# Anonymize mode (default) — generates new random faces
uv run python -m batch_anonymize ./input ./output -v

# Swap mode — uses the original profile face as the identity
uv run python -m batch_anonymize ./input ./output --mode swap -v

# Or use the script entrypoint
uv run batch-anonymize ./input ./output -v

If you use mise for tool management:

mise use [email protected]
mise use uv@latest
uv run python -m batch_anonymize ./input ./output -v

pip install -r requirements.txt
python -m batch_anonymize ./input ./output -v

input/
  user_001/
    profile/
      avatar.jpg          ← face to anonymize (or use as swap source)
    images/
      photo1.jpg          ← same identity will be applied here
      photo2.jpg
  user_002/
    profile/
      avatar.jpg
    images/
      photo1.jpg

Each user folder must contain a profile/ subdirectory with at least one image. The images/ subdirectory is optional.

output/
  user_001/
    profile/
      avatar.jpg          ← anonymized face
    images/
      photo1.jpg          ← consistent identity swapped in
      photo2.jpg
  manifest.json           ← processing state for resumability

1. Uploads the profile image and detects faces
2. Generates a random new face for face 0
3. Saves the generated face as a named identity
4. Replaces the face and downloads the output
5. For each related image: generates a consistent face using the saved identity

1. Uploads the profile face as a named identity (profile image copied to output as-is)
2. For each related image: generates a consistent face using that identity

python -m batch_anonymize <input_dir> <output_dir> [options]

Options:
  --mode {anonymize,swap}          Processing mode (default: anonymize)
  --workers N                      Parallel workers (default: 4)
  --seed N                         Generation seed
  --hair                           Include hair in generation (default: face only)
  --strength {strong,medium,light} Anonymization level (default: strong)
  --prompt-strength F              Override profile prompt strength (0-1)
  --consistent-prompt-strength F   Override related images prompt strength (0-1)
  --no-resume                      Ignore existing manifest, start fresh
  -v, --verbose                    Debug logging

Use --prompt-strength and --consistent-prompt-strength to override individual values from the preset.

Processing state is tracked in output/manifest.json. If the process is interrupted, re-running the same command will skip already-completed users and images. Use --no-resume to force a fresh start.