이미지 수집

분석에 쓰는 이미지 출처는 모드에 따라 다릅니다. 클라이언트는 어느 모드에서도 이미지 바이트를 ATRACE Report API 요청 본문으로 직접 보내지 않습니다.

두 가지 모드

모드 A — 고객 URL

자사 스토리지의 공개 이미지 URL을 줄 수 있을 때 사용합니다.

• POST /reports의 images[].source.url에 URL을 넣습니다. 자체 자산 ID가 있으면 images[].source.client_asset_id도 함께 보낼 수 있습니다.
• URL은 HTTPS 공개 URL이어야 하고, 사용자명·비밀번호를 포함할 수 없습니다. 리디렉션은 최대 3회까지 허용되며 매 대상 URL을 다시 검증합니다. 20MB 이하의 성공 이미지 응답이 15초 안에 반환되어야 합니다.
• 조건을 만족하는 URL을 수락하면 해당 슬롯의 분석이 시작됩니다.
• GET /reports/{id}는 제출한 URL 문자열과 client_asset_id를 asset.source에 그대로 반환하므로 파트너 화면에서도 같은 URL을 사용할 수 있습니다.

자체 리포트 화면에 원본 이미지를 표시하려면 이 모드를 권장합니다. URL은 리포트를 사용할 기간 동안 파트너 시스템에서 접근 가능하게 유지하세요.

모드 B — ATRACE 발급 업로드 URL

이미지를 호스팅할 곳이 없을 때 사용합니다.

1. POST /reports를 images 없이 호출하면 upload_targets[]를 받습니다. 각 항목에는 업로드용 PUT URL과 그 원본을 식별하는 고유 UUID asset_id가 있습니다. 타이어 4개 위치 × {tread, sidewall} = 8개 슬롯 전체가 항상 발급됩니다.
2. 실제로 촬영한 슬롯의 upload_url에만 이미지를 PUT 합니다. 이미지 바이트는 ATRACE Report API 요청 본문을 거치지 않습니다.
3. POST /reports/{id}/images로 실제 업로드한 asset_id와 해당 슬롯을 함께 등록하면 분석이 시작됩니다. 이미 성공한 슬롯에 새 원본을 등록하면 409(slot_already_succeeded)가 반환됩니다.

{
  "images": [
    {
      "asset_id": "1d2f4836-12f8-4bde-9e51-1aac3d848a50",
      "module_type": "tire",
      "slot": { "position": "front_left", "image_type": "tread" }
    }
  ]
}

사이드월 위치는 고정이 아닙니다. 현장 요원이 공간 제약으로 특정 방향만 촬영할 수 있어, 사이드월 2장이 (앞좌 + 뒤우) 등 어떤 조합으로든 올 수 있습니다. 그래서 8개 슬롯을 모두 발급하고 파트너 앱은 실제 촬영한 슬롯에만 업로드·등록합니다. 사이드월의 좌·우를 알 수 없으면 좌·우 중 한쪽을 임의로 선택해 업로드해도 됩니다.

Pre-Signed 업로드 규약

upload_url은 ATRACE가 발급한 서명 업로드 URL입니다.

• 메서드: HTTP PUT — 원본 이미지 바이트를 본문에 그대로 실어 보냅니다.
• Content-Type: image/jpeg 또는 image/png.
• Cache-Control: 응답의 required_headers가 안내하는 max-age=60을 그대로 보내시면 됩니다. 더 엄격한 값도 허용됩니다(아래 표).
• 성공 응답: 200.
• 만료: 발급 후 2시간(7200초).

허용되는 Cache-Control 값

판정 기준은 "재검증 없이 재사용해도 되는 시간이 60초 이하인가" 하나입니다. required_headers가 안내하는 max-age=60이 기본값이고, 그보다 엄격한 값도 그대로 통과합니다.

만료·재촬영·교체

업로드 URL이 만료됐거나 재촬영해야 하면 기존 URL이나 asset_id를 재사용하지 않습니다.

1. POST /reports/{id}/upload-targets에 필요한 slots를 보내 새 타깃을 발급받습니다.
2. 새 upload_url에 이미지를 PUT 합니다.
3. 새 asset_id와 슬롯을 POST /reports/{id}/images?replace=true에 등록합니다.

{
  "slots": [
    {
      "module_type": "tire",
      "slot": { "position": "front_left", "image_type": "tread" }
    }
  ]
}

현재 슬롯에 이미 적용된 **같은 asset_id**로 /images 등록을 재시도하는 것은 멱등입니다. 반면 재촬영은 항상 새 타깃을 발급받아야 합니다. 교체 또는 재분석 중에는 기존 공개 공유 링크가 일시적으로 열리지 않고, 새 분석이 성공하면 자동으로 다시 공개됩니다.

ATRACE 발급 URL로 올린 자산은 GET /reports/{id}에서 다음처럼 표시됩니다.

{
  "asset_id": "1d2f4836-12f8-4bde-9e51-1aac3d848a50",
  "source": {
    "kind": "atrace_upload",
    "url": null,
    "client_asset_id": null
  }
}

이 모드의 업로드 URL은 업로드 작업을 위한 단기 URL이며 리포트 표시용 원본 URL 계약이 아닙니다. asset_id로 URL을 조합하지 마세요. 자체 렌더링 화면에서 원본 이미지가 필요하다면 고객 URL 모드를 사용하세요.

클라이언트는 이미지 바이트를 API 요청 본문으로 직접 보내지 않습니다

/images 엔드포인트는 참조(asset_id·슬롯)만 받습니다. Pre-Signed 모드의 클라이언트는 원본 바이트를 업로드 타깃 URL로 직접 PUT 합니다.

이미지 요구사항

• 포맷: PNG 또는 JPEG.
• 해상도: 가급적 Full HD(1920×1080)급 이상을 권장합니다.
• JPEG 압축 품질: 규격 인식과 트레드 측정 정확도를 위해 0.95 수준을 권장합니다.
• 회전: 클라이언트가 EXIF 회전을 보정할 필요가 없습니다. AI가 시각적으로 회전을 판단하고, 리포트 시각화 시 이미지를 바로 세웁니다. HEIC/EXIF 정규화도 불필요합니다.

모듈 스코프 슬롯 키

이미지는 { module_type, slot }로 식별합니다. slot의 형태는 모듈마다 다릅니다.

{
  "module_type": "tire",
  "slot": { "position": "front_left", "image_type": "tread" }
}

현재는 tire 모듈만 지원합니다. 계기판(dashboard)·번호판(plate)·외장(exterior)은 추후 확장 예정이며, 위 표는 참고용입니다. position은 타이어 전용이며 slot 안에 들어갑니다. 새 모듈이 추가돼도 기존 계약은 깨지지 않습니다.

캡처 구성은 템플릿이 정한다

리포트가 어떤 이미지를 몇 장 요구하는지는 템플릿이 정의합니다(고정 8장이 아닙니다).

template 필드를 생략하면 기본 템플릿 tire_4t_2s가 적용됩니다. 성공 조건은 GET /reports/{id} 응답의 template.requirements[]에 생성 당시 버전과 함께 고정됩니다. 예를 들어 tire_4t_2s의 사이드월은 네 위치 중 특정 두 곳이 아니라 아무 두 슬롯의 성공이 조건입니다.

다음 단계