Check an image

Send an image by URLCopy Anchor Link

curl -X POST "https://realpng.com/api/v1/audit" \
  -H "X-API-Key: $REALPNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://images.example.com/beach.jpg"
  }'

{
  "verdict": "ai",
  "score": 91,
  "decided_by": "pixels",
  "lanes": {
    "pixels": {
      "verdict": "ai",
      "score": 91
    },
    "watermark": {
      "verdict": "none",
      "score": 3
    },
    "provenance": {
      "verdict": "nothing",
      "issuer": null
    }
  },
  "media": "image"
}

realpng fetches the URL itself, so it must be a public http or https address. Redirects are followed. A private address, a host that is slow to answer or a URL that answers with an error comes back as a 400, listed in errors.

Each call sends exactly one of image_url, image_base64 or image_upload_id. It needs an API key and spends credits from your plan.

Send a small file as base64Copy Anchor Link

curl -X POST "https://realpng.com/api/v1/audit" \
  -H "X-API-Key: $REALPNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAF0lEQVR4nGM4UREQteASg0bUtGd3TgAALTYG/9S1V3UAAAAASUVORK5CYII="
  }'

Send the bytes as plain base64 or as a data URL. The data: prefix is removed before decoding.

Base64 travels inside the request, so its size limit is lower than for a URL or an upload. Send anything bigger as an upload.

Send an uploaded fileCopy Anchor Link

curl -X POST "https://realpng.com/api/v1/audit" \
  -H "X-API-Key: $REALPNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_upload_id": "5d1f7a3c-2b8e-4f6a-9c0d-8e3b1a7f4c62"
  }'

Any file on disk can go through POST /uploads first. You PUT the bytes to a one-time URL, then send its id as image_upload_id. Upload a local file covers the full flow, including what a retry needs.

Read the verdictCopy Anchor Link

A 200 carries these fields. Agents get the same body from the audit_image tool. See MCP tools.

VerdictCopy Anchor Link

ScoreCopy Anchor Link

The score orders images by how strongly they read as AI, from 0 to 100. Use it to sort or rank, such as reviewing the highest first.

Branch on verdict, not on the score. The cut points between real, uncertain and ai are internal and may change, so a threshold you pick today can drift. When proof decides, the score is pinned to a set value whatever the pixels said, as the next table shows.

What decided itCopy Anchor Link

A watermark decides even when the pixels are unsure:

{
  "verdict": "ai",
  "score": 99,
  "decided_by": "watermark",
  "lanes": {
    "pixels": { "verdict": "uncertain", "score": 38 },
    "watermark": { "verdict": "present", "score": 96 },
    "provenance": { "verdict": "nothing", "issuer": null }
  }
}

Read the lanesCopy Anchor Link

Each lane keeps its own vocabulary, so the watermark lane reads present or none, never ai or real.

PixelsCopy Anchor Link

A panel of trained pixel detectors reads the image. The lane reads pixels only and knows nothing about who made the file.

It averages the detectors on several overlapping crops and takes the median crop, so a caption or sticker over one part does not decide the verdict. An image too small to crop is read whole.

score is 0 to 100, or null.

What it cannot see. Detection is measured on original files. An ordinary JPEG re-encode makes it markedly weaker, so screenshots, social media copies and recompressed files are caught less often. Generators the panel was not tuned on are caught less reliably.

WatermarkCopy Anchor Link

The lane looks for SynthID, the invisible watermark Google embeds in images from its generators.

score is the watermark model's own reading, 0 to 100, or null.

What it cannot see. Any watermark other than SynthID. An image from a generator that does not embed SynthID reads none.

ProvenanceCopy Anchor Link

The lane reads the file's metadata, not its pixels. It uses no model and always answers, so it has no unavailable value.

An ai_label raises the score but never decides on its own. Anyone can add or remove unsigned metadata, so only a signature counts as proof. Stray bytes that happen to spell a generator's name are ignored.

What it cannot see. Most re-encodes, screenshots and social platforms strip metadata, so nothing is common and says nothing either way. A missing signature is not evidence of AI.

Handle an unavailable verdictCopy Anchor Link

The verdict is unavailable when no lane found proof and the pixel lane could not read the image. With a watermark present or a signed manifest, the verdict is still decided even if the pixel lane is unavailable.

{
  "verdict": "unavailable",
  "score": null,
  "decided_by": "pixels",
  "lanes": {
    "pixels": { "verdict": "unavailable", "score": null },
    "watermark": { "verdict": "none", "score": 4 },
    "provenance": { "verdict": "nothing", "issuer": null }
  }
}

It is a normal 200, not an error, and it is charged as a completed check. Retry the same image later. The full engine report names the detector that dropped out.

The watermark lane can also answer unavailable on its own. The verdict then comes from the other lanes as usual.

An engine that is still warming up is different. It answers 503 before any lane runs, as described in errors.

Get the full engine reportCopy Anchor Link

curl -X POST "https://realpng.com/api/v1/audit?detail=full" \
  -H "X-API-Key: $REALPNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://images.example.com/beach.jpg"
  }'

Add detail=full to the query to get detail beside the usual fields. It holds the raw engine report: each detector's own reading, the evidence per lane, the decoded image's size and format, and how long the engine took (engine_ms).

Know what a check cannot tell youCopy Anchor Link

• Only watermark, provenance and conflict in decided_by rest on proof. A pixels or weighed verdict is a statistical reading and can be wrong.
• A real verdict from the pixels means the image does not read as AI. It does not prove a camera took it.
• Each lane has blind spots of its own. Recompressed copies weaken the pixels, the watermark lane sees SynthID only, and most platforms strip metadata. Read the lanes has the detail.

Handle errorsCopy Anchor Link

Every error comes back as JSON with a stable code. Errors lists each one with its status and fix.

Next stepsCopy Anchor Link