Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xcoder-es/media-cleaner-pro/llms.txt

Use this file to discover all available pages before exploring further.

This page is the authoritative human-readable reference for every data type that appears in the MediaCleaner Pro REST API — request bodies, response envelopes, nested objects, and configuration records. All types are defined as Rust structs and enums in src/api/models.rs and packages/mc-core/src/domain.rs, and exposed through utoipa-generated OpenAPI annotations.
The machine-readable OpenAPI specification at GET /api/openapi.json is always the authoritative source of truth. If any description on this page conflicts with that spec, the spec takes precedence.

​
StartJobRequest

StartJobRequest is the JSON body sent with POST /api/start to launch a new deduplication pipeline job. All three fields are present in every request; hamming_threshold may be omitted (sent as null) to fall back to the pipeline’s configured default.
​
source_dir
string
required
Absolute or relative path to the directory containing the images to scan. If an empty string is provided, the server retains the value from the previous job configuration.
​
dest_dir
string
required
Absolute or relative path to the output directory where deduplicated images will be written. If an empty string is provided, the server retains the value from the previous job configuration.
​
hamming_threshold
integer | null
Perceptual similarity threshold used when comparing dHash fingerprints. Accepts an integer in the range 0–64, where 0 means only bit-for-bit identical hashes match and 64 treats every image as a duplicate. When null, the pipeline uses the value configured in .env (default 4).
Example
{
  "source_dir": "/home/alice/Photos/2024",
  "dest_dir": "/home/alice/Photos/Cleaned",
  "hamming_threshold": 8
}

​
ControlRequest

ControlRequest is the JSON body sent with POST /api/control to manage a running or paused job. The single action field determines the operation applied to the current pipeline.
​
action
string
required
The control action to perform. Must be one of:
ValueEffect
"pause"Suspends processing after the current file completes
"resume"Continues a paused pipeline from where it stopped
"cancel"Aborts the pipeline; any files already written to dest_dir are kept
Example — pause
{
  "action": "pause"
}
Example — resume
{
  "action": "resume"
}
Example — cancel
{
  "action": "cancel"
}

​
JobResponse

JobResponse is the JSON object returned by POST /api/start. It confirms the job was accepted and provides the initial pipeline snapshot, which will have every stage in "pending" state and zeroed-out statistics at the moment of creation.
​
job_id
string
UUID v4 string that uniquely identifies this job for the lifetime of the server process. Use this value to correlate log entries and to distinguish concurrent runs.
​
status
string
Always "started" when returned from POST /api/start. This field distinguishes the start response from polling responses.
​
stages
array of StageInfo
Initial state for each pipeline stage, listed in execution order. See StageInfo for field definitions.
​
stats
ProcessingStats
Initial processing statistics snapshot. All counters are zero and rate fields are 0.0 at job start. See ProcessingStats for field definitions.
​
is_running
boolean
true if the pipeline is actively processing images.
​
is_paused
boolean
true if the pipeline has been suspended via POST /api/control with "pause".
Example
{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "started",
  "stages": [
    {
      "name": "Exact Duplicate Removal",
      "description": "Removes files with identical SHA-256 checksums",
      "status": "pending",
      "progress": 0.0,
      "processed": 0,
      "total": 0,
      "started_at": null,
      "completed_at": null,
      "error": null
    }
  ],
  "stats": {
    "current_file": null,
    "current_dhash": null,
    "unique_count": 0,
    "duplicate_count": 0,
    "error_count": 0,
    "speed": 0.0,
    "eta_seconds": 0,
    "memory_mb": 0,
    "cpu_percent": 0.0
  },
  "is_running": true,
  "is_paused": false
}

​
StateResponse

