Embeddings API

OpenAI Embeddings API와 같은 형식입니다. KURE 확장 파라미터는 input_type 하나뿐입니다.

인증

모든 요청에 Authorization 헤더로 API 키를 보냅니다.

Authorization: Bearer kure-...

키가 없거나 틀리면 401을 돌려줍니다. 키는 대시보드에서 발급하고 폐기할 수 있으며, 계정당 최대 5개까지 쓸 수 있습니다.

임베딩 만들기

POST https://kure.kullm.ai/api/v1/embeddings

요청 본문

파라미터	타입	구분	설명
`model`	string	필수	`kure-v3` 또는 스냅샷 `kure-v3-20261016` (모델 ID와 버전). 희소 임베딩은 Sparse Embeddings API로 보내세요.
`input`	string \| string[]	필수	임베딩할 텍스트. 배열은 최대 8개이며 빈 문자열은 안 됩니다. 텍스트 하나는 최대 8,192 토큰입니다.
`input_type`	`"query"` \| `"document"`	선택	KURE 확장. 검색 질의는 `query`, 검색 대상 문서는 `document`. 모델이 학습한 접두어를 서버가 붙입니다. 생략하면 텍스트를 그대로 임베딩합니다.
`dimensions`	integer	선택	출력 차원. `256`, `512`, `768`, `1024`, `2048` 중 하나이며 기본값은 `2048`입니다 (MRL).
`encoding_format`	`"float"` \| `"base64"`	선택	기본값 `float`. `base64`는 little-endian float32 배열을 base64로 인코딩한 문자열입니다.

OpenAI SDK가 보내는 user 같은 다른 필드는 무시합니다. 토큰 ID 배열 입력(input: [[1, 2, 3]])은 지원하지 않습니다.

응답

{
  "object": "list",
  "model": "kure-v3",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, ...] }
  ],
  "usage": { "prompt_tokens": 12, "total_tokens": 12 }
}

data는 input 순서대로이며, 각 항목의 index가 input의 위치입니다.
벡터는 길이 1로 정규화되어 있습니다. dimensions로 차원을 줄여도 다시 정규화되므로 내적이 곧 코사인 유사도입니다.
usage.prompt_tokens는 서버가 붙인 접두어를 포함한 토큰 수이며, rate limit에 이 값이 차감됩니다.

OpenAI SDK(Python·Node)는 encoding_format을 지정하지 않으면 내부적으로 base64로 받아 float 배열로 풀어 줍니다. 전송량이 줄어드니 SDK 기본 동작 그대로 쓰면 됩니다.

예시

import os
 
from openai import OpenAI
 
client = OpenAI(base_url="https://kure.kullm.ai/api/v1", api_key=os.environ["KURE_API_KEY"])
 
res = client.embeddings.create(
    model="kure-v3",
    input=[
        "고려대학교는 서울특별시 성북구 안암로 145에 있다.",
        "KURE는 고려대학교 NLP&AI 연구실이 만든 한국어 임베딩 모델이다.",
    ],
    dimensions=512,
    extra_body={"input_type": "document"},
)
vectors = [d.embedding for d in res.data]

많은 문서를 넣을 때

한 요청에 최대 8개까지 묶어 보내세요. 요청 수가 줄어 RPM 한도에 덜 걸립니다.
8,192 토큰을 넘는 텍스트는 400 context_length_exceeded로 거절됩니다. 미리 나누어 보내세요.
429를 받으면 Retry-After 헤더만큼 기다린 뒤 다시 보내세요 (한도와 에러).

모델 목록

GET https://kure.kullm.ai/api/v1/models

{
  "object": "list",
  "data": [
    { "id": "kure-v3-20261016", "object": "model", "created": 0, "owned_by": "nlpai-lab", "task": "embedding", "alias_for": null, "status": "active", "sunset": null, "replacement": null },
    { "id": "kure-v3", "object": "model", "created": 0, "owned_by": "nlpai-lab", "task": "embedding", "alias_for": "kure-v3-20261016", "status": "active", "sunset": null, "replacement": null }
  ]
}

스냅샷이 먼저, 별칭이 그 뒤에 나옵니다(일부만 표시). KURE 확장 필드: task는 쓸 엔드포인트(embedding, sparse-embedding, rerank), alias_for는 별칭이 가리키는 스냅샷, status·sunset·replacement는 모델 수명 주기입니다.

OpenAPI 스펙

전체 스펙은 /api/openapi.json에서 받을 수 있습니다.