BYOK (Bring Your Own Key)

BYOK(Bring Your Own Key)는 OpenAI·Anthropic 같은 프로바이더의 API 키를 직접 보유한 경우, 그 키를 PleumRouter에 등록해 사용하는 기능입니다. 토큰 비용은 프로바이더에 직접 지불하고, PleumRouter는 라우팅·과금·관측 등 플랫폼 수수료만 청구합니다. 등록한 키는 저장 시 암호화되며, 평문은 다시 조회되지 않습니다.

상태와 사용량#

GET /v1/byok/status는 현재 BYOK 활성화 여부(enabled), 수수료율(fee_percent, 퍼센트), 월 무료 토큰 한도 (free_monthly_tokens)를 반환합니다.

{
  "enabled": true,
  "fee_percent": 1.5,
  "free_monthly_tokens": 10000000
}

GET /v1/byok/usage는 이번 달 BYOK 토큰 사용량, 남은 무료 토큰, 지금까지 청구된 수수료(원화), 그리고 프로바이더별 내역(by_provider)을 반환합니다.

{
  "month_tokens": 1240000,
  "free_monthly_tokens": 10000000,
  "free_remaining_tokens": 8760000,
  "fee_charged_krw": 0,
  "by_provider": [
    {"provider": "openai", "tokens": 920000, "fee_krw": 0},
    {"provider": "anthropic", "tokens": 320000, "fee_krw": 0}
  ]
}

키 등록#

POST /v1/byok/keys로 키를 등록(또는 갱신)합니다. 같은 프로바이더에 대해 다시 등록하면 기존 키를 덮어씁니다(upsert). 전체 키 목록은 GET /v1/byok/keys, 삭제는 DELETE /v1/byok/keys/{id}를 사용합니다.

curl -X POST https://router.pleum.ai/v1/byok/keys \
  -H "Authorization: Bearer <session_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "api_key": "sk-..."
  }'

응답에는 키 자체가 아니라 마스킹된 힌트(key_hint, 예 ••••a1b2)만 포함됩니다. 평문 키는 어떤 응답에서도 반환되지 않습니다.

{
  "id": "b1f2c3d4-...",
  "provider": "openai",
  "key_hint": "••••a1b2",
  "is_active": true,
  "created_at": "2026-06-27T09:00:00Z"
}

과금 방식#

BYOK 호출에서는 토큰 마크업이 0입니다. 토큰 요금은 등록한 키로 프로바이더에 직접 청구되고, PleumRouter는 정가 환산 원화 비용의 fee_percent만큼만 수수료를 원화 크레딧으로 청구합니다(기본 1.5%).

수수료는 매월 free_monthly_tokens까지 무료입니다(기본 1,000만 토큰). 무료 한도를 넘어선 사용분부터 위 수수료가 적용됩니다. 한도와 수수료율의 현재 값은 GET /v1/byok/status에서 확인하세요.