StateResponse is returned by GET /api/status and is also the payload type streamed as Server-Sent Events by GET /api/progress. It represents a complete point-in-time snapshot of the pipeline.
The log_messages array is populated only by GET /api/status. The SSE stream from GET /api/progress always returns an empty array for that field — use GET /api/logs to retrieve log history separately.
​
stages
array of StageInfo
Current state of every pipeline stage. See StageInfo for the full field breakdown.
​
stats
ProcessingStats
Live processing statistics. See ProcessingStats for the full field breakdown.
​
is_running
boolean
true when the pipeline is actively processing images.
​
is_paused
boolean
true when the job has been suspended mid-run.
​
log_messages
array of LogMessage
Recent log entries. Populated only by GET /api/status; always an empty array in SSE events from GET /api/progress. See LogMessage for field definitions.
Example
{
  "stages": [
    {
      "name": "Exact Duplicate Removal",
      "description": "Removes files with identical SHA-256 checksums",
      "status": "completed",
      "progress": 100.0,
      "processed": 1840,
      "total": 1840,
      "started_at": "2024-08-15T10:22:01Z",
      "completed_at": "2024-08-15T10:22:19Z",
      "error": null
    },
    {
      "name": "Perceptual Duplicate Removal",
      "description": "Groups visually similar images using dHash comparison",
      "status": "running",
      "progress": 43.2,
      "processed": 795,
      "total": 1840,
      "started_at": "2024-08-15T10:22:19Z",
      "completed_at": null,
      "error": null
    }
  ],
  "stats": {
    "current_file": "IMG_4872.jpg",
    "current_dhash": "A3F0C1B28D7E6504",
    "unique_count": 1612,
    "duplicate_count": 183,
    "error_count": 2,
    "speed": 44.7,
    "eta_seconds": 23,
    "memory_mb": 312,
    "cpu_percent": 67.4
  },
  "is_running": true,
  "is_paused": false,
  "log_messages": [
    {
      "timestamp": "2024-08-15T10:22:01Z",
      "level": "INFO",
      "stage": "system",
      "message": "Job f47ac10b started"
    }
  ]
}

​
StageInfo

StageInfo is the per-stage progress record nested inside both JobResponse and StateResponse. Each entry in the stages array corresponds to one pipeline stage and is updated in place as the job runs. The status field is a serialised StageStatus enum rendered in lowercase.
​
name
string
Display name of the stage, e.g. "Exact Duplicate Removal" or "AI Classification". Names are stable across API versions and safe to use as identifiers in client UI.
​
description
string
One-sentence description of what the stage does, intended for display in tooltips or progress UIs.
​
status
string
Current lifecycle state of the stage. Serialised as a lowercase string from the StageStatus enum:
ValueMeaning
"pending"Stage has not yet begun
"running"Stage is actively processing
"completed"Stage finished successfully
"failed"Stage aborted due to an error; see error field
"skipped"Stage was bypassed (e.g. disabled in PipelineConfig)
​
progress
float
Completion percentage as a floating-point value between 0.0 (not started) and 100.0 (fully complete).
​
processed
integer
Count of images that have been handled by this stage so far.
​
total
integer
Total number of images this stage will process. May be 0 before the stage has been initialised.
​
started_at
string | null
ISO 8601 UTC timestamp (chrono::DateTime<Utc>) recording when this stage transitioned to "running". null if the stage has not yet started.
​
completed_at
string | null
ISO 8601 UTC timestamp recording when this stage transitioned to "completed", "failed", or "skipped". null if the stage is still pending or running.
​
error
string | null
Human-readable error message populated when status is "failed". null for all other status values.
Example — running stage
{
  "name": "Perceptual Duplicate Removal",
  "description": "Groups visually similar images using dHash comparison",
  "status": "running",
  "progress": 67.5,
  "processed": 1242,
  "total": 1840,
  "started_at": "2024-08-15T10:22:19Z",
  "completed_at": null,
  "error": null
}
Example — failed stage
{
  "name": "AI Classification",
  "description": "Classifies images into content categories",
  "status": "failed",
  "progress": 12.0,
  "processed": 221,
  "total": 1840,
  "started_at": "2024-08-15T10:24:05Z",
  "completed_at": "2024-08-15T10:24:11Z",
  "error": "Model weights file not found: /usr/share/mc/models/classifier.onnx"
}

​
ProcessingStats

ProcessingStats is the live statistics object nested inside both JobResponse and StateResponse. It is updated continuously as the pipeline processes each file and provides real-time visibility into throughput, resource usage, and deduplication results.
​
current_file
string | null
Filename (not full path) of the image currently being processed. null when no file is being actively handled — either between stages, while paused, or after completion.
​
current_dhash
string | null
Hex-encoded 64-bit difference hash (dHash) of the current file, formatted as a 16-character uppercase hex string (e.g. "A3F0C1B28D7E6504"). null when current_file is null or when the hash has not yet been computed for the current file.
​
unique_count
integer
Cumulative count of images determined to be unique across all stages processed so far.
​
duplicate_count
integer
Cumulative count of images flagged as duplicates across all stages processed so far.
​
error_count
integer
Cumulative count of files that could not be processed due to read errors, unsupported formats, or other failures.
​
speed
float
Current processing throughput expressed as files per second, calculated as a rolling average.
​
eta_seconds
integer
Estimated number of seconds remaining until the pipeline finishes all stages, derived from speed and the remaining file count.
​
memory_mb
integer
Current resident memory usage of the MediaCleaner Pro process in megabytes.
​
cpu_percent
float
Current CPU utilisation of the process as a percentage in the range 0.0–100.0. On multi-core systems this value can reflect aggregate utilisation across all cores used by the Tokio runtime.
Example
{
  "current_file": "DSC_0047.jpg",
  "current_dhash": "A3F0C1B28D7E6504",
  "unique_count": 1612,
  "duplicate_count": 183,
  "error_count": 2,
  "speed": 44.7,
  "eta_seconds": 23,
  "memory_mb": 312,
  "cpu_percent": 67.4
}

