본문으로 건너뛰기
PleumRouter
시작하기

BYOK (Bring Your Own Key)

코드 소유 credential preset을 선택하고 검증된 Provider API 키로 라우팅합니다.

BYOK(Bring Your Own Key)는 Provider의 종량제 API 계정에서 발급한 키를 PleumRouter에 암호화해 보관하고, 해당 키로 요청을 라우팅하는 기능입니다. Provider 모델 원가는 Provider에 직접 지불하고, PleumRouter에는 무료구간 초과 후 서비스 수수료만 크레딧으로 지불합니다.

BYOK는 이메일 신청이나 계정별 심사 기능이 아닙니다. 운영 상태(enabled)가 켜져 있으면 모든 인증 사용자가 live·approved·공식 무과금 검증 지원 프리셋을 연결할 수 있습니다. 운영 상태가 꺼져 있을 때는 새 연결과 재검증만 일시 중지됩니다. 상태·카탈로그·과거 사용량과 기존 키 목록은 계속 조회할 수 있고 기존 키 연결도 해제할 수 있습니다.

프리셋 카탈로그#

GET/v1/byok/catalog

GET /v1/byok/catalog는 서버가 소유한 불변 프리셋을 반환합니다. 키 연결은 availability=live, contract_status=approved, connection_enabled=true이고 공식 무과금 검증이 있는 종량제 프리셋으로 제한됩니다. endpoint·protocol·auth_scheme은 프리셋에 고정되며 사용자가 바꿀 수 없습니다.

카탈로그에는 지금 연결할 수 있는 종량제 프리셋만 노출됩니다(2026-09-13 정책). 공식 무과금 검증이 증명되지 않은 provider와 토큰 플랜·코딩 플랜, 그리고 ChatGPT·Claude·Gemini 같은 소비자 구독 항목은 목록에서 제외됩니다. 소비자 구독은 종량제 API 사용량을 포함하지 않으므로 BYOK 키로 사용할 수 없고, 별도로 결제되는 Provider API 계정이 필요합니다.

200 OK
{
  "data": [
    {
      "preset_id": "openai.payg.default",
      "provider": "openai",
      "kind": "payg",
      "display_name_key": "byok.preset.openai.payg",
      "display_name_en": "OpenAI PAYG API",
      "availability": "live",
      "contract_status": "approved",
      "endpoint": "https://api.openai.com/v1/chat/completions",
      "region": "global",
      "protocol": "openai_chat",
      "auth_scheme": "bearer",
      "supported_protocols": ["openai_chat"],
      "official_price_equivalent_ref": "model_catalog.provider:openai",
      "validation": {"kind": "openai_models", "zero_cost": true},
      "allowed_use_key": "byok.provider_api_key_only",
      "allowed_use_en": "Use an API key issued for this provider's metered API account.",
      "connection_enabled": true,
      "referral_enabled": false
    },
    {
      "preset_id": "groq.payg.default",
      "provider": "groq",
      "kind": "payg",
      "display_name_key": "byok.preset.groq.payg",
      "display_name_en": "Groq PAYG API",
      "availability": "live",
      "contract_status": "approved",
      "endpoint": "https://api.groq.com/openai/v1/chat/completions",
      "region": "global",
      "protocol": "openai_chat",
      "auth_scheme": "bearer",
      "supported_protocols": ["openai_chat"],
      "official_price_equivalent_ref": "model_catalog.provider:groq",
      "validation": {"kind": "openai_models", "zero_cost": true},
      "allowed_use_key": "byok.provider_api_key_only",
      "allowed_use_en": "Use an API key issued for this provider's metered API account.",
      "connection_enabled": true,
      "referral_enabled": false
    }
  ]
}

키 연결과 검증#

POST/v1/byok/keys

POST /v1/byok/keys에 정확한 preset_id와 api_key만 보냅니다. 사용자 endpoint와 협상 단가는 받지 않습니다. 서버는 저장 암호화를 먼저 확인한 뒤 프리셋의 공식 무과금 엔드포인트에서 즉시 검증하며, 검증된 키만 활성화합니다.

파라미터타입필수설명
preset_idstring필수GET /v1/byok/catalog에서 고른 정확한 프리셋 ID. 별칭은 지원하지 않습니다.
api_keystring필수해당 Provider의 종량제 API 계정이 발급한 키. 공백 제거 후 8~500자이며 평문은 응답하지 않습니다.
request
curl -X POST https://apirouter.pleum.ai/v1/byok/keys \
  -H "Authorization: Bearer <session_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "preset_id": "openai.payg.default",
    "api_key": "sk-..."
  }'

응답에는 평문 대신 끝 네 자리만 포함한 key_hint와 서버 검증 상태가 들어갑니다. 실패한 등록도 inactive/failed 상태로 보일 수 있으며 검증 오류 코드는 비밀값 없이 제한된 값만 제공합니다.

