시작하기

ATRACE Report API로 첫 호출까지 안내합니다. AI Engine API 직접 호출은 ATRACE Report API와 AI Engine API를 먼저 보세요.

0. 키 발급/온보딩

API Key는 셀프서비스 콘솔에서 직접 발급합니다. 조직 관리자가 콘솔에 로그인해 프로젝트(test 또는 live 모드)를 만들고, 그 프로젝트 안에서 API Key를 발급하면 됩니다. 전체 키 값은 발급 시 한 번만 표시되니 안전한 곳에 저장하세요. 더 쓰지 않는 키는 콘솔에서 폐기(revoke)할 수 있습니다. 테스트 프로젝트는 조직당 1개(무료)이고, 라이브 프로젝트는 필요한 만큼 만들 수 있습니다. 발급받은 키로 아래 인증 절차를 그대로 따르면 됩니다.

1. 인증

모든 요청에 발급받은 API Key를 Authorization: Bearer <API Key> 형태로 넣습니다. 발급받은 키를 그대로 보내면 됩니다.

Authorization: Bearer atr_test_xxxxxxxxxxxxxxxxxxxx

키는 프로젝트 단위로 발급됩니다. 프로젝트는 조직에 속하며, 데이터는 프로젝트별로 격리됩니다(한 키는 자신의 프로젝트 데이터에만 접근).
키에는 권한 범위(scope)가 있습니다. 대부분의 파트너는 report:*를 받습니다.
ATRACE Report API와 AI Engine API는 인증 방식이 동일합니다. 두 API 모두 발급받은 API Key를 그대로 Authorization: Bearer <API Key>로 보내면 됩니다.
키는 클라이언트(브라우저·모바일앱)에 노출하지 마세요. 서버 간 통신에만 사용합니다.

2. 호스트와 모드

호스트는 하나이고, API 키가 모드를 결정합니다(별도의 샌드박스 호스트는 없습니다).

모드	키 접두사	개수	용도
테스트	`atr_test_…`	조직당 1개	무료 연동 시험 (실데이터 아님)
라이브	`atr_live_…`	필요한 만큼	실서비스

ATRACE Report API: https://app.atrace.ai/api/v1
AI Engine API: https://api.atrace.ai

키는 프로젝트 단위로 발급됩니다. 개발은 무료 테스트 프로젝트 키로 시작하고, 같은 코드에서 키만 라이브로 바꾸면 실서비스로 전환됩니다(호스트 변경 없음). 라이브 프로젝트는 리전·플릿 등 필요에 따라 여러 개를 둘 수 있습니다. 자세한 내용은 테스트와 라이브 모드를 보세요.

3. 첫 호출 — 리포트 생성

바로 실행해 보고 싶다면

미리 준비된 샘플 이미지로 복사–실행만으로 동작하는 예제가 필요하면 퀵스타트로 가세요. 고객 URL 모드 한 번의 호출과 Pre-Signed 업로드를 대신 해 주는 bash 스크립트를 모두 제공합니다.

가장 단순한 시작은 고객 URL 모드입니다(이미 이미지 URL을 가지고 있을 때). 요청에 이미지를 함께 보내면 분석이 자동으로 시작됩니다. plate_number는 선택 필드입니다. 신차·번호판 미장착·고객사 자체 QR 사용 등으로 번호판이 없으면 생략할 수 있습니다. 같은 차량의 리포트를 묶고 싶다면 external_vehicle_id(선택)에 파트너 측 차량 ID를 넣으세요. 번호판은 바뀌거나 다른 차량으로 재사용될 수 있어, 차량 단위 관리에는 이 필드를 권장합니다. template은 촬영 구성을 정합니다(템플릿 설명 참고).

curl -X POST https://app.atrace.ai/api/v1/reports \
  -H "Authorization: Bearer $ATRACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: partner-INSP-0001" \
  -d '{
    "plate_number": "12가3456",
    "external_inspection_id": "partner-INSP-0001",
    "external_vehicle_id": "partner-VEH-0001",
    "template": "tire_4t_2s",
    "callback_url": "https://partner.example.com/atrace/webhook",
    "images": [
      { "module_type": "tire", "slot": { "position": "front_left", "image_type": "tread" },
        "source": { "url": "https://docs.atrace.ai/samples/tire/tread-a-8mm.jpg" } },
      { "module_type": "tire", "slot": { "position": "front_left", "image_type": "sidewall" },
        "source": { "url": "https://docs.atrace.ai/samples/tire/sidewall-205-55R16.jpg" } }
    ]
  }'

응답:

{
  "report_id": "rpt_01HXEXAMPLE",
  "status": "processing",
  "share_url": "https://app.atrace.ai/r/sh_abcdef"
}

share_url은 생성 응답에 이미 포함됩니다. 바로 저장해 두면 되고, 완료를 기다렸다가 다시 조회할 필요가 없습니다.

이미지를 호스팅할 곳이 없다면 Pre-Signed 모드를 씁니다. images를 생략하면 업로드용 URL을 돌려줍니다. 이미지 수집에서 다룹니다.

4. 결과 받기

두 가지 방법이 있습니다.

Polling (권장): GET /reports/{report_id}로 상태를 확인합니다. 신뢰 가능한 완료 확인은 이 폴링으로 하세요.
Webhook: 완료 시 report.completed 이벤트가 callback_url로 전송됩니다. 이벤트 알림용입니다. Webhooks.

share_url은 생성 시점에 이미 받았으므로, 폴링은 "공개 리포트가 열람 가능해졌는지"만 확인하면 됩니다. 열람 가능 여부는 GET /reports/{report_id}의 status가 published가 되었는지로 판단합니다. summary_status(complete/partial)는 게시 여부가 아니라 필수 슬롯이 모두 성공했는지를 알려주는 별도의 품질 신호입니다. share_url을 다시 조회할 필요는 없습니다.

curl https://app.atrace.ai/api/v1/reports/rpt_01HXEXAMPLE \
  -H "Authorization: Bearer $ATRACE_API_KEY"

미리 저장해 둔 share_url은 분석이 끝나면 자동으로 열람 가능해집니다.

0. 키 발급/온보딩

1. 인증

2. 호스트와 모드

3. 첫 호출 — 리포트 생성

4. 결과 받기

5. 멱등성

다음 단계

퀵스타트 — 예제 리포트 만들기

리포트 생성 흐름

이미지 수집

에러 처리

On this page