Combining Visual Diff and AI Analysis: What Changed vs Why It Matters

v3/compare answers "did this page change, and by how much." It does not answer "does this change matter, and to whom." A 6% mismatch could mean a broken layout, or it could mean a rotating testimonial did its normal rotation. The diff image and the mismatch percentage alone don't tell the two apart — someone still has to look.

Chaining a compare call with an analyze call on the same capture gets you both signals without adding a second, separate integration: a precise measurement of what changed, and an AI-generated read on what the after-state actually contains.

Two Real Calls, Not One Merged Feature

This is not a special combined endpoint — it is two ordinary API calls run back to back, each already documented on its own:

1. POST /api/v3/compare — get the mismatch percentage and diff image between two states.
2. POST /api/v3/analyze — capture the after state again (or reuse the same URL) with enableSummary and/or enableQuality to get an AI-generated read on that page's content and quality.

# Step 1: measure the visual change
curl --request POST \
  --url https://api.prod.ss.snapshot-site.com/api/v3/compare \
  --header 'Content-Type: application/json' \
  --header 'x-snapshotsiteapi-key: YOUR_API_KEY' \
  --data '{
    "before": {"url": "https://example.com/pricing", "width": 1440, "fullSize": true, "hideCookie": true},
    "after": {"url": "https://staging.example.com/pricing", "width": 1440, "fullSize": true, "hideCookie": true},
    "threshold": 0.1
  }'

# Step 2: get an AI read on the "after" state
curl --request POST \
  --url https://api.prod.ss.snapshot-site.com/api/v3/analyze \
  --header 'Content-Type: application/json' \
  --header 'x-snapshotsiteapi-key: YOUR_API_KEY' \
  --data '{
    "url": "https://staging.example.com/pricing",
    "format": "png",
    "width": 1440,
    "fullSize": true,
    "enableSummary": true,
    "enableQuality": true
  }'

Why Run Both Instead of Just One

• Compare alone tells you a pricing page changed by 14%, but not whether that's a redesign, a broken CSS bundle, or new promotional banner.
• Analyze alone, run on a schedule without a comparison step, gives you a snapshot-in-time summary but no signal about when something actually changed versus when it's always looked that way.
• Both together gives you a trigger (the mismatch crossed your threshold) and a first-pass explanation (the AI summary of what the after-state now contains) in the same review, instead of a reviewer having to open both images and guess.

A Practical Trigger Pattern

Rather than running the analyze call on every single comparison — which adds cost and latency for changes nobody needs explained — gate it behind the compare result:

1. Run v3/compare on your normal schedule or CI trigger.
2. If mismatchPercentage is below your noise floor (see Tuning the threshold Parameter), stop — nothing worth explaining happened.
3. If it's above threshold, follow up with v3/analyze on the after state and attach both the diff image and the AI summary to the alert or review ticket.

This keeps the AI call reserved for the changes that actually crossed your bar for "worth a human looking at," rather than running on every check.

Where This Fits

This pattern slots naturally into workflows that already run one half of it — visual uptime monitoring and CI-gated visual regression checks both already call compare on a trigger; adding the analyze step on top is a small addition to an existing pipeline, not a new one.

Chaining two simple, well-documented calls gets a result that neither one produces alone, and Snapshot Site prices both endpoints the same way whether you call them separately or as a pair.