Keural API

Keural에 등록된 모델을 OpenAI Chat Completions 형식으로 호출합니다.

Base URL은 https://<환경별 공개 API 도메인>/llm/v1 형식입니다. 공개 API 도메인은 환경마다 다르므로 관리자에게 확인합니다.

임베딩, 이미지 생성, 음성, Responses API 경로는 지원하지 않으며 404를 반환합니다.

이용 흐름링크 복사

준비 사항링크 복사

API 키 발급링크 복사

1. 계정 메뉴에서 설정 → API를 엽니다. 데스크톱 앱과 모바일 앱에서는 도구 구역에 있습니다.
2. API 키 탭에서 키 소속(개인 워크스페이스 또는 조직 워크스페이스)과 Model ID를 고릅니다.
3. 필요하면 새 키 만료일을 정합니다. 비워 두면 회수할 때까지 무기한입니다.
4. 키 발급을 누르고 키 복사로 키를 복사해 보관합니다. 키 원문은 이때 한 번만 표시됩니다.

• 키는 고른 워크스페이스와 모델 하나에 연결됩니다. 사용량은 키를 발급한 사람에게 귀속됩니다.
• 같은 워크스페이스·모델에는 키가 하나만 있습니다. 새 키가 필요하면 기존 키를 재발급하거나 회수합니다.
• 키를 잃어버리면 재발급합니다. 재발급하면 이전 키는 즉시 무효가 됩니다.
• 발급할 수 있는 모델이 없으면 모델 공개 설정, 요금제, 조직 API 권한을 관리자에게 확인합니다.

조직 멤버의 API 권한링크 복사

조직 소유자·관리자용입니다. 조직 워크스페이스에서 멤버가 키를 받으려면 관리자가 먼저 허용해야 합니다. 모든 멤버의 기본값은 차단입니다.

조직 관리 → 조직 API 관리는 다음 세 구역으로 구성됩니다. 메뉴가 없으면 API 기능이 꺼져 있거나 조직 관리 권한이 없는 계정입니다.

멤버가 조직을 나가거나 제거되면 그 멤버가 조직에서 받은 키는 자동으로 회수됩니다.

클라이언트에 연결링크 복사

OpenAI API 호환 앱(챗 클라이언트, IDE 확장, 자동화 도구 등)에 다음 세 값을 입력합니다.

1. 앱 설정에서 OpenAI 호환 연결(Connection)을 추가합니다.
2. Base URL과 API Key를 입력하고 저장합니다.
3. 모델 목록에서 모델을 고릅니다. 목록에는 키에 연결된 모델 하나만 표시됩니다.
4. 짧은 메시지를 보내 응답을 확인합니다.

요청 형식은 다음과 같습니다.

첫 요청링크 복사

export KEURAL_API_KEY='발급받은_키'
export KEURAL_BASE_URL='https://<환경별 공개 API 도메인>/llm/v1'
export MODEL_ID='발급 화면의 모델 ID'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"안녕하세요.\"}]}"

요청 본문의 model은 키에 연결된 모델 ID와 같아야 합니다. provider/모델ID처럼 앞에 경로가 붙으면 마지막 / 뒤를 비교합니다. 다르면 403을 반환합니다. 응답의 model에는 항상 키의 모델 ID가 담깁니다.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "안녕하세요."}],
)
print(res.choices[0].message.content)

지원하는 요청 필드링크 복사

최상위 필드는 아래 18개만 받습니다. 다른 필드를 보내면 400을 반환합니다. 값이 null인 선택 필드는 보내지 않은 것으로 처리합니다.

메시지링크 복사

• tool 메시지는 앞선 tool_calls의 id에 한 번씩만 답합니다.
• 이미지 파트(image_url)는 이미지를 받는 모델의 user 메시지에만 넣습니다. http·https 주소나 PNG·JPEG·GIF·WebP의 base64 data URI를 넣고, detail은 auto · low · high입니다.

