판독 서버 API

이미지 한 장을 보내면 번호판 문자열을 돌려주는 HTTP API 입니다. 고객사 서버·현장 장비에서 직접 부를 때 쓰며, 인증은 온라인 계정에서 발급한 API 키로 합니다. (AXCam 앱은 기기에서 직접 판독하므로 이 API 를 부르지 않습니다.)

한눈에 보기

• 기본 주소 https://axcam.kloa.kr, 모든 경로는 /api/v1/anpr/ 아래입니다.
• 인증: 모든 요청에 X-API-Key 헤더. 키는 내 계정에서 결제 없이 발급하며, 한 계정의 키들은 요금제·충전 횟수를 함께 씁니다.
• 응답은 항상 JSON 봉투 {"status", "data", "message", "time"} 입니다. HTTP 200 이면 data 를 읽습니다.
• 과금 단위는 성공 판독 1회 — recognized=true 이고 duplicated=false 인 응답만 셉니다. 미인식·중복·오류는 세지 않습니다.
• 업로드 이미지는 요청을 처리하는 동안 메모리에만 있다가 응답과 함께 파기됩니다. 번호판 원문도 저장하지 않습니다 (판독 기록에는 일방향 해시만 남습니다).

POST /api/v1/anpr/recognize — 번호판 판독

multipart/form-data 로 이미지를 보냅니다.

요청 예

curl -X POST https://axcam.kloa.kr/api/v1/anpr/recognize \
  -H "X-API-Key: ax_live_xxxxxxxxxxxxxxxx" \
  -F "image=@vehicle.jpg" \
  -F "track_id=cam1-000123" \
  -F "captured_at=2026-09-07T14:02:11"

응답 — 인식

plate_type 부터 plate_color_label 까지는 조회 서버 API 의 같은 키와 같은 값입니다 — 판독 응답을 그대로 조회 요청에 옮겨 담을 수 있습니다.

HTTP/1.1 200 OK
{
  "status": "success",
  "data": {
    "recognized": true,
    "plate_number": "서울31바1234",   // 번호판 원문 (응답에만 있고 서버에는 남지 않습니다)
    "confidence": 0.97,               // 판독 신뢰도 0~1 (0.75 미만은 미인식으로 돌려줍니다)
    "plate_type": "commercial",       // 종류 코드 — 조회 서버 API 문서의 표와 같은 값
    "plate_type_label": "영업용",
    "plate_format": "region_biz",     // 형식 (standard / region_biz / moto_old / moto_new / diplomatic / temporary / unknown)
    "region1": "서울",                 // 시·도 (없으면 null)
    "region2": null,                  // 시·군·구 — 이륜 구형판
    "number1": "31",                  // 앞 숫자 (차종 기호)
    "hangul": "바",                    // 용도 문자
    "number2": "1234",                // 일련번호
    "plate_color": "yellow",          // 번호판 색상 코드 — white 일반 / blue 전기차 / yellow 영업용 / green 법인 / orange 건설기계 (모르면 null)
    "plate_color_label": "영업용",
    "duplicated": false,              // 같은 키가 60초 안에 같은 번호판을 읽었으면 true (과금 안 됨)
    "truncated": false,
    "log_id": 48213,                  // 판독 기록 ID — 아래 판정 첨부에 씁니다
    "track_id": "cam1-000123",
    "recognized_at": "2026-09-07 14:02:12",
    "elapsed_ms": 312
  },
  "message": null,
  "time": "2026-09-07T14:02:12.418+09:00"
}

응답 — 미인식

HTTP 200 에 recognized=false 입니다. 오류가 아니라 '이 이미지에서는 못 읽었다' 는 뜻이므로, 차량이 더 가까워진 다음 프레임으로 다시 시도하는 것이 맞습니다.

{
  "status": "success",
  "data": {
    "recognized": false,
    "reason": "no_plate",             // 아래 표
    "confidence": null,
    "truncated": false,
    "track_id": "cam1-000123",
    "plate_number": null,
    "elapsed_ms": 205
  }
}

GET /api/v1/anpr/ping — 키 확인 · 요금제 상태

키가 유효한지, 이번 달(또는 오늘) 얼마나 썼는지 확인합니다. 과금되지 않습니다.

{
  "status": "success",
  "data": {
    "device_id": 17,                  // 키 번호
    "device_name": "정문 카메라",
    "web_key": true,
    "engine": "axnet",
    "plan": "basic",                  // trial 이면 요금제 없음 (계정당 하루 10회 테스트)
    "plan_label": "베이직",
    "quota": 1000,                    // 월 한도 (trial 은 하루 한도)
    "used": 312,
    "remaining": 688,
    "credits_remaining": 100,         // 단건 충전 잔여 — 한도를 다 쓴 뒤부터 차감
    "period": "202609",
    "resets_at": "2026-10-01 00:00:00",
    "subscription_state": "WEB_PAID",
    "subscription_expires_at": "2026-10-07 14:00:00"
  }
}

POST /api/v1/anpr/log/{log_id}/result — 판정 첨부 (선택)

판독 기록에 고객사 판정을 붙여 두면 관리자 화면에서 판독과 판정을 같이 볼 수 있습니다. JSON 본문:

{
  "is_abnormal": true,               // 필수 (불리언 또는 "true"/"1")
  "status": "suspended",             // 선택
  "status_label": "출입정지",         // 선택
  "reason": "미납 3개월"              // 선택
}

오류

권장 사용 방식

• 차량을 먼저 찾아 차량 영역만 잘라 보내세요. 여백은 차량 박스의 8% 정도면 충분합니다.
• 같은 차량을 연속 프레임으로 여러 번 보내지 마세요 — 한 장이 미인식이면 차가 더 커진 프레임(가로 1.25배 이상)에서 다시 시도하는 것이 효율적입니다.
• 야간·고감도 이미지는 압축 품질을 낮추지 마세요 (글자 에지가 노이즈와 함께 지워집니다). WebP 80 / JPEG 88 이상.
• 결과를 조회 서버로 넘길 때의 JSON 규격은 조회 서버 API 문서에 있습니다. 내 계정 → 인식 테스트에서 사진 한 장으로 그 JSON 을 미리 볼 수 있습니다.