Fewer questions.
More creativity.

Choose your installation.

Spoofys is self-hosted software for a single administrator. There is no public account signup on this site. Running your own copy and signing in to an existing installation are separate paths.

Your first file

Open the studio and sign in with your installation’s account. If the studio has never been configured, the first screen lets you create the administrator account; your operator may require a setup token.

In the media library, choose “Upload media”. You can select multiple files. Imports use the existing resumable upload service; progress and errors are shown in the import window.

Review. Then run.

1. Select one or more files in the library.
2. Open the photo or video metadata editor and set the supported fields. Cleanup, dates, coordinates and variants each have their own options.
3. Preview the changes and read the warnings for each file.
4. Create the batch. Follow the queue and processing progress in “Batch Jobs”.
5. Download a version or an archive of completed results. If some files fail, review the errors and retry those files.

The preview shows proposed changes. It does not guarantee that encoding will succeed. Original files are preserved.

On an installation with on-demand processing, keep the studio open to track and advance your imports and batches. If you leave the studio, remaining items wait until you return or until the next scheduled run, if one is configured.

Your settings, ready to reuse.

Presets save your processing options. Device profiles group customizable identity fields. You can review candidates extracted from reference media before saving a profile.

These templates do not certify the device, date or location of capture. They do not constitute proof of provenance.

What each format supports.

The listed metadata capabilities cover JPEG, HEIC, PNG, WebP, TIFF, AVIF, MP4 and MOV. Each container has its limits: check the available fields and warnings in the studio.

GIF and WebM have conversion options, without ExifTool metadata writing. HEIC decoding depends on the installation, and HEIC encoding is not enabled. Video conversions depend on FFmpeg and its codecs.

Conversion and watermark removal re-encode media. Metadata-only processing preserves the encoded media when the format allows it. Default removal uses a rectangular area. Depending on the installation’s configuration, AI image inpainting uses either the included local LaMa engine, started on demand, or an IOPaint service configured by the operator. The studio shows whether it is available.

Your studio, connected.

Jump to the REST API example or MCP bridge setup. Replace example server URLs with your installation’s origin; access requires an account and token from that installation.

Create a token on the studio’s API screen. Grant only the permissions you need: read, or read and write. The token is shown only once.

Start with a read. Then preview.

Keep tokens in your local environment or your client’s secure configuration. Never put them in browser code or commit them to a repository.

curl 'https://spoofys.si/api/library?limit=10' \
  -H "Authorization: Bearer $SPOOFYS_TOKEN"

Requests use your browser session or a Bearer authorization header. The OpenAPI specification is available after you sign in.

Send library asset IDs and processing options to POST /api/preview to inspect every variant. Use POST /api/batches/estimate to check output count, estimated storage and preflight errors. Reuse the returned seed when submitting the same plan to POST /api/batches. Add an Idempotency-Key header when creating a batch; reuse that key only when retrying the same submission. A valid plan does not guarantee runtime encoding will succeed.

For resumable REST uploads, compute SHA-256 of the whole source file before initialization. Send the digest as expectedSha256 and sha256:<digest> as sourceFingerprint; send that fingerprint in the Upload-Fingerprint header on subsequent upload operations. Inspect the authenticated OpenAPI contract for local and cloud transfer steps.

In on-demand mode, API clients with write permission can call POST /api/processing/run and wait for the response to execute a bounded processing cycle. Then check the batch status; several cycles may be needed. Without this call, processing resumes according to the configured schedule.

Connect your assistant with MCP.

The MCP server uses stdio to expose the existing API. Configure METADATA_STUDIO_URL and METADATA_STUDIO_TOKEN locally, then run npm run --silent mcp. The tools cover the library, profiles, capabilities, previews, processing, authorized imports and download links.

{
  "mcpServers": {
    "spoofys": {
      "command": "node",
      "args": [
        "--import",
        "tsx",
        "C:/path/to/spoofys/server/mcp.ts"
      ],
      "cwd": "C:/path/to/spoofys",
      "env": {
        "METADATA_STUDIO_URL": "https://spoofys.si",
        "METADATA_STUDIO_TOKEN": "YOUR_LOCAL_API_TOKEN"
      }
    }
  }
}

Obtain the project package and install its dependencies first. Replace both paths with your local checkout and supply your own token using your client’s secure configuration. This starts a local stdio process that connects to the remote studio; https://spoofys.si/mcp is not an MCP endpoint.

Ask your assistant to inspect capabilities and preview every variant before submitting a batch. The bridge accepts up to 100 source assets, 10 variants and 500 requested outputs per batch; server limits can be lower. Reuse the preview or estimate seed for reproducible assignment. In on-demand mode, call processing_run after creating a job, then check jobs_get.

upload_bytes accepts caller-supplied base64 media up to 128 KiB; it cannot read arbitrary paths on your computer. Use the resumable REST API for larger local files, or an operator-allowed URL import. For pending cloud imports, call processing_run, then upload_get. Download links require an authorized session or Bearer header; output file bytes are downloaded separately.

Remote API origins require HTTPS. HTTP is accepted only for loopback development. Run connection_check from your MCP client, or node --import tsx server/mcp.ts --diagnose from the installed checkout with your URL and token configured. A successful diagnostic verifies stdio initialization and an authenticated API read; it does not verify write permission or processing codecs.

Connect what happens next.

Register an endpoint in the studio’s Webhooks screen for batch.completed, batch.partial, batch.failed and batch.cancelled. The operator must allowlist the destination host. Version 2 events include the batch ID, state and total/completed/failed/cancelled counts, so your receiver can handle each outcome.

Verify the x-metadata-signature header against the raw request body and your webhook secret: HMAC-SHA256 of timestamp + "." + rawBody. Check timestamp freshness and deduplicate using the stable x-metadata-delivery header. Failed deliveries are retried up to five attempts.

In version 2, a completed event means all items completed; mixed successful and unsuccessful results emit a partial event. Subscribe to partial and cancelled events explicitly. Older queued events retain their original payloads during an upgrade, so receivers should check the schema version and retrieve the batch when needed.

Recover administrator access.

If you forgot the administrator password, contact the installation’s operator. There is no public password-reset endpoint. Check the operator details for this installation.

The operator uses the local npm run recover command’s issue and complete steps with private code and password files. The one-time code expires after 15 minutes. Recovery revokes existing sessions and API tokens; sign in again and replace integration tokens afterward.

Follow the package’s docs/ACCOUNT-RECOVERY.md instructions on the server. Never paste passwords, recovery codes or tokens into a public page or support conversation.

A workspace on your infrastructure.

First obtain and extract the project package. Installation requires Node.js 24 or later, FFmpeg and ffprobe on your PATH. ExifTool is included as a project dependency. Linux and macOS also require Perl. Run the commands below from the project folder. On Windows PowerShell, use npm.cmd in place of npm.

The studio starts at http://127.0.0.1:4310 by default. Keep the data directory between updates. Open http://127.0.0.1:4310/app to create your administrator account while the server is only accessible locally. The repository includes guides for Docker, PostgreSQL and Supabase, along with backup procedures.

This version uses a single administrator workspace. It has no built-in subscription or payment system.