사진 한 장을 보내면 판정을 JSON으로 돌려받습니다

빠른 시작

사진 파일을 multipart/form-data의 image 필드에 담아 보냅니다. 키가 없어도 됩니다.

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:
            # 파일 이름도 판정에 쓰일 수 있어 중립적인 이름으로 보냅니다
            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)  # 분당 한도나 대기열: 서버가 알려 준 만큼만 쉬고 한 번 더
            continue
        r.raise_for_status()
        return r.json()

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

응답에서 판정은 display_band로 읽습니다(판정 읽는 법).

키와 인증

지금은 키 없이도 부를 수 있고, 이때는 요청한 IP마다 횟수를 셉니다. 키를 받으면 그 키로 따로 셉니다. 키는 둘 중 한 헤더로 보냅니다.

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

• 등록되지 않은 키를 보내면 401 Invalid API key입니다. 키 없는 요청으로 바꿔서 처리하지 않습니다.
• 서버가 키를 필수로 요구하도록 설정되어 있으면, 키 없는 요청은 401 API key required (X-API-Key header)를 받습니다.
• 서버에는 키의 해시만 저장되어 있어 잃어버린 키를 다시 알려 드릴 수 없습니다. 새 키를 받아 주세요.
• 키를 앱이나 웹 페이지 코드에 넣지 마세요. 서버에서만 보내 주세요.

키 받기

키 요청 창구: oscar43@naver.com. 서비스 이름, 하루 예상 요청 수, 이용자 사진을 보내는지 여부를 적어 보내 주세요.

이용자의 사진을 A-EYE로 보내는 서비스라면, 그 이용자에게 사진이 A-EYE 분석 서버로 전송된다는 사실(처리 위탁과 국외 이전)을 알려야 합니다. A-EYE 쪽 처리는 개인정보처리방침에 있습니다. 키는 이 사실을 이용자에게 알리고 있는지, 평가·연구 목적인지 확인한 뒤 드립니다.

사용량 제한

키는 같은 IP의 다른 이용자와 횟수를 나누지 않고 하루 1,000회까지 쓸 수 있습니다. 분당을 10회로 둔 것은 한 번에 한 장씩 분석하는 무료 서버를 A-EYE 앱 이용자와 나눠 쓰기 때문입니다.

• 분당 횟수는 그 창의 첫 요청부터 60초, 하루 횟수는 첫 요청부터 24시간(86,400초) 단위로 셉니다. 자정에 초기화되지 않습니다.
• POST /api/analyze와 POST /predict는 같은 횟수에서 셉니다. 키 확인을 통과한 요청은 형식 오류(400·413·415·422)나 대기열 초과(503)로 끝나도 한 번으로 셉니다. 받기 단계에서 거절된 요청(401, 그리고 Content-Length 헤더만 보고 거절한 400·413)과 429는 세지 않습니다. GET 주소는 세지 않습니다.
• 횟수를 센 응답에는 X-RateLimit-Remaining(이번 분에 남은 횟수) 헤더가 붙습니다. 429에는 창이 끝날 때까지 남은 초가 Retry-After로 붙습니다.
• 분석은 한 번에 한 장씩 합니다. 차례를 기다릴 수 있는 요청은 8건이고, 그 이상이면 바로 503(Retry-After: 2)입니다. 줄에 선 요청도 30초 안에 차례가 오지 않으면 503(Retry-After: 30)입니다.

POST/api/analyze

요청

• multipart/form-data, 파일 필드 이름은 정확히 image 하나입니다. 이름이 다르면 422입니다.
• 형식: JPEG, PNG, WebP. 확장자나 Content-Type이 아니라 파일 앞부분 바이트로 판단합니다. HEIC, GIF, 움직이는 PNG·WebP는 415입니다.
• 크기: 파일 29,360,128바이트(28 MiB)까지. 화소(가로×세로): JPEG 64,000,000, PNG·WebP 32,000,000까지.
• 파일은 받은 그대로 보내 주세요. 파일 안의 C2PA·메타데이터 기록도 판정에 쓰이고, 다시 저장하거나 압축하면 이 기록과 흔적이 줄어듭니다.
• 업로드한 파일 이름도 서버가 읽습니다. 생성 도구가 붙이는 이름이나 스크린샷 이름은 결과에 영향을 줄 수 있으니, 원래 이름이 필요 없으면 image.jpg처럼 중립적인 이름으로 보내 주세요.

응답 필드

아래 필드만 연동에 쓰세요. 응답에는 이 표에 없는 필드도 들어 있지만 내부 점검용이라 이름과 값이 예고 없이 바뀌거나 빠질 수 있습니다. 필드가 새로 생길 수 있으니 모르는 필드는 무시하도록 만들어 주세요.

그림 필드에는 data: 접두어가 없습니다. 화면에 띄우려면 data:image/png;base64,를 앞에 붙이세요.

응답 예시(값은 설명용, 그림은 줄임)

{
  "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,
  …
}

이 예에서 판정은 판단 유보이고, 사람에게 보여 줄 숫자는 49입니다. verdict는 "REAL", score는 0.91이라 둘 중 하나만 보면 판정을 잘못 읽게 됩니다.

판정 읽는 법

display_band가 판정이고, basis는 그 이유를 덧붙입니다. A-EYE 앱은 이렇게 보여 줍니다.

