Kinfri API 문서
Kinfri는 글로벌·국산 LLM을 단일 OpenAI 호환 API로 묶어줍니다. 쓰던 OpenAI SDK에서 base_url과 api_key만 바꾸면, 원화 정산·전자세금계산서·한국어 PII 마스킹이 자동으로 따라옵니다.
이미 OpenAI SDK를 쓰고 있다면 코드 두 줄이면 전환이 끝납니다. 아래 퀵스타트로 바로 시작하세요.
10초 퀵스타트
① 콘솔에서 API 키를 발급하고, ② 엔드포인트를 https://api.kinfri.ai/v1 로 바꾸면 끝입니다.
from openai import OpenAI
client = OpenAI(
base_url="https://api.kinfri.ai/v1",
api_key="sk-kf-live-...",
)
resp = client.chat.completions.create(
model="hyperclova-x",
messages=[{"role": "user", "content": "안녕하세요"}],
)
print(resp.choices[0].message.content)인증 & API 키
모든 요청은 Authorization: Bearer <API_KEY> 헤더로 인증합니다. 키는 콘솔 → API 키에서 발급하며, 발급 시 한 번만 전체 값이 표시됩니다.
sk-kf-live-— 운영(프로덕션) 키sk-kf-test-— 테스트 키 (과금되지 않음)
키는 서버 환경변수로만 보관하세요. 클라이언트(브라우저·앱)에 노출하면 즉시 폐기하고 새 키로 회전해야 합니다.
채팅 호출
OpenAI chat.completions 규격을 그대로 사용합니다. model만 Kinfri 모델 ID로 지정하세요.
resp = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "너는 친절한 비서야."},
{"role": "user", "content": "세금계산서 발행 방법 알려줘"},
],
temperature=0.7,
)스트리밍
stream: true를 주면 토큰을 SSE로 실시간 수신합니다. 국산 모델(HyperCLOVA X·Solar)도 동일하게 스트리밍됩니다.
stream = client.chat.completions.create(
model="claude-sonnet-4-6",
messages=[{"role": "user", "content": "긴 글 써줘"}],
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")모델 선택
전체 9종 모델을 같은 코드로 호출합니다. 단가·컨텍스트는 모델 목록에서 확인하세요.
| 모델 ID | 제공사 | 용도 |
|---|---|---|
gpt-5.5 | OpenAI | 범용 플래그십 |
claude-sonnet-4-6 | Anthropic | 균형 추천 기본 |
hyperclova-x | NAVER | 한국어 특화 |
deepseek-v4 | DeepSeek | 초저가 고성능 |
PII 가드레일
워크스페이스에서 가드레일을 켜면, 요청이 업스트림으로 나가기 전에 주민번호·연락처·이메일 등이 비식별화됩니다. 원문은 저장되지 않고 즉시 휘발됩니다. 호출별로 헤더로도 제어할 수 있습니다.
resp = client.chat.completions.create(
model="hyperclova-x",
messages=[{
"role": "user",
"content": "내 주민번호는 900101-1234567",
}],
extra_headers={"X-Kinfri-PII": "on"},
)
# 업스트림 전송 전: 900101-1234567 → ######-#######마스킹 동작은 PII 가드레일 설정에서 유형별로 켜고 끌 수 있습니다.
원화 청구 & 세금계산서
호출 시점 환율로 원화 크레딧에서 차감되며, 응답 usage에 토큰 수가 포함됩니다. 법인 고객은 매월 전자세금계산서가 자동 발행됩니다. 잔액이 0이 되면 호출이 중단되고 미수금은 발생하지 않습니다.
선불 크레딧 방식이므로 미수금이 발생하지 않습니다. 잔액 경고 알림은 설정 → 워크스페이스에서 켤 수 있습니다.
에러 코드
| 코드 | 의미 | 대응 |
|---|---|---|
401 | 인증 실패 | API 키 확인 |
402 | 크레딧 부족 | 충전 후 재시도 |
404 | 모델 없음 | 모델 ID 확인 |
429 | 요청 한도 초과 | 백오프 후 재시도 |
SDK & 마이그레이션
OpenAI 공식 SDK(Python·Node)를 그대로 사용합니다. 별도 Kinfri SDK 설치가 필요 없습니다. 기존 코드에서 두 줄만 바꾸세요.
# 기존 OpenAI 코드
base_url="https://api.openai.com/v1",
model="gpt-4o",
# Kinfri로 변경 — 두 줄만
base_url="https://api.kinfri.ai/v1",
model="hyperclova-x",