Send one image, get the verdict back as JSON

Quick start

Send the image file in the image field of a multipart/form-data request. No key is needed.

curl

curl -sS https://wonjun12-aeye-backend.hf.space/api/analyze \
  -F "image=@photo.jpg;filename=image.jpg"

Python (requests)

import time
import requests

BASE = "https://wonjun12-aeye-backend.hf.space"

def analyze(path, api_key=None):
    headers = {"X-API-Key": api_key} if api_key else {}
    for attempt in range(2):
        with open(path, "rb") as f:
            # the file name can affect the verdict, so send a neutral one
            r = requests.post(f"{BASE}/api/analyze", headers=headers,
                              files={"image": ("image.jpg", f)}, timeout=120)
        wait = int(r.headers.get("Retry-After", "0"))
        if r.status_code in (429, 503) and attempt == 0 and wait <= 60:
            time.sleep(wait)  # per-minute limit or a full line: wait as told, try once more
            continue
        r.raise_for_status()
        return r.json()

result = analyze("photo.jpg")
print(result["display_band"], result["display_score"])

Read the verdict from display_band (see Reading the verdict).

Keys

Today the API can be called without a key; such requests are counted per IP address. With a key, requests are counted for that key. Send the key in either header:

X-API-Key: <key>
Authorization: Bearer <key>

• A key that is not registered gets 401 Invalid API key. The request is not handled as a keyless one instead.
• When the server is set to require a key, a request without one gets 401 API key required (X-API-Key header).
• The server stores only a hash of each key, so a lost key cannot be looked up. Ask for a new one.
• Keep the key out of app and web page code. Send it from your server only.

Getting a key

Where to ask: oscar43@naver.com. Tell us the service name, the expected requests per day and whether you send your users’ photos.

If your service sends its users’ photos to A-EYE, you must tell those users that their photos are sent to the A-EYE analysis server (processing by a third party and transfer abroad). How A-EYE handles them is in the privacy policy. A key is issued after we have confirmed that you tell your users this and that the use is for evaluation or research.

Rate limits

A key is counted on its own, never together with others on the same IP address, and allows 1,000 requests a day. Its per-minute limit is 10 because one free server analyzes one image at a time and is shared with A-EYE app users.

• A minute is 60 seconds from the first request of the window, and a day is 24 hours (86,400 seconds) from the first request of its window. Nothing resets at midnight.
• POST /api/analyze and POST /predict share one count. A request that passes the key check counts once even if it then fails as a bad upload (400, 413, 415, 422) or a full line (503). Requests stopped at the Receive step (401, and the 400 or 413 decided from the Content-Length header alone) and 429s do not count. GET endpoints do not count.
• Counted responses carry X-RateLimit-Remaining, the requests left this minute. A 429 carries Retry-After, the seconds until its window ends.
• Images are analyzed one at a time. Up to 8 requests can wait for their turn; one more gets an immediate 503 (Retry-After: 2). A waiting request whose turn does not come within 30 seconds also gets a 503 (Retry-After: 30).

POST/api/analyze

Request

• multipart/form-data with exactly one file field, named image. Any other name gets a 422.
• Formats: JPEG, PNG, WebP, decided from the first bytes of the file, not from its extension or Content-Type. HEIC, GIF and animated PNG or WebP get a 415.
• Size: files of at most 29,360,128 bytes (28 MiB). Pixels (width × height): at most 64,000,000 for JPEG and 32,000,000 for PNG and WebP.
• Send the file as you received it. C2PA and metadata records inside the file are part of the verdict, and saving or compressing it again weakens those records and traces.
• The server also reads the uploaded file name. A name a generator gives its exports, or a screenshot’s name, can change the result, so if you do not need the original name, send a neutral one such as image.jpg.

Response fields

Build only on the fields below. The response carries more fields than this table; they are internal diagnostics whose names and values can change or disappear without notice. New fields can be added, so ignore fields you do not know.

The image fields have no data: prefix. To show one, put data:image/png;base64, in front of it.

Example response (illustrative values, images shortened)

