hbyang 7f18206f36 docs: API 가이드 부제와 갱신일 제거

2026-08-18 12:57:46 +09:00

7.3 KiB

Raw Blame History

저작권 탭 API 연동 가이드

1. 연동 요약

저작권 탭은 아래 API를 한 번 호출해 렌더링한다.

POST https://plagiarism.o2o.kr/v1/plagiarism/review

이 API는 내부적으로 표절 탐지, AI 생성 의심도 산출, 판례 비교를 수행하지만 앱에는 화면에 필요한 요약값만 반환한다. 상세 탐지 API의 matches, evidence_spans, extracted_elements, score_semantics, 모델 정보 등은 응답하지 않는다.

2. 공통 규격

항목	값
Base URL	`https://plagiarism.o2o.kr`
Method	`POST`
Path	`/v1/plagiarism/review`
Content-Type	`application/json; charset=utf-8`
인증	운영에서 설정된 경우 `X-API-Key` 헤더 사용
시간	ISO 8601 UTC

3. 요청

최소 요청

{
  "doc_id": "episode-001",
  "text": "창밖으로 보이는 숲은 오늘따라 유난히 푸르게 보였다."
}

전체 요청

{
  "doc_id": "episode-001",
  "text": "검사할 에피소드 본문 전체",
  "metadata": {
    "title": "에피소드 1",
    "author": "홍길동",
    "genre": "자서전"
  },
  "options": {
    "threshold": null,
    "top_k": 5,
    "autobiography_mode": null
  },
  "legal_context": {
    "work_type": "literary",
    "access_evidence": null,
    "protected_expression_reviewed": false,
    "rights_verified": false
  }
}

필드	타입	필수	설명
`doc_id`	string	O	호출 측 문서 또는 에피소드 ID
`text`	string	O	검사할 본문, 1자 이상
`metadata`	object	X	제목, 저자, 장르 등 표시·추적용 메타데이터
`options.threshold`	number/null	X	탐지 임계값. 미지정 시 서버 기본값
`options.top_k`	integer	X	내부 비교 후보 수, 기본 5
`options.autobiography_mode`	boolean/null	X	자서전 특화 전처리 사용 여부
`legal_context`	object	X	사람이 확인한 접근 가능성·권리관계 등의 법적 맥락

일반적인 저작권 탭 연동에서는 doc_id, text만 전달하면 된다.

4. 응답

침해 의심이 낮은 예시

{
  "doc_id": "episode-001",
  "copyright": {
    "originality_percent": 98,
    "similarity_percent": 2,
    "compared_count": 31560,
    "has_suspicion": false,
    "description": "등록 원문 검색 세그먼트 31,560건과 대조한 결과 표절 의심 구간이 없습니다."
  },
  "similar_sentences": {
    "count": 0,
    "label": "0건"
  },
  "ai_generation_suspicion": {
    "level": "low",
    "label": "낮음"
  },
  "legal_judgment": {
    "status": "low",
    "label": "등록 판례 기준 침해 의심 낮음",
    "summary": "등록 코퍼스에서 일치 증거가 확인되지 않아 판례 기반 침해 의심을 제시하지 않습니다. 다만 미매칭은 비침해 확정이 아닙니다.",
    "precedent_ids": []
  },
  "analyzed_at": "2026-08-18T03:00:00Z"
}

판례에 따른 침해 의심 예시

{
  "doc_id": "episode-002",
  "copyright": {
    "originality_percent": 10,
    "similarity_percent": 90,
    "compared_count": 31560,
    "has_suspicion": true,
    "description": "등록 원문 검색 세그먼트 31,560건과 대조한 결과 표절 의심 구간이 확인되었습니다."
  },
  "similar_sentences": {
    "count": 5,
    "label": "5건"
  },
  "ai_generation_suspicion": {
    "level": "unknown",
    "label": "확인 불가"
  },
  "legal_judgment": {
    "status": "suspected",
    "label": "판례에 비추어 저작권 침해 의심",
    "summary": "2011고단6934, 2013노232 판례의 판단 기준과 탐지 증거를 비교한 결과, 표현 일치 범위가 커 저작권 침해가 의심되어 추가 검토가 필요합니다.",
    "precedent_ids": ["2011고단6934", "2013노232"]
  },
  "analyzed_at": "2026-08-18T03:01:00Z"
}

5. 화면 매핑

화면 항목	응답 경로	표시 방법
독창성 98%	`copyright.originality_percent`	숫자 뒤 `%`
저작권 · 유사도 2%	`copyright.similarity_percent`	숫자 뒤 `%`
대조 결과 설명	`copyright.description`	문자열 그대로 표시
유사 문장 0건	`similar_sentences.label`	문자열 그대로 표시
AI 생성 의심도 낮음	`ai_generation_suspicion.label`	문자열 그대로 표시
판례 판단 제목	`legal_judgment.label`	의심 또는 검토 필요 시 표시
판례 판단 근거	`legal_judgment.summary`	제목 아래 설명으로 표시
근거 판례	`legal_judgment.precedent_ids[]`	사건번호 배지로 표시

compared_count는 현재 등록된 검색 세그먼트 수다. 원천 PDF 파일 수 또는 외부 공개 문서 전체 건수로 바꾸어 표기하지 않는다.

6. 상태값

`legal_judgment.status`

값	의미	권장 UI
`suspected`	판례와 탐지 증거에 비추어 침해 의심	빨간색 또는 주의 표시
`low`	현재 증거에서 침해 의심 낮음	기본 또는 정상 표시
`review_required`	관련 판례에 따른 추가 확인 필요	노란색 검토 표시
`unavailable`	등록 판례가 없어 비교 불가	회색 안내 표시

`ai_generation_suspicion.level`

값	한글 라벨
`low`	낮음
`medium`	중간
`high`	높음
`unknown`	확인 불가

unknown을 임의로 low로 바꾸지 않는다. 학습 모델이 없거나 채점할 수 없는 경우다.

7. 호출 예시

curl -X POST 'https://plagiarism.o2o.kr/v1/plagiarism/review' \
  -H 'Content-Type: application/json' \
  -d '{
    "doc_id": "episode-001",
    "text": "검사할 에피소드 본문"
  }'

const response = await fetch(
  "https://plagiarism.o2o.kr/v1/plagiarism/review",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ doc_id: episodeId, text: episodeText })
  }
);

if (!response.ok) throw new Error(`저작권 검사 실패: ${response.status}`);
const result = await response.json();

originality.textContent = `${result.copyright.originality_percent}%`;
copyrightDescription.textContent = result.copyright.description;
similarSentenceCount.textContent = result.similar_sentences.label;
aiSuspicion.textContent = result.ai_generation_suspicion.label;
legalTitle.textContent = result.legal_judgment.label;
legalDescription.textContent = result.legal_judgment.summary;

8. 오류 처리

HTTP	의미	처리
`200`	검사 완료	응답으로 화면 갱신
`401`	API 키 누락 또는 불일치	인증 설정 확인
`422`	요청 형식 오류 또는 빈 본문	입력값 확인
`503`	탐지 또는 판례 검토 기능 사용 불가	잠시 후 재시도
`500`	서버 내부 오류	오류 로그와 `doc_id` 전달

앱은 검사 중 로딩 상태를 표시하고, 실패하면 직전 성공 결과를 새 결과처럼 표시하지 않는다.

9. 상세 API

이 결과는 등록 코퍼스와 판례에 기반한 검토 보조 의견이며 법률상 침해 확정이 아니다.

7.3 KiB Raw Blame History