임베딩 API
텍스트를 벡터로 변환하는 OpenAI 호환 임베딩 엔드포인트와, 검색 결과를 질의 관련도 순으로 재정렬하는 리랭킹 엔드포인트를 제공합니다. 임베딩은 OpenAI SDK를 그대로 사용할 수 있습니다.
엔드포인트
임베딩과 리랭킹은 별도 엔드포인트로 제공됩니다 POST /v1/embeddings 텍스트 임베딩 생성 (OpenAI 호환) POST /v1/rerank 질의 기준 문서 재정렬 인증은 Authorization: Bearer <API Key> 헤더를 사용합니다. 두 엔드포인트 모두 입력 토큰만 과금되며, 응답의 usage.cost 확장 필드로 원화 환산 비용을 확인할 수 있습니다.
지원 모델
모델 목록과 가격은 모델 페이지의 임베딩 섹션에서 확인할 수 있습니다 모델 코드 종류 기본 차원 최대 입력 (토큰) 🇰🇷 K-오픈웨이트 호환 별칭: openai/text-embedding-3-small 임베딩 1,536 8,191 openai/text-embedding-3-large 임베딩 3,072 8,191 모델 디스커버리 GET /v1/models 응답에서 api_type 이 embeddings 또는 rerank 인 모델이 이 엔드포인트를 지원합니다. 임베딩 모델은 채팅 엔드포인트에서 호출할 수 없으며, 반대의 경우도 마찬가지입니다. 국내 추론 임베딩·리랭킹 (K-OpenWeight) Qwen3 임베딩 3종·리랭커 2종과 Google EmbeddingGemma 2는 모두 BizRouter가 국내 자체 GPU에서 직접 서빙합니다. 기존 qwen/qwen3-embedding-* , qwen/qwen3-reranker-8b 코드는 같은 모델을 가리키는 호환 별칭으로 계속 동작하고 같은 가격이 적용됩니다(모델 목록에는 정본 코드만 보입니다). 가중치와 벡터 공간이 같아서 어느 코드로 만든 색인이든 그대로 쓸 수 있습니다. Qwen3 계열의 최대 입력은 32,768 토큰, EmbeddingGemma 2는 모든 modality가 함께 쓰는 8,192 토큰입니다(아래 멀티모달 절).
임베딩 생성
POST /v1/embeddings
임베딩 생성 · 요청 파라미터
model 모델 코드 (필수) input 문자열 또는 문자열 배열 (필수, 토큰 ID 배열은 지원하지 않습니다). 멀티모달 모델에는 배열 항목으로 content-parts 객체도 넣을 수 있습니다(아래 멀티모달 절) dimensions 출력 벡터 차원 축소 (선택, 모든 지원 모델에서 사용 가능 — EmbeddingGemma 2는 768·512·256·128만) encoding_format float (선택, OpenAI 모델은 base64도 지원) cURL Node.js Python 응답은 OpenAI Embeddings API와 동일한 { object: "list", data: [{ embedding, index }], model, usage } 형식입니다.
멀티모달 임베딩 (EmbeddingGemma 2)
텍스트·이미지·비디오·오디오를 한 벡터 공간에 — 같은 POST /v1/embeddings bizrouter/embeddinggemma-2 는 Google의 740M 멀티모달 임베딩 모델(Apache-2.0)을 국내 자체 GPU에서 서빙합니다. 텍스트(코드 포함)·이미지·비디오·오디오가 모두 768차원의 같은 공간에 들어가므로, 텍스트 질의로 이미지·오디오 자료를 검색하거나 한 항목 안에 텍스트와 미디어를 섞어 하나의 벡터로 만들 수 있습니다. 요청의 input 배열 항목에 문자열 대신 { content: [...] } 객체를 넣으면 됩니다. 파트 순서가 곧 섞이는 순서입니다.
멀티모달 임베딩 (EmbeddingGemma 2) · content 파트
text { "type": "text", "text": "..." } image_url { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } } — 이미지 1장 = 280 토큰 video_url { "type": "video_url", "video_url": { "url": "https://..." } } — 1fps로 최대 32프레임을 균등 추출, 프레임당 140 토큰(소리는 포함되지 않습니다) input_audio { "type": "input_audio", "input_audio": { "data": "<base64>", "format": "wav" } } — 초당 25 토큰 (16kHz 모노 권장, 다른 포맷은 서버가 변환) audio_url { "type": "audio_url", "audio_url": { "url": "https://..." } } 한도와 규칙 모든 modality가 한 요청 항목당 8,192 토큰 을 나눠 써요(단독이면 이미지 약 29장, 비디오 약 58프레임, 오디오 약 5분 27초). 넘치면 400입니다. 미디어 URL은 data: URI(base64) 또는 공개 호스트의 http(s) URL만 받습니다. 요청 본문은 전체 20MB까지입니다 — 큰 영상은 URL로 넘기십시오. 텍스트에는 모델 카드의 task prefix를 붙이십시오: 검색 질의 task: search result | query: ... , 문서 title: none | text: ... , 유사도·분류·군집은 양쪽에 task: sentence similarity | query: ... 식입니다. 미디어에는 prefix가 없습니다. dimensions 는 768·512·256·128만 받고(그 외 400), 잘라낸 벡터는 다시 정규화됩니다. 질의와 색인은 같은 차원이어야 합니다. Qwen3·OpenAI 임베딩 모델에 content-parts 항목을 보내면 400입니다( GET /v1/models 의 input_modalities 가 기준). 조직의 파일 업로드 차단 정책은 미디어 파트에도 그대로 적용됩니다. 과금은 텍스트·미디어를 합친 입력 토큰입니다(이미지 1장 280 토큰 = 약 0.0000042달러). 미디어 원본은 저장되거나 로그에 남지 않습니다. cURL Python 오디오 (Python)
리랭킹
POST /v1/rerank 비표준 계약 OpenAI에는 리랭킹 표준이 없으므로 이 엔드포인트는 OpenAI SDK로 호출할 수 없습니다. 아래 요청/응답 계약에 맞추어 HTTP로 직접 호출해야 합니다.
리랭킹 · 요청 파라미터
model 모델 코드 (필수) query 검색 질의 (필수) documents 재정렬할 문서 문자열 배열 (필수) top_n 반환할 상위 문서 수 (선택, 기본은 전체) return_documents 응답에 문서 원문 포함 여부 (선택, 기본 true) cURL Python 응답 예시 index 는 요청 documents 배열에서의 원래 위치이며, relevance_score 가 높은 순으로 정렬되어 반환됩니다. 질의와 문서를 합한 입력 토큰이 과금 대상입니다.
보안과 데이터 보관
임베딩 계열 엔드포인트는 채팅과 다른 보안 정책을 사용합니다 벡터 무결성 우선 개인정보 마스킹은 입력 내용을 변형하여 벡터 값 자체를 바꾸므로 이 엔드포인트에는 적용되지 않습니다. 조직의 금칙어 차단 설정은 동일하게 적용되며, 금칙어가 포함된 요청은 400으로 거부됩니다. 입력 텍스트, 문서, 생성된 벡터, 관련도 점수는 감사 로그에 저장되지 않습니다. 요청 로그에는 입력 개수와 길이 요약, 토큰 수, 비용만 기록됩니다.