{
  "display_band": "uncertain",
  "display_score": 49,
  "verdict": "REAL",
  "score": 0.91,
  "basis": "model",
  "partial_edit_suspect": false,
  "heatmap_b64": "iVBORw0KGgo…",
  "overlay_b64": "iVBORw0KGgo…",
  "heatmap_style": "spotlight",
  "input_kind": "photo",
  "model_version": "best91(v6)+best91_loc",
  "elapsed_ms": 3140,
  …
}

In this example the verdict is Inconclusive and the number to show is 49. verdict says "REAL" and score is 0.91, so reading either one alone gets the verdict wrong.

Reading the verdict

display_band is the verdict and basis adds why. This is how the A-EYE app shows them.

POST/predict

A compatibility endpoint that keeps the response format older app versions used. For a new integration, use /api/analyze: this response has no display_band, so it cannot tell you a result was inconclusive.

• The request is the same as for /api/analyze: the same image field, the same size limits, the same count.
• fake_prob is score multiplied by 100, and real_prob is 100 minus fake_prob. Do not show fake_prob to people as a score: it cannot tell an inconclusive result and differs from display_score. verdict, heatmap_b64, overlay_b64, heatmap_style, model_version and input_kind are as in /api/analyze. Other fields are internal diagnostics.
• One error differs: when the analysis itself fails, the answer is not a 422 but a 200 with {"error": "Invalid image"}. On a 200, look for an error key first.
• Empty, broken, unsupported and oversized files are refused exactly as on /api/analyze, with 400, 413 and 415. A missing image field also gets the same 422 with a list in detail.

GET/api/health

200 with {"status": "ok"} means the server has finished starting and has loaded its models. The server only starts taking requests once the models are loaded, so while it starts this endpoint does not answer either. There is no other status value, and it does not tell you whether the line is full. It does not count toward the rate limit.

GET/api/version

Returns the name of the model now giving verdicts as model_version. The other fields that come with it are for operations. It does not count toward the rate limit.

{"model_version": "best91(v6)+best91_loc", …}

Errors

An error body is {"detail": "…"} with a string in detail. There are two exceptions: a 422 for a malformed request (a FastAPI validation error) has a list in detail, and an analysis failure on /predict is the 200 answer described above.

A 422 for a malformed request looks like this. Whether detail is a string or a list tells it apart from an analysis failure.

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "image"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Responses from the A-EYE server almost always carry an X-Request-Id header (8 hexadecimal digits). It is the same value as the ref of an analysis failure; include it when you contact us.

Terms of use

• For evaluation and pilots. Availability and response times are not guaranteed, and there is no service level agreement (SLA).
• Photos are not stored. A photo you send is discarded as soon as the result is returned and is not used for model training.
• When you show a result to others, say it is an estimate. Do not present a verdict as a fact check or as evidence.
• To use the API in a commercial service, ask first. During the pilot period, each request is considered case by case.

Limitations

• The verdict is an estimate. A real photo can be judged AI and an AI image real, and images from newly released generators are the easiest to miss. Do not use a result as the only basis for an important decision such as legal evidence, news reporting or a hiring decision; check the source, the context in which it was taken and the metadata as well.
• It is one free server. One CPU server analyzes one image at a time and is shared with the users of the A-EYE app. Sending many requests at once makes app users get 503s too. If you need to process a large batch, contact us first. Availability is not guaranteed, and the server does not answer while it restarts.
• Screenshots often come out Inconclusive. The verdict criteria are set to fit photos taken with a camera, including ones shared in messages. For some PNG images that look like screenshots, a server-side screenshot step can move an Inconclusive result down to Likely real; score then stays on the photo scale. Follow display_band. A Likely real screenshot does not mean the messages or amounts it shows are true.
• It cannot be called from a browser directly. Browser code on another website is blocked by the cross-origin (CORS) settings. Call the API from your server.
• Images are not kept. An uploaded image is held in server memory only while it is analyzed, is discarded as soon as the result is returned, and is never used to train models. See the privacy policy.

Contact

API questions: oscar43@naver.com. When reporting an error, include the X-Request-Id and the time. For help with the app, see the support page.