판독 사전점검 (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, 아니면 모듈별 사유 코드입니다.
HTTP 상태 규칙
precheck의 HTTP 상태는 사진을 검사했는지로 나뉩니다.
| HTTP | 의미 | 해당 경우 | 클라이언트 처리 |
|---|---|---|---|
200 | 사진을 검사했습니다 | 분석 가능(analyzable: true)과 판독 불가(analyzable: false + reason) 모두 | reason에 따라 진행하거나 재촬영을 안내합니다. |
4xx | 사진을 검사하지 못했습니다 | 이미지를 받거나 풀 수 없음(bad_image_url), 크기 상한 초과(image_too_large), 잘못된 요청(code: null) | 요청·이미지를 고칩니다. 같은 요청을 재시도하지 마세요. |
5xx | 서버 쪽 문제입니다 | 500 internal_server_error 등 | 잠시 후 재시도하거나 precheck 없이 진행합니다. |
크기 상한을 넘는 사진은 400 image_too_large입니다. 예전에는 트레드 precheck가 이 경우 200 tread_not_found를 돌려줬습니다.
권장 해상도(이미지 품질)로 줄여 보내면 이 오류는 나지 않습니다.
reason 목록
reason은 재촬영으로 해결되는 것과 재촬영해도 결과가 같은 것(종결) 으로 나뉩니다.
| 모듈 | reason | 의미 | 구분 | 안내 문구 예시 (자사 문구로 매핑) |
|---|---|---|---|---|
| 공통 | ok | 분석 가능 | — | — |
| 트레드 | tread_not_found | 트레드(접지면)를 찾지 못함 | 재촬영 | "타이어 접지면(트레드)이 화면에 보이도록 다시 촬영해 주세요." |
| 트레드 | photo_too_dark | 사진이 너무 어두움 | 재촬영 | "사진이 너무 어둡습니다. 밝은 곳에서 또는 조명을 켜고 다시 촬영해 주세요." |
| 트레드 | photo_too_blurry | 흔들림 또는 초점 불량 | 재촬영 | "사진이 흐립니다. 카메라를 고정하고 트레드에 초점을 맞춰 다시 촬영해 주세요." |
| 트레드 | tread_pattern_unsupported | 윈터·특수 타이어 등 지원하지 않는 트레드 패턴 | 종결 | "이 타이어의 트레드 패턴은 자동 측정을 지원하지 않습니다." (재촬영을 요청하지 않음) |
| 사이드월 | size_not_found | 규격 각인 영역을 찾지 못함 | 재촬영 | "사이드월의 규격 각인이 선명하게 보이도록 더 가까이서 다시 촬영해 주세요." |
tread_pattern_unsupported는 재촬영으로 해결되지 않습니다
윈터·올웨더·오프로드처럼 트레드 패턴이 일반 타이어와 다른 타이어는 다시 찍어도 같은 결과가 나옵니다.
재촬영을 반복하게 하지 말고, 수동 점검 등 다른 경로로 안내하세요. 정식 분석도 같은 사진에 400 tread_pattern_unsupported를 돌려줍니다.
구현 팁
판독 불가는 오류가 아닙니다. 분석이 불가능한 사진도 HTTP
200으로 오고,analyzable: false+reason으로 구분합니다.4xx는 사진을 검사하지 못한 경우입니다.reason은 정확히 일치하는 값으로 분기하세요.부분 문자열로 매칭하면
tread_pattern_unsupported처럼tread를 포함하는 코드가 엉뚱한 안내로 빠질 수 있습니다. 향후 사유 코드가 추가될 수 있으므로, 알 수 없는 값이 오면 "다시 촬영해 주세요" 같은 기본 안내로 폴백하도록 구현하세요.precheck가
analyzable: true로 통과한 트레드 사진은 정식 분석에서photo_too_dark·photo_too_blurry·tread_pattern_unsupported로 거절되지 않습니다. 다만 그루브를 측정하는 단계에서 드물게tread_not_found가 날 수 있습니다.재촬영 안내 문구는 파트너가 자사 UX에 맞게 매핑합니다 — ATRACE는 코드만 내려줍니다.
지연
precheck는 게이트 단계만 실행하므로 정식 분석의 수분의 일 수준입니다. 다만 사이드월 precheck는 이미지가 클수록 느려지므로, 4K처럼 불필요하게 큰 이미지는 보내지 마세요 — 이미지 품질의 권장 해상도를 지키면 됩니다.
흔한 함정
- false-pass: 파이프라인은 작은 이미지를 거부하지 않고 업스케일합니다. precheck 이미지가 정식 분석 이미지보다 지나치게 작으면 precheck만 통과하고 정식에서 실패할 수 있습니다 — 정식 분석에 보낼 사진을 축소해 프레이밍을 맞추고, 이미지 품질의 precheck 크기보다 작게 줄이지 마세요.
- 사이드월 해상도 부족이 가장 흔한 실패 원인입니다(1280px 미만).
- 사이드월 precheck 통과가 규격 인식을 보장하지는 않습니다. precheck는 규격 각인 영역이 있는지만 봅니다. 흔들려 글자가
흐린 사진은 precheck가
200 ok여도 정식 분석이400 tire_size_not_found일 수 있습니다. 공개 샘플 sidewall-205-65R15.jpg가 그런 예입니다.
