판독 사전점검 (precheck)
촬영 직후 최저 지연으로 분석 가능 여부를 확인하고 재촬영을 안내하는 precheck 엔드포인트 사용법.
precheck는 정식 분석 전에 "이 사진이 분석 가능한가"만 빠르게 판단하는 경량 엔드포인트입니다. 깊이 측정이나 규격 OCR 같은 무거운 단계를 건너뛰므로 정식 분석보다 훨씬 빠르고, 현장에서 촬영 직후 재촬영이 필요한지 즉시 안내하는 데 씁니다.
언제 호출하나
사진을 찍은 직후, 업로드·리포트 등록 전에 호출합니다. 통과하면 그때 스토리지에 올려 분석을 진행하고, 실패하면 그 자리에서 재촬영을 유도합니다.
엔드포인트
POST https://api.atrace.ai/v2/tire/tread/precheck
POST https://api.atrace.ai/v2/tire/sidewall/precheck인증은 Authorization: Bearer <토큰>입니다. 브라우저에서 직접 호출할 때 쓰는 단기 토큰을 얻는 방법은
인증 & 저지연 호출 구조를 보세요.
요청
image 바이트(multipart) 를 권장합니다(최저 지연). precheck에서는 json_param을 보내지 않아도 됩니다.
# 트레드
curl -X POST https://api.atrace.ai/v2/tire/tread/precheck \
-H "Authorization: Bearer $TOKEN" \
-F "image=@tread.jpg"
# 사이드월
curl -X POST https://api.atrace.ai/v2/tire/sidewall/precheck \
-H "Authorization: Bearer $TOKEN" \
-F "image=@sidewall.jpg"구버전 예시처럼 json_param={} 빈 객체를 함께 보내도 하위호환으로 계속 동작합니다. 다만 새 구현에서는
precheck의 multipart 경로에서 image만 보내는 형태가 기본 계약입니다.
image 대신 JSON { "image_url": "..." }도 받지만, 서버가 URL을 내려받는 왕복 지연이 더해지므로 바이트 방식을 권장합니다.
해상도는 이미지 품질을 따르세요 — 특히 사이드월은 1280px 이상이어야 합니다.
응답
{ "data": { "analyzable": true, "reason": "ok" } }analyzable(bool) — 이 사진이 해당 모듈 분석에 적합한지.reason(string) — 머신 코드.analyzable이true면ok, 아니면 모듈별 사유 코드입니다.
| reason | 의미 | 재촬영 안내 문구 예시 (자사 문구로 매핑) |
|---|---|---|
ok | 분석 가능 | — |
tread_not_found | 트레드(접지면)를 찾지 못함 | "타이어 접지면(트레드)이 화면에 보이도록 다시 촬영해 주세요." |
size_not_found | 규격 각인 영역을 찾지 못함 | "사이드월의 규격 각인이 선명하게 보이도록 더 가까이서 다시 촬영해 주세요." |
구현 팁
판독 불가는 오류가 아닙니다. 분석이 불가능한 사진도 HTTP
200으로 오고,analyzable: false+reason으로 구분합니다. 손상됐거나 디코딩할 수 없는 이미지만 HTTP400입니다.reason을 정확 매칭에만 의존하지 마세요.향후 사유 코드가 추가될 수 있으므로, 알 수 없는 값이 오면 "다시 촬영해 주세요" 같은 기본 안내로 폴백하도록 구현하세요.
재촬영 안내 문구는 파트너가 자사 UX에 맞게 매핑합니다 — ATRACE는 코드만 내려줍니다.
지연
precheck는 게이트 단계만 실행하므로 정식 분석의 수분의 일 수준입니다. 다만 사이드월 precheck는 이미지가 클수록 느려지므로, 4K처럼 불필요하게 큰 이미지는 보내지 마세요 — 이미지 품질의 권장 해상도를 지키면 됩니다.
흔한 함정
- false-pass: 파이프라인은 작은 이미지를 거부하지 않고 업스케일합니다. precheck 이미지가 정식 분석 이미지보다 지나치게 작으면 precheck만 통과하고 정식에서 실패할 수 있습니다 — 둘의 해상도·프레이밍을 비슷하게 유지하세요.
- 사이드월 해상도 부족이 가장 흔한 실패 원인입니다(1280px 미만).