PhotoCheck API

API reference

Four endpoints, one request shape, one response shape. Base URL https://photocheckapi.com/api/v1. The OpenAPI 3.1 spec describes the same thing for code generators.

Quickstart

Send a photo to POST /api/v1/analyze with your key in an Authorization: Bearer header. The JSON response holds an AI-generation score, every face found, and the file's metadata. Without a key you get 5 calls a day per IP to try it.

bash
curl https://photocheckapi.com/api/v1/analyze \
  -H "Authorization: Bearer $PHOTOCHECK_API_KEY" \
  -F image=@photo.jpg

Quickstarts: cURL, JavaScript (Node.js), Python, PHP, Go, Ruby, Java, C# (.NET), Rust.

Authentication

Send the key as Authorization: Bearer pc_live_…, or as X-API-Key: pc_live_… if your client makes that easier. Keys come from a credit pack: there is no account, so the key is the account. We store only a SHA-256 of it, so a lost key can't be recovered, only replaced by support.

Keep keys on your server. CORS is open so you can test from a browser console, but any key in shipped front-end code can be read and spent by anyone.

Endpoints

EndpointRunsCostUse it for
POST /v1/analyzeAI score, faces and metadata1 creditThe default. All three readings for one credit.
POST /v1/ai-detectAI score and metadata1 creditWhen you only need the AI-generation question answered.
POST /v1/facesFaces1 creditFace count and boxes, without the AI model.
POST /v1/metadataMetadata1 creditProvenance and EXIF only. Fastest.
GET /v1/accountBalance and 30-day usageFreeMonitoring your balance from code.

Sending an image

Every check endpoint accepts the image three ways. Pick whichever your stack makes easiest.

Content-TypeBody
multipart/form-dataAn image file field, or an image_url text field. Optional min_confidence.
application/json{"image_base64": "…"} (a data: URL is fine) or {"image_url": "https://…"}. Optional min_confidence.
image/jpeg, image/png, …The raw bytes. min_confidence goes in the query string.

Accepted formats are JPEG, PNG, WebP and GIF (first frame), up to 10 MB and 25 megapixels. The format is read from the bytes, never from the file name or Content-Type.

Fetching from image_url

We download the URL with a 10-second timeout and up to three redirects, from PhotoCheckAPI/1.0. Only http and https on standard ports. URLs that resolve to private, loopback or reserved addresses are refused, at every redirect. A URL that fails to download costs nothing.

min_confidence

A number from 0.2 to 0.95, default 0.5. Faces below it are dropped. Lower it for small or side-on faces and expect occasional false positives in patterns and windows.

Response

Every successful check returns the same object. Blocks for checks the endpoint doesn't run are left out: /faces has no ai or metadata.

200 OK, /v1/analyze
{
  "id": "chk_fym6W1cs1IoDAyGM",
  "object": "image.check",
  "created": 1795077456,
  "image": {
    "width": 700,
    "height": 1050,
    "format": "jpeg",
    "bytes": 62538
  },
  "ai": {
    "score": 0.0214,
    "verdict": "real",
    "label": "No signs of AI generation",
    "model": "umm-maybe/AI-image-detector"
  },
  "faces": {
    "count": 1,
    "faces": [
      {
        "box": {
          "x": 160,
          "y": 224,
          "width": 322,
          "height": 322
        },
        "confidence": 0.91
      }
    ],
    "min_confidence": 0.5,
    "model": "blazeface (Human 3.3)"
  },
  "metadata": {
    "format": "jpeg",
    "exif": {
      "present": false,
      "make": null,
      "model": null,
      "lens": null,
      "software": null,
      "taken_at": null,
      "gps": null
    },
    "c2pa": {
      "present": false,
      "claim_generator": null,
      "signature_verified": false
    },
    "ai_declared": false,
    "generator": null,
    "prompt_excerpt": null,
    "signals": [],
    "note": "No AI provenance found. Most platforms strip metadata on upload, so its absence proves nothing."
  },
  "summary": {
    "ai_generated": "unlikely",
    "has_faces": true,
    "text": "No signs of AI generation (score 0.02). One face found (confidence 0.91)."
  },
  "credits": {
    "charged": 1,
    "remaining": 999
  },
  "ms": 781
}
FieldTypeMeaning
idstringUnique id for this check, chk_…. Not stored; quote it with X-Request-Id when writing to support.
image.width / heightintegerPixels, after EXIF orientation is applied. Face boxes use the same frame.
image.formatstringjpeg, png, webp or gif, sniffed from the bytes.
ai.scorenumber0–1. How strongly the classifier reads the image as generated.
ai.verdictstringlikely_ai (≥0.8), possibly_ai (≥0.5), likely_real (≥0.2) or real.
faces.countintegerFaces at or above min_confidence.
faces.faces[].boxobjectx, y, width, height in pixels from the top-left corner.
faces.faces[].confidencenumber0–1, two decimals. Sorted highest first.
metadata.exifobjectmake, model, lens, software, taken_at (ISO 8601), gps {latitude, longitude}. null when absent.
metadata.c2paobjectpresent, claim_generator, signature_verified (always false for now).
metadata.ai_declaredbooleanThe file itself declares AI generation or an AI edit.
metadata.generatorstring|nullThe generator named by the provenance, when one is.
metadata.prompt_excerptstring|nullUp to 300 characters of an embedded prompt (Stable Diffusion, ComfyUI, Midjourney).
metadata.signals[]arrayEach provenance finding: source (c2pa, iptc, png_text, software), indicates_ai, detail.
summary.ai_generatedstringdeclared, likely, possible, unlikely or not_checked. Declared outranks the score.
summary.has_facesboolean|nullnull when faces weren't checked.
credits.charged / remainingintegerCredits this call cost and what the key has left. remaining is null on keyless calls.
msintegerServer time for the whole check.

Response headers: X-Request-Id on every response, X-Credits-Remaining on keyed calls, X-Free-Remaining on keyless ones, and Retry-After on 429 and some 503s.

Errors

Errors share one shape. Branch on error.type; the message is for people and may change.

402 Payment Required
{
  "error": {
    "type": "insufficient_credits",
    "message": "This key has no credits left. Top it up at https://photocheckapi.com/pricing."
  }
}
StatustypeMeaning
400invalid_requestThe request is missing the image, or a field is malformed.
401authentication_failedThe API key is missing a character, revoked, or not one of ours.
402insufficient_creditsThe key has no credits left. Top it up and retry.
403key_suspendedThe key has been suspended, usually after a payment dispute.
413payload_too_largeThe image is over 10 MB, or over 25 megapixels.
415unsupported_media_typeThe bytes are not a JPEG, PNG, WebP or GIF, or the body type is wrong.
422image_fetch_failedimage_url could not be downloaded, or did not answer 200.
429rate_limitedToo many requests. Wait for the Retry-After header, or use a key.
503service_unavailableA detector is busy or restarting. The credit was returned; retry shortly.

Credits and limits

  • One credit per successful check, whichever endpoint. Credits don't expire.
  • Nothing is charged for a request we reject (bad input, unreadable URL) or a check that fails on our side.
  • Up to 120 requests a minute per key. Write to support for more.
  • Keyless calls: 5 a day per IP address, all endpoints together.
  • Top up from Pricing by pasting your key; the credits are added to it. Check the balance on the key page or with GET /v1/account.

What we keep

Nothing about the image. It's checked in memory and dropped when the response is sent. For each keyed call we record the key, the endpoint, the status, the duration and the credits charged, so your usage page works. For keyless calls, a SHA-256 of your IP address is kept for 24 hours to enforce the daily limit.