게이트웨이 API

고객사 온프레미스 커넥터가 에토스AI 클라우드 게이트웨이를 호출하는 머신용 API입니다. DB·파일은 고객 안에 두고, LLM 호출만 이 게이트웨이를 거칩니다 (B1 아키텍처). 프로바이더 키는 에토스AI 서버에만 있으며, 커넥터는 워크스페이스 API 토큰으로만 인증합니다.

1. 토큰 발급

관리자(ADMIN)가 /admin 대시보드 → 게이트웨이 API 토큰에서 발급합니다. 평문 토큰은 발급 화면에서 1회만 노출되며, 서버에는 sha256 해시만 저장됩니다. 토큰 형식: vok_…

2. POST /api/v1/chat

대화 메시지 배열과 모델 ID를 받아, 선택한 모델의 응답을 JSON으로 반환합니다 (비스트리밍).

인증 헤더

Authorization: Bearer vok_xxxxxxxx...

Request Body (application/json)

필드	타입	설명
`messages`	{ role, content }[]	대화 이력. `role`은 `user` 또는 `assistant`. (필수)
`model`	string	모델 ID (예: `claude-fable-5`). 생략 시 기본 모델.
`system`	string	시스템 프롬프트 (선택). 생략 시 기본값.

Response (200)

{
  "text": "…모델 응답…",
  "model": "claude-fable-5",
  "provider": "anthropic",
  "usage": { "input_tokens": 42, "output_tokens": 128 }
}

오류

상태	의미
`401`	토큰 없음/무효/폐기됨
`400`	잘못된 본문 또는 알 수 없는 모델
`502`	프로바이더 키 미설정 또는 프로바이더 호출 실패

3. 호출 예시 (curl)

curl -X POST https://<에토스AI-호스트>/api/v1/chat \
  -H "Authorization: Bearer vok_xxxxxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "messages": [{ "role": "user", "content": "이번 분기 매출 요약해줘" }]
  }'

4. POST /api/v1/metering — 폐쇄망 미터링

완전 폐쇄망 설치본은 LLM 호출 자체를 내부에서 처리하고, 과금을 위한 집계 카운터만 주기적으로 업링크합니다. 프롬프트·답변 내용은 절대 전송되지 않습니다. 인증은 동일한 게이트웨이 토큰(Bearer)입니다.

curl -X POST https://<에토스AI-호스트>/api/v1/metering \
  -H "Authorization: Bearer vok_xxxxxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "counters": [
      { "model": "qwen2.5-72b-local", "inputTokens": 120000, "outputTokens": 45000 },
      { "model": "claude-sonnet-5",   "inputTokens": 8000,   "outputTokens": 3000 }
    ]
  }'

응답: { "ok": true, "accepted": 2 }. 수신된 카운터는 워크스페이스 사용량으로 기록되어 관리자·수퍼 대시보드에 합산 표시됩니다 (한 번에 최대 100건).

5. 데이터 흐름과 보안

커넥터 → 게이트웨이는 아웃바운드 1개 지점이라 고객 방화벽에서 화이트리스트하기 쉽습니다.
고객의 DB·파일 원본은 게이트웨이로 오지 않습니다. 프롬프트에 실린 데이터 조각만 전송됩니다.
모든 호출은 워크스페이스별 사용량으로 기록되어 관리자 대시보드에서 조회됩니다.
토큰 폐기 시 해당 커넥터는 즉시 인증에 실패합니다.