# 빠른 시작
Corepin API는 한 키로 라이브 모델 모두를 호출할 수 있어요. 한국형 개인정보 필터, 사내 문서 등급·유형 분류 (DLP), 한국형 유해발화 필터, 한국형 캐릭터챗 (OpenAI·Anthropic 호환), 한국형 정신건강 위험 신호 필터가 운영 중이에요.
- **Base URL**: `https://api.corepin.ai`
- **인증**: `Authorization: Bearer sk_live_…`
- **OpenAPI**: `GET /openapi.json` · 인터랙티브 문서는 `/_internal/docs`
## 1. 키 받기
회원가입 후 [대시보드](/dashboard)에서 키를 발급받으세요. 가입 시 무료 티어 키 한 개가 자동으로 발급돼요. raw 토큰은 발급 직후 한 번만 보여드리고, DB에는 SHA-256 해시만 저장돼요. 분실하면 새로 발급해야 해요.
```bash
export COREPIN_API_KEY=sk_live_…
```
## 2. 첫 호출 — 헬스체크
```bash
curl https://api.corepin.ai/v1/health
# {"status":"ok","models_loaded":["chat","dlp","mental_health","moderation","pii"],
# "models_live":["pii","dlp","moderation","chat","mental_health"], ...}
```
## 3. 모델 디렉토리
```bash
curl https://api.corepin.ai/v1/models | jq
```
응답에는 라이브 모델 메타데이터(이름·버전·도메인·엔드포인트)가 담겨 있어요. 새 모델이 늘어나도 클라이언트 코드 변경 없이 디렉토리만 다시 받으면 돼요.
## 4. 인증
모든 추론 엔드포인트는 Bearer 토큰을 요구해요.
```http
Authorization: Bearer sk_live_<22 chars>
```
키는 두 가지 prefix로 구분돼요:
- `sk_live_…` — 운영 트래픽
- `sk_test_…` — 통합 테스트 (현재 동일 모델 사용)
## 5. 요금제 · 한도
가입 직후 기본 상태는 **무료** 입니다. 신용카드를 등록하면 자동으로 **후불** 로 전환되고 한도가 사라져요.
| 상태 | 분당 호출 | 월 호출 한도 | 청구 |
|---|---:|---:|---|
| **무료** (기본) | 60회 | **1,000회** | 없음 |
| **후불** (카드 등록) | 사실상 무제한 | **한도 없음** | 매월 1일에 사용량 합산 청구 |
- **분당 한도 초과** → `429 rate_limited` + `Retry-After` 헤더
- **월 한도 소진** (무료) → `429 quota_exceeded` + `Retry-After: 86400`. [대시보드 → 청구](/dashboard/billing)에서 카드 등록하면 즉시 후불 전환.
- **한 키 = 모델 통합 청구**: PII / DLP / 유해발화 / 정신건강 모든 호출이 같은 월 한도·청구를 공유해요. 모델별 사용량은 [대시보드 → 사용량](/dashboard/usage)에서 분리 확인할 수 있어요.
- **API 키당 동시 호출 한도** — 한 키로 동시에 처리되는 요청 수가 너무 많으면 `429 concurrency_limit` 응답. 운영 중 spike 시 한 사용자가 모든 워커를 점유하지 못하도록 보호. 짧은 backoff 후 재시도하면 정상 처리돼요.
응답 `meta.quota_remaining` 으로 잔량 추적 가능 (후불 사용자는 큰 정수가 그대로 반환).
## 6. 에러 응답 (공통)
모든 에러는 동일한 envelope:
```json
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded (60 req/min)",
"request_id": "..."
}
}
```
| HTTP | code | 의미 |
|---|---|---|
| 401 | `missing_api_key` | `Authorization` 헤더 누락 |
| 401 | `invalid_api_key` | 키가 잘못됐거나 폐기됨 |
| 422 | `invalid_request` | 스키마/길이/제어문자 검증 실패 |
| 429 | `rate_limited` | 분당 RPM 초과 |
| 429 | `quota_exceeded` | 월 한도 소진 |
| 429 | `concurrency_limit` | 한 키의 동시 처리 한도 초과 — 짧은 backoff 후 재시도 |
| 503 | `overloaded` | 일시적 서버 과부하 (처리 큐 가득). 잠시 후 재시도 |
| 500 | `inference_failed` | 모델 처리 실패 (재시도 권장) |
| 500 | `internal_error` | 그 외 unhandled. `request_id` 첨부해 운영팀에 알려주세요 |
`X-Request-ID` 응답 헤더는 모든 응답(성공/실패)에 포함돼요. 문의 시 항상 같이 보내주세요.
## 7. 입력 제약 (공통)
- **텍스트 길이**: 1 ~ 32,768 자
- **배치 크기**: 1 ~ 100 텍스트 (PII / DLP / 유해발화 / 정신건강 지원)
- **인코딩**: UTF-8
- **금지 문자**: NUL/BEL/DEL/`\x01`–`\x1F` (탭/개행/CR 제외)
- **자동 처리**: zero-width 문자 (`` 등) 는 NFC 정규화 + 제거
## 8. 다음 단계
- **한국형 개인정보 필터** — [`/docs/pii`](/docs/pii) · 17 카테고리 · 개인정보보호법 §24-2 고유식별정보 9종
- **한국형 문서보안 필터** — [`/docs/dlp`](/docs/dlp) · 6등급 · 11 유형 · 자동 보강 추론
- **한국형 유해발화 필터** — [`/docs/moderation`](/docs/moderation) · 10라벨 + NEG · LLM·에이전트 입력 가드레일 · 3-tier cascade
- **한국형 정신건강 위험 신호 필터** — [`/docs/mental_health`](/docs/mental_health) · 10축 5단계 · LLM 가드레일 · 본문 미저장
- **앱·프로젝트 관리** — [`/docs/tenants`](/docs/tenants) · 여러 앱·프로젝트 별 차단 정책 분리
- **요금제** — [`/docs/billing`](/docs/billing) · 한도 변경 요청
- **대시보드** — [`/dashboard`](/dashboard) · 사용량·검출 이력·키 관리
문의: <support@corepin.ai>