PixTrace.

Documentation

Analyze →

On this page

Need help?

Our team replies within 24h.

contact@pixtrace.io →

API Documentation

Submit an image — PixTrace runs 10 intelligence modules in parallel and returns a structured JSON report.

Quickstart

Submit an image with your API key. The API returns a job_id — poll for the result every few seconds.

Step 1 — Submit

curl -X POST https://pixtrace.io/api/v1/analyze \
  -H "Authorization: Bearer pxt_live_YOUR_KEY" \
  -F "image=@photo.jpg"

Step 2 — Poll

curl https://pixtrace.io/api/v1/analyze/{job_id} \
  -H "Authorization: Bearer pxt_live_YOUR_KEY"

Response (completed)

{
  "status": "completed",
  "progress": 100,
  "result": {
    "services_results": {
      "image_osint": {
        "result": {
          "geoclip":       { "best": { "lat": 45.98, "lon": 7.71, "pays": "Switzerland", ... } },
          "vlm_synthese":  { "resume_executif": "...", "score_confiance_global": 82 },
          "exif":          { "raw": { "EXIF:Make": "Apple", "EXIF:Model": "iPhone 15 Pro", ... } },
          "landmark":      { "labels": [...], "dominant_colors": [...] },
          "reverse_search":{ "google_lens": { "resultats": [...] }, "yandex": { "resultats": [...] } },
          "shadowfinder":  { "candidates": [...] },
          "osm":           { "display_name": "Zermatt, Wallis, Switzerland", "address": {...} },
          "pdq":           { "hash_pdq": "..." }
        }
      }
    }
  }
}

Authentication

Pass your API key as a Bearer token in the Authorization header of every request.

Authorization: Bearer pxt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

pxt_live_…Live key

Production — credits are billed

pxt_test_…Test key

Sandbox — no data, always free

Manage your keys in Dashboard → API Keys.

Endpoints

POST/v1/analyze

Submit one image for analysis.

{ "image_url": "https://example.com/photo.jpg" }

GET/v1/analyze/{job_id}

Poll an analysis job until it completes.

GET/v1/credits

Return current credit balance.

GET/v1/history

Return a paginated list of past analyses.

Submit an image

POST/api/v1/analyze

Submit an image file (multipart/form-data) or a URL (application/json). Requires a live API key.

# File upload
-H "Authorization: Bearer pxt_live_YOUR_KEY"
-F "image=@photo.jpg"

# URL submission
-H "Authorization: Bearer pxt_live_YOUR_KEY"
-H "Content-Type: application/json"
-d '{"image_url": "https://example.com/photo.jpg"}'

Returns: { "job_id": "uuid", "status": "pending", "message": "..." }

Polling the result

GET/api/v1/analyze/{job_id}

Poll every 3 seconds until status is "completed" or "failed".

pending

Job queued, not yet started

processing

Modules running in parallel

completed

All modules finished — result available

failed

An error occurred — check error field

Average processing time: ~54 seconds. Set a timeout of 4–5 minutes for safety.

Response structure

Module data lives at result.services_results.image_osint.result.

result.services_results.image_osint.result.geoclipGeolocation predictions

result.services_results.image_osint.result.vlm_syntheseAI narrative synthesis

result.services_results.image_osint.result.landmarkVision labels + colors

result.services_results.image_osint.result.reverse_searchReverse image search

result.services_results.image_osint.result.exifCamera EXIF metadata

result.services_results.image_osint.result.shadowfinderShadow candidates

result.services_results.image_osint.result.osmAddress (OSM)

result.services_results.image_osint.result.pdqPerceptual hash

Modules

Module	Name	Description
`geoclip`	AI geolocation	Predicts lat/lon from visual cues. Returns best prediction + top candidates with probability scores.
`vlm_synthese`	VLM synthesis	LLM-powered narrative: executive summary, image content, authenticity verdict, geolocation reasoning.
`landmark`	Google Vision	Labels, web entities, reverse image matches, dominant colors, OCR text, face detection.
`reverse_search`	Reverse search	Google Lens + Yandex results: matching pages, similar images, thumbnails.
`exif`	EXIF metadata	Full camera metadata: make, model, lens, GPS, ISO, aperture, shutter, software.
`shadowfinder`	Shadow analysis	Bellingcat methodology — sun geometry candidates from shadow direction and elevation angle.
`pdq`	PDQ hash	Perceptual hash for near-duplicate detection across large image databases.
`osm`	OpenStreetMap	Reverse geocoding of the best predicted lat/lon to a human-readable address.
`suncalc`	Sun calculator	Solar azimuth and elevation at the estimated capture time and location.
`forensics`soon	Forensics (coming soon)	Manipulation detection — JPEG artifacts, clone stamping, metadata inconsistencies.

Error codes

400bad_requestMissing or invalid image / image_url field

401unauthorizedMissing or invalid API key

402no_creditsNo credits remaining

404not_foundJob not found, or it does not belong to your account

413payload_too_largeImage exceeds 20 MB limit

429rate_limitedToo many requests — slow down

500server_errorInternal error — retry after a short delay