유메 검증 API v1

자사 서비스의 AI 답변을 사용자에게 보여주기 전에 유메로 사실 여부를 확인하세요. 응답에는 주장별 판정·근거·출처와, 인용된 법령·판례·문헌이 공식 자료에 없을 때의 부존재 신뢰도가 함께 들어 있습니다.

시작하기

1. 유메에 가입하고 계정 메뉴의 API 키에서 키를 발급받습니다. 키는 발급할 때 한 번만 보여주므로 안전한 곳에 보관하세요.
2. 모든 요청에 Authorization: Bearer <API 키> 헤더를 붙입니다.
3. 키는 서버에서만 사용하세요. 브라우저·앱에 넣으면 누구나 키를 볼 수 있습니다.

POST /v1/verify

텍스트 하나를 검증합니다. 검증에는 보통 10~40초가 걸립니다. wait를 주면 결과가 나올 때까지(최대 60초) 연결을 유지하고, 주지 않으면 즉시 202와 id를 돌려주므로 GET /v1/verify/:id로 조회하세요.

curl -X POST https://www.yume-reamer.com/v1/verify \
  -H "Authorization: Bearer yume_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "대법원 2019다123456 판결에 따르면 …", "wait": true}'

Node.js

const res = await fetch("https://www.yume-reamer.com/v1/verify", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.YUME_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ text, wait: 30 }),
});
let job = await res.json();
while (job.status === "pending") {
  await new Promise((r) => setTimeout(r, 3000));
  job = await (await fetch(`https://www.yume-reamer.com/v1/verify/${job.id}`, { headers: { Authorization: `Bearer ${process.env.YUME_API_KEY}` } })).json();
}

Python

import os, time, requests
H = {"Authorization": f"Bearer {os.environ['YUME_API_KEY']}"}
job = requests.post("https://www.yume-reamer.com/v1/verify", json={"text": text, "wait": 30}, headers=H).json()
while job["status"] == "pending":
    time.sleep(3)
    job = requests.get(f"https://www.yume-reamer.com/v1/verify/{job['id']}", headers=H).json()

응답

{
  "id": "9f2c1a7b3d4e5f60",
  "status": "done",              // pending | done | error
  "cached": false,
  "created_at": "2026-09-12T03:10:00.000Z",
  "completed_at": "2026-09-12T03:10:21.000Z",
  "result": {
    "verdict": { "label": "부분적으로 부정확", "tone": "false", "detail": "3개 중 1개가 사실과 다릅니다 — …" },
    "domain": "법률",
    "claims": [
      {
        "text": "대법원 2019다123456 판결은 …",
        "domain": "법률",
        "verdict": "false",           // confirmed | false | uncertain
        "verified_via": "nec",        // official | nec | web | research | unavailable
        "explanation": "인용된 ‘2019다123456’은(는) 존재하지 않을 가능성이 높습니다(부존재 신뢰도 0.735). …",
        "sources": [],
        "legal_ref": { "type": "case", "case_number": "2019다123456" },
        "nec": {
          "identifier": { "type": "case", "canonical": "2019다123456", "searchSpace": "대법원 판결" },
          "score": 0.735, "grade": "nonexistent", "gradeLabel": "부존재 확실", "threshold": 0.7,
          "weights": { "w1": 0.65, "w2": 0.2, "w3": 0.15 },
          "coverage": { "value": 0.9, "estimated": true, "searched": [ … ] },
          "formatError": { "value": 0, "skippedSearch": false, "checks": [] },
          "proximity": { "value": 0, "similar": [] },
          "uncovered": [],
          "summary": "…"
        }
      }
    ]
  },
  "usage": { "used": 12, "quota": 1000, "remaining": 988, "resets_at": "2026-09-30T15:00:00.000Z" }
}

verified_via

부존재 신뢰도(NEC)

AI가 존재하지 않는 판례·법령·논문을 지어내거나, 있지도 않은 통계·사건을 사실처럼 말하는 경우가 있습니다. 데이터베이스에서 "못 찾았다"는 사실만으로 곧바로 "없다"고 단정할 수는 없으므로, 유메는 다음 세 지표로 부존재 신뢰도를 산출합니다.

식별자(법령·판례·DOI 등)는 공식 레지스트리가 검색공간입니다. 식별자가 없는 일반 사실 주장은 "이 주장이 사실이라면 어디에 기록되어 있어야 하는가"를 검색공간으로 삼습니다 — 공공 통계·공시처럼 사실이라면 반드시 공표되는 영역을 충분히 탐색하고도 찾지 못하면 부존재 신뢰도가 임계값을 넘어 사실과 다름으로 판정합니다. 반대로 비공개 내부 정보나 개인 경험처럼 애초에 기록이 남지 않는 주장은 탐색 커버리지가 낮아 부존재로 단정하지 않고 확인되지 않음으로 남습니다.

NEC = w1·C + w2·F + w3·(1 − P)

• C 탐색 커버리지 — 탐색한 자료가 해당 식별자의 검색공간을 얼마나 덮는지(기관별 공표 수록 범위 기반 추정값)
• F 형식오류 지수 — 체계·범위·시간·발급규칙 정합성 검사 결과. 형식상 존재할 수 없으면 탐색 없이 판정
• P 유사항목 근접도 — 비슷한 실재 항목(한 글자 틀린 사건번호 등)이 있을수록 높음

grade가 nonexistent(NEC ≥ 0.7)이면 해당 주장은 false로, unverifiable이면 uncovered에 아직 확인하지 못한 영역과 확인 방법이 담깁니다. 지원 식별자: 판례 사건번호, 헌법재판소 사건번호, 법령·조문, DOI, arXiv, PMID, ISBN.

GET /v1/verify/:id

같은 계정의 키로 요청한 검증만 조회할 수 있습니다. 조회는 과금되지 않습니다.

GET /v1/usage

{ "key": { "label": "운영 서버", "prefix": "yume_live_ab12cd…" }, "rate_per_min": 30,
  "month": { "used": 12, "quota": 1000, "remaining": 988, "resets_at": "…" } }

한도와 과금

• 과금 단위는 받아들여진 POST /v1/verify 1건입니다(같은 텍스트의 캐시 재사용 포함). 입력 오류·인증 실패·한도 초과로 거절된 요청은 과금되지 않습니다.
• 월 한도는 매달 1일 0시(KST)에 초기화됩니다. 한도 상향과 단가 협의는 reamer@d-reamer.com로 문의해주세요.
• 키별 분당 요청 한도가 있으며, 초과 시 429와 Retry-After 헤더를 돌려줍니다.

오류

{ "error": { "code": "quota_exceeded", "message": "…" } }

데이터 처리

API로 보낸 텍스트는 검증과 과금·분쟁 대응을 위해 1년간 보관되며, 별도 계약으로 허용한 경우를 제외하고 데이터셋 제공 대상에 포함되지 않습니다. 텍스트에 개인정보가 들어간다면 귀사 이용자에게 필요한 고지·동의를 받아주세요. 자세한 내용은 개인정보처리방침과 이용약관을 참고하세요.