o2o-plagiarism-ai/docs/API_GUIDE_BAIKAL.md

저작권 탭 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": 37891,
    "has_suspicion": false,
    "description": "등록 원문 검색 세그먼트 37,891건과 대조한 결과 표절 의심 구간이 없습니다."
  },
  "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": 37891,
    "has_suspicion": true,
    "description": "등록 원문 검색 세그먼트 37,891건과 대조한 결과 표절 의심 구간이 확인되었습니다."
  },
  "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로 바꾸지 않는다. 학습 모델이 없거나 채점할 수 없는 경우다. 현재 운영 서버에는 한국어 자서전 대조 데이터로 학습한 모델이 적재되어 있어 정상적인 본문에는 low, medium, high 중 하나가 반환된다. 이 값은 AI 작성 확정 판정이 아니라 사람 검토 우선순위를 위한 보조 신호다.

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

관리자 화면에서 일치 원문, 좌표, 점수 구성 등 상세 증거가 필요할 때만 POST /v1/plagiarism/detect를 사용한다. 모바일 저작권 탭은 응답 크기가 작은 POST /v1/plagiarism/review를 사용한다.

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

상세 응답에는 기존 필드 외에 다음 정보가 추가되었다. 모두 추가 필드이므로 기존 /v1/plagiarism/review 연동에는 영향이 없다.

응답 필드	설명
ai_generation	모델 버전, 점수, 구간별 의심도와 주의사항
legal_risk	판례 기반 검토 상태, 인용 사건번호와 A/B/C 검토 등급
score_semantics	검색 점수와 임계값의 의미, 일치 범위
has_similarity_match	등록 코퍼스에서 유사 원문이 확인됐는지 여부
corpus_scope_note	검색 대상 코퍼스 범위 안내
matches[].source_*	일치 원문의 문서·세그먼트·페이지·문자 좌표

10. 판례 조회 API

관리 화면에서 엔진에 적재된 판례를 검색할 때 사용한다. 판례 545건 전체가 검색·인용 후보이며, A/B/C는 제외 기준이 아니라 검토 품질과 직접성을 나타내는 우선순위다.

GET /v1/precedents?q=어문저작물&grade=A&work_type=literary&offset=0&limit=25

쿼리	설명
q	사건번호·제목·판단 요지 검색
grade	A, B, C, unreviewed 중 하나
work_type	저작물 유형 필터
offset, limit	페이지 위치와 개수. limit 최대 100

응답의 loaded_total은 전체 적재 판례 수, graded_total은 사람이 A/B/C 검토를 마친 판례 수다. 각 항목에는 case_id, title, source_url, grade, holding_excerpt 등이 포함된다.

11. 맞춤 요약 API

POST /v1/summary

{
  "text": "요약할 자서전 본문",
  "detail": "standard",
  "emphasis": ["가족", "창업"],
  "max_sentences": 5,
  "use_abstractive": false
}

필드	설명
detail	brief, standard, detailed. 기본 standard
emphasis	우선 반영할 주제·키워드, 최대 10개
ratio	직접 지정할 요약 비율. 지정하면 detail보다 우선
max_sentences	최대 요약 문장 수
use_abstractive	LLM 사용 요청. 사용할 수 없으면 추출 요약으로 폴백

12. 상태 확인 API

GET /v1/health에서 기존 상태값과 함께 다음 필드를 확인할 수 있다.

필드	설명
corpus_size	검색 가능한 전체 세그먼트 수
corpus_documents	적재된 원문 문서 수
index_backend	현재 검색 인덱스 구현
ai_model_ready	학습된 AI 의심도 모델 준비 여부
precedent_count	엔진에 적재된 판례 수