# 한국형 정신건강 필터 API 한국어 사용자 입력에서 정신건강 위험 신호를 10축 × 5단계로 분류하는 API. - **모델 ID**: `mental_health` - **Base URL**: `https://api.corepin.ai` ## 1. 엔드포인트 | Method | Path | 인증 | 설명 | |---|---|:-:|---| | GET | `/v1/mental_health/axes` | – | 10축 + 5단계 + 권고 액션 카탈로그 | | POST | `/v1/mental_health/classify` | ✓ | 단건 분류 (sync 기본 / `async_mode: true` fire-and-forget) | | POST | `/v1/mental_health/batch` | ✓ | 1 ~ 100 텍스트 일괄 분류 | | GET | `/v1/mental_health/history` | ✓ | 분류 이력 (본문 미저장) | ## 2. POST `/v1/mental_health/classify` **Request**: ```json { "text": "분류할 사용자 입력 (1 ~ 32,768자)", "context_turns": [ {"role": "user", "text": "직전 사용자 발화"}, {"role": "assistant", "text": "직전 챗봇 응답"} ], "async_mode": false, "return_text": false } ``` | 필드 | 타입 | 기본 | 설명 | |---|---|---|---| | `text` | string | (필수) | 1 ~ 32,768자 | | `context_turns` | object[] | `null` | 직전 대화 맥락. `role` = `user` / `assistant`, `text` ≤ 8,000자. 최대 12 user + 4 assistant 턴. | | `async_mode` | bool | `false` | `true`면 즉시 202 반환, 백그라운드 분류 + 운영자 알림 (§6 참고). | | `return_text` | bool | `false` | 응답에 입력 본문 echo 여부. | ## 3. POST `/v1/mental_health/batch` ```json { "texts": ["오늘 너무 힘들어", "..."], "return_text": false } ``` - 1 ~ 100 텍스트. 각 항목 1 ~ 32,768자. - 각 항목당 호출 1건 차감. `async_mode` 미지원. ## 4. 응답 (sync) ```json { "risk_level": "acute", "recommended_action": "emergency_1393", "axes": [ {"axis": "MH01", "name_ko": "자살 사고", "level": "acute"}, {"axis": "MH02", "name_ko": "비자살 자해", "level": "none"}, "..." ], "active_axes": [ {"axis": "MH01", "name_ko": "자살 사고", "level": "acute"}, {"axis": "MH10", "name_ko": "급성 위기", "level": "acute"} ], "meta": { "model_id": "mental_health", "model_version": "mh-2026.05", "processing_time_ms": 15.5, "request_id": "...", "quota_remaining": 99996 } } ``` | 필드 | 타입 | 설명 | |---|---|---| | `risk_level` | string | 종합 위험 등급. `none` / `mild` / `moderate` / `severe` / `acute`. | | `recommended_action` | string | 권고 액션 코드 (§5). | | `axes` | object[] | 10축 전체. `{axis, name_ko, level}`. | | `active_axes` | object[] | `level != "none"`만 추린 축. UI 카드용. | | `text` | string \| null | `return_text=false`면 null. | | `meta.*` | – | 공통 응답 메타. | ## 5. 응답 (async_mode=true) `async_mode: true` 호출은 즉시 202 반환: ```json { "accepted": true, "mode": "async", "request_id": "abc123...", "quota_remaining": 996, "note": "백그라운드에서 분류 후 운영자에게 알림이 자동 분배돼요. 분류 결과는 클라이언트에 반환되지 않아요." } ``` | 시나리오 | 권장 모드 | |---|---| | 챗봇 입력 가드레일 (운영자 알림만 필요) | `async_mode: true` | | 응답에 1393 자원 카드 등 즉시 노출 | sync (기본) | | 의료 reviewer가 분류 결과를 즉시 받아야 함 | sync (기본) | ## 6. 10축 | 코드 | 한국어 | 알림 우선순위 | |---|---|:-:| | `MH01` | 자살 사고 | **high** | | `MH02` | 비자살 자해 | **high** | | `MH03` | AI 파라소셜 의존 | med | | `MH04` | AI 망상 강화 | med | | `MH05` | 정신증 신호 | **high** | | `MH06` | 조증 신호 | med | | `MH07` | 섭식장애 | med | | `MH08` | 약물·알코올 | med | | `MH09` | 현실감 상실 (DPDR) | med | | **`MH10`** | **급성 위기** | **critical** | `GET /v1/mental_health/axes`에서 한글 설명·5단계·권고 액션을 받을 수 있어요. ## 7. 5단계 (ordinal) | 코드 | 한글 | |---|---| | `none` | 해당 없음 | | `mild` | 약함 | | `moderate` | 중간 | | `severe` | 심각 | | `acute` | 급성 | ## 8. 권고 액션 | 액션 | 의미 | SLA | |---|---|---| | `monitor` | 모니터링 (알림 없음) | – | | `soft_resource` | 자원 안내 (의료/상담 카드 노출) | – | | `warn_operator` | 운영자 큐 등록 | 4 ~ 24h | | `human_review` | 임상 reviewer 즉시 큐 | 즉시 | | `emergency_1393` | **1393 자살예방상담전화 카드 우선 노출 + 운영자 즉시 알림** | 즉시 | ## 9. GET `/v1/mental_health/history` 본문 미저장 분류 이력. risk_level / recommended_action / active_axes 카운트만 반환. 쿼리: `from_ts` / `to_ts` (unix sec) · `limit` (1 ~ 500) · `offset`. ## 10. 오류 응답 공통 오류 envelope·인증·rate limit 오류는 [빠른 시작 §6](/docs/quickstart) 참고. 추가: | HTTP | code | 의미 | |---|---|---| | 503 | `model_unavailable` | 정신건강 모델 일시 사용 불가. 잠시 후 재시도. | ## 11. 코드 예제 ### Python ```python import os, httpx def screen(text: str, context: list[dict] | None = None) -> dict: r = httpx.post( "https://api.corepin.ai/v1/mental_health/classify", headers={"Authorization": f"Bearer {os.environ['COREPIN_API_KEY']}"}, json={"text": text, "context_turns": context or []}, timeout=10.0, ) r.raise_for_status() return r.json() # LLM 호출 앞에 끼우는 패턴 def screen_then_chat(user_text: str, context: list, lm) -> str: r = screen(user_text, context) if r["recommended_action"] == "emergency_1393": prepend = "1393 자살예방상담전화 (24시간 무료): https://www.lifeline.or.kr/\n\n" else: prepend = "" return prepend + lm.chat(user_text, context) ``` ### JavaScript ```ts const r = await fetch(`${BASE}/v1/mental_health/classify`, { method: "POST", headers: { "Authorization": `Bearer ${process.env.COREPIN_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ text, context_turns: context }), }); const { risk_level, recommended_action, active_axes } = await r.json(); if (recommended_action === "emergency_1393") { // 1393 카드 우선 노출 + 운영자 알림 } ```