본문링크 복사

본문 규칙을 어기면 400이고 param은 body입니다.

스트리밍링크 복사

요청에 "stream": true를 넣으면 SSE로 응답합니다. 청크는 data: ... 이벤트로 전송되고, 마지막에 data: [DONE]이 전송됩니다. "stream_options": {"include_usage": true}를 넣으면 [DONE] 직전에 토큰 사용량 청크가 추가로 전송됩니다.

include_usage를 넣으면 모든 청크에 usage: null이 담기고, 마지막 사용량 청크는 choices가 빈 배열입니다. 비스트리밍 응답은 입력·출력 토큰이 모두 확인됐을 때만 usage를 담습니다.

응답 id는 chatcmpl-<x-request-id> 형식입니다. 모든 응답 헤더에는 x-request-id가 붙습니다.

스트리밍 중 오류가 나면 오류 JSON을 담은 data: 이벤트가 전송되고 [DONE] 없이 연결이 끝납니다. 청크 하나가 1MiB를 넘거나 응답이 16MiB를 넘으면 503으로 끝납니다.

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"안녕하세요.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

사용 한도링크 복사

사용자·조직·모델 단위로 동시 요청 수, 분당 요청 수(RPM), 분당 토큰 수(TPM)가 제한됩니다. 실제 값은 환경마다 다릅니다.

분당 토큰은 요청을 받을 때 미리 차감합니다. 입력은 영문 4글자당 1토큰, 그 밖의 글자는 1글자당 1토큰, 이미지 1장은 2,000토큰으로 계산합니다. 출력은 max_tokens(최대 4,096)만큼 차감하므로, 출력 상한을 필요한 만큼만 지정하면 한도 여유가 커집니다.

키 관리링크 복사

설정 → API → API 키 탭에서 키 상태(유효 · 만료 · 회수됨)를 확인하고 재발급하거나 회수합니다.

키는 krl_llm_으로 시작하는 51자 문자열입니다. 키 소속 하나에 키는 하나이며, 이미 있으면 재발급합니다. 만료일은 오늘 이후로만 정할 수 있습니다.

사용량 확인링크 복사

API 요청과 토큰 사용량은 다음 두 곳에서 확인합니다.

조회 조건링크 복사

조건을 정하고 조회를 누릅니다. 최근 요청을 반영하려면 새로고침을 누릅니다.

화면에 나오는 값링크 복사

• 적용 조회 기간: 실제로 조회된 기간입니다. 시작·종료 시각을 비웠거나 90일을 넘기면 조정된 기간이 표시됩니다.
• 요청 수와 입력 토큰 · 출력 토큰 · 전체 토큰 합계: 확인된 값만 합산합니다. 확인되지 않은 토큰은 미확인으로 표시합니다.
• 요청 목록: 요청마다 요청 시각, Model ID, 요청 상태, 입력·출력·전체 토큰을 표시합니다. 한 쪽에 20개씩 표시되며 이전 · 다음으로 넘깁니다.

행의 요청 세부 정보를 누르면 다음 값이 표시됩니다.

스트리밍 요청은 stream_options.include_usage 없이도 사용량이 기록됩니다. 요청이 중간에 끊기면 일부 확인이나 미확인으로 남을 수 있습니다.

오류 형식링크 복사

오류는 OpenAI 호환 형식으로 반환합니다.

{
  "error": {
    "message": "사람이 읽을 수 있는 오류 설명",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type은 상태 코드로 정해지고, code로 원인을 구분합니다.

문제 해결링크 복사

해결되지 않으면 다음 정보를 담아 관리자에게 문의합니다. 키 원문과 프롬프트 내용은 보내지 않습니다.

• 발생 시각
• 사용한 모델 ID
• 클라이언트 앱의 이름과 버전
• 응답 헤더의 x-request-id
• 화면에 나온 오류 메시지