Guide

Compare files

Diff two images, PDFs or videos.

The compare operations diff two files of the same kind — a reference and a candidate — and produce a visual diff that highlights where they differ. Unlike most operations, these take two inputs: list the reference first, then the candidate.

Two inputs

Provide both files in the input array. The first entry is treated as the reference, the second as the candidate. Both inputs can be remote URLs, uploads, or any other supported source type — see Input sources.

compare-image

Compares two images pixel-by-pixel using a configurable metric and renders a visual diff where the highlighted regions mark the differences. Tune the comparison with method, threshold and diff_color.

Option Values Description
method ae, mae, ncc, psnr, rmse, ssim The comparison metric: absolute error, mean absolute error, normalized cross-correlation, peak signal-to-noise ratio, root mean squared error, or structural similarity.
threshold 0–100 Sensitivity. Differences below this threshold are ignored; higher values tolerate more variation before a pixel is flagged.
diff_color color name / hex The color used to highlight the differing regions in the produced diff image.

Example: compare two remote images

{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
    },
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "compare-image",
      "options": {
        "method": "ssim",
        "threshold": 5,
        "diff_color": "red"
      }
    }
  ]
}
curl -X POST https://api.api2convert.com/v2/jobs \
  -H "x-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d @compare-image.json

compare-pdf

Diffs two PDF documents page by page and renders the differences visually, making it easy to spot content or layout changes between two revisions of a PDF.

{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/document/pdf/example.pdf"
    },
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/document/pdf/example.pdf"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "compare-pdf",
      "options": {}
    }
  ]
}

compare-video

Performs a frame-by-frame diff of two videos, highlighting the frames and regions where the candidate differs from the reference.

{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/video/mp4/example_small.mp4"
    },
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/video/mp4/example.mp4"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "compare-video",
      "options": {}
    }
  ]
}
Both inputs should be the same format and, ideally, the same dimensions (and for video, the same frame rate). Comparing mismatched files can produce a diff dominated by alignment differences rather than real content changes.

Options reference

The live options below are pulled directly from the API. For the full list of supported source and target formats, see the format explorer.

Loading options…