​
LogMessage

LogMessage represents a single structured log entry. It appears in two places: in the log_messages array returned by GET /api/status, and as the individual records returned by GET /api/logs. The SSE stream at GET /api/progress always emits an empty log_messages array — poll /api/logs for history.
​
timestamp
string
ISO 8601 RFC 3339 UTC timestamp (e.g. "2024-08-15T10:22:01Z") recording when the event was emitted by the pipeline.
​
level
string
Log severity level. One of:
ValueMeaning
"INFO"Normal operational events (stage transitions, file counts)
"WARN"Non-fatal issues that may affect output quality
"ERROR"Failures that caused a file or stage to be skipped
​
stage
string
Name of the pipeline stage that emitted this message. Uses "system" for lifecycle events that are not attributable to a specific stage, such as job start, pause, resume, and cancellation.
​
message
string
Human-readable log entry text. Intended for display in log viewers and debugging output; not guaranteed to be machine-parseable.
Example
[
  {
    "timestamp": "2024-08-15T10:22:01Z",
    "level": "INFO",
    "stage": "system",
    "message": "Job f47ac10b-58cc-4372-a567-0e02b2c3d479 started"
  },
  {
    "timestamp": "2024-08-15T10:22:19Z",
    "level": "INFO",
    "stage": "Exact Duplicate Removal",
    "message": "Stage completed: 45 exact duplicates removed from 1840 files"
  },
  {
    "timestamp": "2024-08-15T10:23:04Z",
    "level": "WARN",
    "stage": "Perceptual Duplicate Removal",
    "message": "Skipping corrupt file: PANO_20240512.jpg (invalid JPEG header)"
  }
]

​
PipelineConfig

PipelineConfig controls the behaviour of every stage in the deduplication pipeline. Default values are applied at server startup from environment variables (.env file). Individual jobs can override hamming_threshold via StartJobRequest; the remaining fields require a server restart to change.
PipelineConfig is not directly exposed through a dedicated API endpoint — it is an internal domain type. The effective configuration for a job is embedded in the Job record and reflected in pipeline behaviour. Set these values in your .env file before starting the server.
​
hamming_threshold
integer
Hamming distance threshold for dHash comparison. Default: 4. Range: 0–64. Lower values require hashes to be nearly identical; higher values match more aggressively. Override per-job via StartJobRequest.hamming_threshold.
​
min_width
integer
Minimum image width in pixels below which a file is filtered out before any deduplication stages run. Default: 100.
​
min_height
integer
Minimum image height in pixels for the same pre-filter. Default: 100.
​
detect_icons
boolean
When true, the classification stage identifies and flags icon-sized images (typically very small, square, with transparency). Default: true.
​
detect_thumbnails
boolean
When true, the classification stage identifies and flags thumbnail images. Default: true.
​
detect_screenshots
boolean
When true, the classification stage identifies and flags screenshots based on aspect ratio and content heuristics. Default: true.
​
detect_wallpapers
boolean
When true, the classification stage identifies and flags wallpaper-resolution images. Default: true.
​
detect_documents
boolean
When true, the classification stage identifies and flags document scans and page images. Default: true.
​
classification_enabled
boolean
Master switch for the AI classification stage. When false, the entire classification stage is skipped and all detect_* flags are ignored. Default: true.
​
quality_ranking_enabled
boolean
Controls whether the quality ranking stage runs. When true, duplicate candidates are ranked by sharpness, exposure, and resolution to select the best copy for retention. Default: true.
Default configuration
{
  "hamming_threshold": 4,
  "min_width": 100,
  "min_height": 100,
  "detect_icons": true,
  "detect_thumbnails": true,
  "detect_screenshots": true,
  "detect_wallpapers": true,
  "detect_documents": true,
  "classification_enabled": true,
  "quality_ranking_enabled": true
}
Aggressive deduplication — loose threshold, classification disabled
{
  "hamming_threshold": 16,
  "min_width": 50,
  "min_height": 50,
  "detect_icons": false,
  "detect_thumbnails": true,
  "detect_screenshots": false,
  "detect_wallpapers": false,
  "detect_documents": false,
  "classification_enabled": false,
  "quality_ranking_enabled": true
}

Build docs developers (and LLMs) love

Get started for freeTalk to us