Skip to content

images-process.md

Latest commit

 

History

History
83 lines (69 loc) · 2.63 KB

images-process.md

File metadata and controls

83 lines (69 loc) · 2.63 KB
Raw

AI Server — 이미지 보호 처리 API 명세 (POST /api/v1/images/process)

상태: Backend 초안 (AI 담당자 원본 문서 미수령 상태에서 인터페이스 계약서 기준으로 작성). AI 담당자 확정 시 이 파일을 원본으로 교체할 것. 관련 계약서: docs/INTERFACE-FOR-AISERVER.md

요청

POST http://52.79.247.230:8001/api/v1/images/process
Content-Type: application/json

{
  "source_object_key": "uploads/{task_id}.jpg",
  "source_download_url": "https://...(presigned GET, 15분)...",
  "result_object_key": "protected/{task_id}.png",
  "result_upload_url": "https://...(presigned PUT, 15분)...",
  "result_content_type": "image/png",
  "analysis_image_sha256": "8ac1e73c...",
  "selected_regions": [
    {
      "detection_id": "det_plate_001",
      "risk_group": "VEHICLE",
      "polygon": [[820,750],[1100,750],[1100,840],[820,840]]
    }
  ],
  "remove_metadata": true
}
필드 설명
source_download_url 원본 다운로드용 presigned GET (만료 15분)
result_upload_url 결과 업로드용 presigned PUT (만료 15분). PUT 시 Content-Type: image/png 헤더 필수 (서명에 포함됨)
result_content_type 항상 image/png
analysis_image_sha256 analyze 응답의 image.sha256. 원본 무결성 검증용
selected_regions 사용자가 선택한 마스킹 영역. 빈 배열 가능 (딥페이크 방지만 적용)
remove_metadata EXIF/GPS 메타데이터 제거 여부. 항상 전달됨

AI 서버 처리 순서

  1. source_download_url로 원본 다운로드
  2. sha256 검증 (analysis_image_sha256과 비교)
  3. selected_regions 마스킹 + 딥페이크 방지 처리 + (옵션) 메타데이터 제거
  4. 결과 PNG를 result_upload_url로 PUT 업로드 (Content-Type: image/png)
  5. 응답 반환

응답 (200)

{
  "status": "SUCCESS",
  "result_object_key": "protected/{task_id}.png",
  "masked_region_count": 1,
  "deepfake_protection": {
    "applied": true,
    "method": "adversarial_noise"
  },
  "metadata_removed": true,
  "request_id": "req_01JZ456DEF"
}

에러 응답 (4xx/5xx)

{
  "error": {
    "code": "DEEPFAKE_PROTECTION_FAILED",
    "message": "딥페이크 방지 처리에 실패했습니다.",
    "request_id": "req_01JZ123ABC"
  }
}

5xx는 Backend가 자동 재시도(최대 1회, 30초 후), 4xx는 재시도하지 않는다. 결과 키가 protected/{task_id}.png로 결정적이므로 재실행해도 안전(멱등).

타임아웃

Backend 측 httpx 타임아웃 300초 (GPU 처리 시간 고려). 초과 시 FAILURE(AI_SERVER_TIMEOUT).