ATRACE Report API와 AI Engine API
API가 둘인 이유와 차이, 그리고 어느 쪽을 써야 하는지 설명합니다.
ATRACE는 목적이 다른 두 API를 제공합니다. 처음 연동한다면 이 둘의 역할 차이를 먼저 알아야 합니다.
요약
- ATRACE Report API — 리포트를 만들어 달라고 요청합니다. 대부분의 파트너가 쓰는 진입점입니다.
- AI Engine API — 이미지 한 장의 분석값을 요청합니다. 자체 리포트 시스템을 직접 만드는 고객용입니다.
두 API를 나눈 이유
ATRACE는 성격이 다른 두 가지 일을 합니다.
- 이미지 분석 — 타이어 사진(PNG·JPEG, 가급적 Full HD(1920×1080)급 이상 권장)을 분석합니다. 무겁고, 분석 모델 가까이에서 처리해야 빠릅니다. 이 일은 AI 추론 서비스가 맡습니다.
- 리포트 오케스트레이션 — 리포트를 만들고, 이미지를 보관하고, 분석을 호출하고, 공개 링크를 발급합니다. 가볍고 상태를 다룹니다. 이 일은 플랫폼 서비스가 맡습니다.
이미지 바이트는 플랫폼 서비스를 거치지 않고 AI 추론 서비스(또는 스토리지)로 곧장 갑니다.
차이
| 구분 | ATRACE Report API | AI Engine API |
|---|---|---|
| 호스트 | app.atrace.ai/api/v1 | api.atrace.ai |
| 추상화 | 리포트 단위 | 이미지 1장 단위 |
| 상태 | 리포트·이미지·공유를 저장 | 저장하지 않음 |
| 대표 호출 | POST /reports | POST /v2/tire/tread |
| 이미지 보관 | 플랫폼이 보관 | 보관하지 않음 |
| 분석 트리거 | 이미지 등록 시 자동 | 호출자가 직접 |
| 공개 링크 | 발급·관리 | 없음 |
| 대상 | 대부분의 파트너 | 자체 리포트를 만드는 고객 |
AI 추론 서비스는 상태를 저장하지 않습니다
AI Engine API는 이미지나 결과를 보관하지 않습니다. 이미지를 받아 분석값만 돌려줍니다. 이미지 보관과 리포트화는 플랫폼 서비스가 맡습니다.
어느 API를 쓸지
- 자사앱에서 촬영해 리포트를 받는다 → ATRACE Report API. 대부분 여기 해당합니다.
- 자체 점검 시스템이 있고 분석값만 필요하다 → AI Engine API.
현장 촬영 품질을 즉시 확인 — Precheck
ATRACE Report API를 쓰는 파트너라도, 촬영 현장에서 "방금 찍은 사진이 분석 가능한지"를 즉시 확인하고 싶다면 AI Engine API의 판독 가능성 사전 점검(POST /v2/tire/tread/precheck, POST /v2/tire/sidewall/precheck)을 쓸 수 있습니다. 무거운 분석을 건너뛰고 { analyzable, reason }만 빠르게 돌려주어, 재촬영이 필요하면 촬영 단계에서 바로 안내할 수 있습니다. 이 점검은 AI Engine API라 ai:* 스코프가 필요합니다. 자세한 내용은 AI Engine API 레퍼런스를 보세요.
키와 권한 범위
두 API는 하나의 키로 접근하고, 인증 방식도 동일합니다. 발급받은 API Key를 그대로 Authorization: Bearer <API Key>로 보내면 됩니다. AI Engine API도 같은 API Key를 그대로 사용합니다. 키마다 권한 범위(scope)가 다릅니다.
report:*— ATRACE Report API 호출ai:*— AI Engine API 호출- 둘 다 받으면 양쪽 모두 호출
대부분의 파트너는 report:* 만 받습니다. 자세한 내용은 시작하기를 보세요.