POST/predict

예전 앱이 쓰던 형식을 그대로 돌려주는 호환 주소입니다. 새로 연동한다면 /api/analyze를 쓰세요. 이 응답에는 display_band가 없어서 판단 유보를 구분할 수 없습니다.

• 요청은 /api/analyze와 같습니다. 같은 image 필드, 같은 크기 제한, 같은 횟수입니다.
• 응답의 fake_prob은 score에 100을 곱한 실수, real_prob은 100에서 fake_prob을 뺀 값입니다. fake_prob을 사람에게 점수로 보여 주지 마세요. 판단 유보를 모르고, display_score와도 다릅니다. verdict, heatmap_b64, overlay_b64, heatmap_style, model_version, input_kind는 /api/analyze와 같습니다. 그 밖의 필드는 내부 점검용입니다.
• 오류가 하나 다릅니다. 분석 도중 실패하면 422가 아니라 200과 함께 {"error": "Invalid image"}를 돌려줍니다. 200을 받으면 먼저 error 키가 있는지 보세요.
• 빈 파일, 깨진 파일, 허용하지 않는 형식, 너무 큰 파일은 /api/analyze와 똑같이 400, 413, 415로 거절됩니다. image 필드가 없을 때도 똑같이 422와 목록 형태의 detail을 받습니다.

GET/api/health

200과 {"status": "ok"}는 서버가 시작을 마치고 모델을 다 불러왔다는 뜻입니다. 서버는 모델을 다 불러온 뒤에야 요청을 받기 시작하므로, 시작하는 동안에는 이 주소도 응답하지 않습니다. 다른 상태값은 없고, 대기열이 찼는지는 알려 주지 않습니다. 횟수에 들어가지 않습니다.

GET/api/version

지금 판정하는 모델의 이름을 model_version으로 돌려줍니다. 함께 오는 다른 필드는 운영 점검용입니다. 횟수에 들어가지 않습니다.

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

오류

오류 본문은 {"detail": "…"}이고 detail은 문자열입니다. 예외는 둘입니다. 요청 형식이 틀렸을 때(FastAPI 검증 오류) 422의 detail은 목록이고, /predict의 분석 실패는 위에서 본 200 응답입니다.

요청 형식이 틀린 422의 본문은 이렇게 생겼습니다. detail이 문자열인지 목록인지로 분석 실패와 구분하세요.

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

A-EYE 서버의 응답에는 대부분 X-Request-Id 헤더(16진수 8자리)가 붙습니다. 분석 실패의 ref 값과 같은 값이니 문의할 때 함께 보내 주세요.

이용 조건

• 평가·시범용입니다. 가용성과 응답 시간을 보장하지 않고, 서비스 수준 계약(SLA)은 없습니다.
• 사진을 저장하지 않습니다. 보낸 사진은 결과를 돌려준 직후 폐기되고 모델 학습에 쓰지 않습니다.
• 결과를 다른 사람에게 보여 줄 때는 추정이라고 밝혀 주세요. 판정을 사실 확인이나 증거처럼 보이게 하지 마세요.
• 상업 서비스에서 쓰려면 먼저 문의해 주세요. 시범 기간에는 문의를 받은 뒤 개별로 판단합니다.

한계

• 판정은 추정입니다. 실제 사진을 AI로, AI 이미지를 실제로 판단할 수 있고, 새로 나온 생성 도구의 이미지일수록 놓치기 쉽습니다. 법적 증거, 보도, 인사 결정처럼 중요한 판단의 유일한 근거로 쓰지 말고 출처, 촬영 맥락, 메타데이터를 함께 확인해 주세요.
• 무료 서버 한 대입니다. CPU 서버 한 대가 한 번에 한 장씩 분석하고, A-EYE 앱 이용자와 같은 서버를 나눠 씁니다. 한꺼번에 많이 보내면 앱 이용자까지 503을 받습니다. 많은 양을 한 번에 처리해야 하면 먼저 문의해 주세요. 가용성은 보장하지 않으며, 서버가 다시 시작하는 동안에는 응답이 없습니다.
• 화면 캡처는 판단 유보가 자주 나옵니다. 판정 기준이 카메라로 찍은 사진(메신저로 받은 사진 포함)에 맞춰져 있기 때문입니다. 화면 캡처로 보이는 일부 PNG는 서버의 화면 캡처 처리 단계에서 판단 유보가 진짜 사진으로 한 단계 내려갈 수 있고, 이때 score는 사진 기준 점수 그대로입니다. 판정은 display_band를 따르세요. 진짜로 나와도 캡처 속 대화나 금액이 사실이라는 뜻은 아닙니다.
• 브라우저에서 바로 부를 수 없습니다. 다른 웹사이트의 브라우저 코드에서 부르면 교차 출처(CORS) 설정에 막힙니다. 여러분의 서버에서 호출해 주세요.
• 사진은 남기지 않습니다. 보낸 사진은 분석하는 동안만 서버 메모리에 있고, 결과를 돌려준 직후 폐기되며 모델 학습에 쓰지 않습니다. 자세한 내용은 개인정보처리방침에 있습니다.

문의

API 문의: oscar43@naver.com. 오류를 알릴 때는 X-Request-Id와 시각을 함께 보내 주세요. 앱 사용 문의는 지원 페이지에 있습니다.