200 OK
{
  "id": "b1f2c3d4-...",
  "preset_id": "openai.payg.default",
  "provider": "openai",
  "kind": "payg",
  "key_hint": "••••a1b2",
  "is_active": true,
  "verification_status": "verified",
  "verification_attempted_at": "2026-08-12T09:00:00Z",
  "verified_at": "2026-08-12T09:00:00Z",
  "last_verification_error": null,
  "created_at": "2026-08-12T09:00:00Z"
}
GET/v1/byok/keys
POST/v1/byok/keys/{id}/verify
DELETE/v1/byok/keys/{id}

GET /v1/byok/keys로 목록을 보고, POST /v1/byok/keys/{id}/verify로 저장된 키를 재검증하며, DELETE /v1/byok/keys/{id}로 연결을 해제합니다. 운영 상태가 꺼져도 목록 조회와 해제는 가능하지만 재검증은 중지됩니다. 기존 방식의 키는 verification_required이며 재검증 전까지 라우팅되지 않습니다.

상태와 사용량#

GET/v1/byok/status
GET/v1/byok/usage

GET /v1/byok/status는 현재 운영 상태, 초과 요금(1M 토큰당 크레딧), 주간 무료 토큰 한도를 반환합니다. GET /v1/byok/usage는 UTC 기준 이번 주 BYOK 토큰, 무료 잔여량, 청구된 크레딧, Provider별 내역을 반환합니다. 주 집계는 매주 월요일 00:00 UTC에 초기화됩니다.

GET /v1/byok/status · 200 OK
{
  "enabled": true,
  "overage_credits_per_1m": 300.0,
  "free_period_tokens": 10000000,
  "market": "kr"
}
GET /v1/byok/usage · 200 OK
{
  "period_tokens": 1240000,
  "free_period_tokens": 10000000,
  "free_remaining_tokens": 8760000,
  "fee_charged_krw": 0,
  "by_provider": [
    {"provider": "openai", "tokens": 1240000, "fee_krw": 0}
  ]
}

과금과 라우팅#

주 1,000만 BYOK 토큰까지 Pleum 초과 요금은 0크레딧입니다. 초과 사용분에는 1M 토큰당 300크레딧을 청구합니다. 미납이 생기면 BYOK 사용이 일시 정지되고 충전하면 자동 해제됩니다. 실제 현재 값은 status/usage 응답이 권위이며, Provider 모델 원가와 Provider 계정 한도는 사용자가 Provider에 직접 부담합니다.

등록된 Provider 키가 미검증·실패·복호화 불가 상태이면 같은 Provider의 Pleum 관리형 키로 조용히 자동 전환하지 않습니다. 다만 일반 라우팅 정책이 별도의 이용 가능한 offering을 선택할 수는 있습니다.

추천 진단과 호환 API#

POST/v1/byok/recommendations

POST /v1/byok/recommendations의 본문은 도구, 월 예상 토큰, 예산대, 필수 모델, 호스팅 리전만 받습니다. 서버가 인증된 사용자의 영속 시장을 권위값으로 더해 카탈로그의 연결 가능 프리셋 중 Top 3와 전체 비교표를 계산하며, 클라이언트가 market을 보낼 수 없습니다. 제휴 캠페인·수수료·보상액은 점수에 넣지 않습니다.

request
curl -X POST https://apirouter.pleum.ai/v1/byok/recommendations \
  -H "Authorization: Bearer <session_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "coding",
    "monthly_tokens": 50000000,
    "budget": "low",
    "required_models": [],
    "region": "global"
  }'
POST/v1/byok/plans/{preset_id}/interest

POST /v1/byok/plans/{preset_id}/interest는 같은 사용자·프리셋 요청을 멱등 처리하는 호환 엔드포인트로, 카탈로그에 노출된 프리셋만 등록할 수 있습니다. 관심 등록 자체는 화면 기능에서 제거됐습니다.

외부 추천 링크는 운영자가 승인한 캠페인이 live 상태이고 캠페인 API가 이를 확인한 경우에만 표시됩니다. 제휴·스폰서 관계는 순위와 분리해 고지하며, 캠페인이 확인되지 않으면 외부 이동 CTA가 없습니다. 현재 추천 보너스 정산·지급·회수 경로도 없습니다.

지원 범위와 책임#

현재 BYOK는 영상 및 3D 같은 비동기 생성 job을 지원하지 않으며 해당 요청은 400으로 거부됩니다. 작업 경계를 넘는 BYOK 상태를 안전하게 영속·정산하기 전까지 이 제한이 유지됩니다.

키 권한·잔액·결제수단·회전·폐기는 Provider 콘솔에서 직접 관리하세요. PleumRouter는 평문 키를 다시 보여주지 않습니다.

이전모델·라우팅 고르기다음커스텀 프로바이더