Kinfri API 문서

Kinfri는 글로벌·국산 LLM을 단일 OpenAI 호환 API로 묶어줍니다. 쓰던 OpenAI SDK에서 base_url과 api_key만 바꾸면, 원화 정산·한국어 PII 마스킹이 자동으로 따라옵니다(전자세금계산서는 유료 오픈부터).

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="gemini-3.8-flash",
    messages=[{"role": "user", "content": "안녕하세요"}],
)
print(resp.choices[0].message.content)

인증 & API 키

모든 요청은 Authorization: Bearer <API_KEY> 헤더로 인증합니다. 키는 콘솔 → API 키에서 발급하며, 발급 시 한 번만 전체 값이 표시됩니다.

• sk-kf-live- — 발급되는 모든 키의 접두사. 호출한 만큼 크레딧에서 차감됩니다.
• 별도의 무료 테스트 키는 없습니다. 이메일 인증을 마치면(Google 가입은 바로) 체험 크레딧 ₩1,000을 드립니다. 업무 도구 전부와 체험 모델 API(저가 모델 · 한 번에 약 3만 토큰 · 분당 10회)에 쓸 수 있어요. 충전하면 모든 모델을 제한 없이 씁니다.

채팅 호출

OpenAI chat.completions 규격을 그대로 사용합니다. model만 Kinfri 모델 ID로 지정하세요.

resp = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[
        {"role": "system", "content": "너는 친절한 비서야."},
        {"role": "user", "content": "세금계산서 발행 방법 알려줘"},
    ],
)

스트리밍

stream: true를 주면 토큰을 SSE로 실시간 수신합니다. 모든 대화 모델이 같은 방식으로 스트리밍되며, stream_options: { include_usage: true }를 주면 마지막 청크에 토큰 사용량이 옵니다.

stream = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "긴 글 써줘"}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

이미지 생성

POST /v1/images/generations 에 OpenAI 이미지 규격 그대로 prompt · size · n · response_format: "b64_json" 을 보냅니다. 기본 이미지 모델은 gemini-nano-banana-2.1 이며, 지원 크기는 모델마다 다릅니다(gemini-nano-banana-2.1 · 1024x1024 · 1376x768 · 768x1376 · 2048x2048). Gemini 이미지 모델은 512 급(512x512 등 한 변이 768 미만인 크기)을 받지 않아 400 으로 거절됩니다. 응답은 data[].b64_json 과 토큰 usage 입니다.

참조 이미지: Gemini 이미지 모델에는 reference_images 배열로 사진을 함께 보낼 수 있습니다(사람 · 캐릭터 · 제품을 닮게 그리기). 각 항목은 data:image/png;base64,… 모양의 data URL 만 받으며(PNG · JPEG · WebP), 한 요청에 최대 4장 · 장당 7MB · 합 15MB 까지입니다. http(s) URL, 그 밖의 형식, 상한 초과, 참조 이미지를 받지 않는 모델(imagen · OpenAI)에 보낸 경우는 400 으로 거절됩니다. 참조 이미지는 PII 가드레일이 훑지 않으며, 입력 이미지 토큰은 응답 usage.prompt_tokens_details.image_tokens 로 와서 입력 단가로 과금됩니다.

import base64

photo = "data:image/jpeg;base64," + base64.b64encode(open("me.jpg", "rb").read()).decode()
resp = client.images.generate(
    model="gemini-nano-banana-2.1",
    prompt="이 사람을 닮은 웹툰풍 스티커, 흰 테두리, 엄지 척",
    size="1024x1024",
    response_format="b64_json",
    extra_body={"reference_images": [photo]},
)
png = base64.b64decode(resp.data[0].b64_json)

엔드포인트

기본 주소는 https://api.kinfri.ai/v1 입니다. 요청 · 응답 모양은 OpenAI 규격과 같습니다.

모델 선택

여러 공급처의 모델을 같은 코드로 호출합니다. model에 아래 모델 ID 를 넣으세요. 단가는 1K 토큰당 원화(VAT 별도, 표시 환율 기준)이며, 로그인 뒤 모델 목록에서도 볼 수 있습니다.

PII 가드레일

워크스페이스에서 가드레일을 켜면, 요청이 업스트림으로 나가기 전에 주민번호·연락처·이메일 등이 비식별화됩니다. 원문은 저장되지 않고 즉시 휘발됩니다. 호출별로 헤더로도 제어할 수 있습니다.

resp = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{
        "role": "user",
        "content": "내 주민번호는 900101-1234567",
    }],
    extra_headers={"X-Kinfri-PII": "on"},
)
# 업스트림 전송 전: 900101-1234567 → ######-#######

마스킹 동작은 PII 가드레일 설정에서 유형별로 켜고 끌 수 있습니다.

원화 청구 & 세금계산서

호출 시점 환율로 원화 크레딧에서 차감되며, 응답 usage에 토큰 수가 포함됩니다. 법인 고객 전자세금계산서 자동 발행은 유료 오픈(2026-12 예정)부터 제공합니다. 잔액이 0이 되면 호출이 중단되고 미수금은 발생하지 않습니다.

에러 코드

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="gemini-3.8-flash",