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.
curl https://photocheckapi.com/api/v1/analyze \
-H "Authorization: Bearer $PHOTOCHECK_API_KEY" \
-F image=@photo.jpgQuickstarts: 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
| Endpoint | Runs | Cost | Use it for |
|---|---|---|---|
POST /v1/analyze | AI score, faces and metadata | 1 credit | The default. All three readings for one credit. |
POST /v1/ai-detect | AI score and metadata | 1 credit | When you only need the AI-generation question answered. |
POST /v1/faces | Faces | 1 credit | Face count and boxes, without the AI model. |
POST /v1/metadata | Metadata | 1 credit | Provenance and EXIF only. Fastest. |
GET /v1/account | Balance and 30-day usage | Free | Monitoring your balance from code. |
Sending an image
Every check endpoint accepts the image three ways. Pick whichever your stack makes easiest.
| Content-Type | Body |
|---|---|
multipart/form-data | An 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.
{
"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
}| Field | Type | Meaning |
|---|---|---|
id | string | Unique id for this check, chk_…. Not stored; quote it with X-Request-Id when writing to support. |
image.width / height | integer | Pixels, after EXIF orientation is applied. Face boxes use the same frame. |
image.format | string | jpeg, png, webp or gif, sniffed from the bytes. |
ai.score | number | 0–1. How strongly the classifier reads the image as generated. |
ai.verdict | string | likely_ai (≥0.8), possibly_ai (≥0.5), likely_real (≥0.2) or real. |
faces.count | integer | Faces at or above min_confidence. |
faces.faces[].box | object | x, y, width, height in pixels from the top-left corner. |
faces.faces[].confidence | number | 0–1, two decimals. Sorted highest first. |
metadata.exif | object | make, model, lens, software, taken_at (ISO 8601), gps {latitude, longitude}. null when absent. |
metadata.c2pa | object | present, claim_generator, signature_verified (always false for now). |
metadata.ai_declared | boolean | The file itself declares AI generation or an AI edit. |
metadata.generator | string|null | The generator named by the provenance, when one is. |
metadata.prompt_excerpt | string|null | Up to 300 characters of an embedded prompt (Stable Diffusion, ComfyUI, Midjourney). |
metadata.signals[] | array | Each provenance finding: source (c2pa, iptc, png_text, software), indicates_ai, detail. |
summary.ai_generated | string | declared, likely, possible, unlikely or not_checked. Declared outranks the score. |
summary.has_faces | boolean|null | null when faces weren't checked. |
credits.charged / remaining | integer | Credits this call cost and what the key has left. remaining is null on keyless calls. |
ms | integer | Server 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.
{
"error": {
"type": "insufficient_credits",
"message": "This key has no credits left. Top it up at https://photocheckapi.com/pricing."
}
}| Status | type | Meaning |
|---|---|---|
| 400 | invalid_request | The request is missing the image, or a field is malformed. |
| 401 | authentication_failed | The API key is missing a character, revoked, or not one of ours. |
| 402 | insufficient_credits | The key has no credits left. Top it up and retry. |
| 403 | key_suspended | The key has been suspended, usually after a payment dispute. |
| 413 | payload_too_large | The image is over 10 MB, or over 25 megapixels. |
| 415 | unsupported_media_type | The bytes are not a JPEG, PNG, WebP or GIF, or the body type is wrong. |
| 422 | image_fetch_failed | image_url could not be downloaded, or did not answer 200. |
| 429 | rate_limited | Too many requests. Wait for the Retry-After header, or use a key. |
| 503 | service_unavailable | A 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.