임베딩 — /v1/embeddings
검색·추천에 쓰는 벡터. 입력 단가만 있습니다.
문서 검색(RAG)이나 추천을 만들 때 쓰는 벡터예요. 출력 토큰이 없어서 입력 단가만 있어요. OpenAI SDK 를 그대로 쓰시면 돼요.
curl https://oneport.kr/v1/embeddings \
-H "Authorization: Bearer $ONEPORT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": "3학년 수학 분수 단원 정리"
}'import os
from openai import OpenAI
client = OpenAI(base_url="https://oneport.kr/v1", api_key=os.environ["ONEPORT_API_KEY"])
r = client.embeddings.create(model="text-embedding-3-small", input=["첫 문단", "둘째 문단"])
vecs = [d.embedding for d in sorted(r.data, key=lambda d: d.index)]응답은 벤더가 준 OpenAI 모양 그대로예요 — data[].embedding · data[].index · usage. usage.prompt_tokens 가 차감 기준 토큰이에요. 이 문 응답엔 글 문의 usage.cost_credits 가 없어요 — 벤더 몸통을 그대로 드려서요. 한 번의 값은 usage.prompt_tokens × input_credits_per_mtok ÷ 100만이에요(저희는 아주 작은 단위에서 올려서 어림엔 차이가 없어요). 구글 모델(gemini-embedding-…)은 모델 회사 응답에 usage 가 없어서 저희가 구글의 토큰 세기로 따로 세어 차감하고, 그 수를 usage.prompt_tokens · total_tokens 에 넣어 드려요(2026-10-29 부터) — 그래서 구글 모델도 같은 셈으로 한 번의 값을 알 수 있고, 아래 input 칸의 비율 재기(작은 묶음의 usage.prompt_tokens ÷ 글자 수)도 돼요. 드물게 구글의 토큰 세기가 실패하면 잡아 둔 몫 그대로 차감하고 응답에 usage 가 없어요 — 그 호출은 잡아 두는 몫(본문 바이트 ÷ 2 토큰)으로 셈하세요. 보낸 글은 저희 사용 기록에 남기지 않아요 — 모델 · 토큰 수 · 성공/실패 · 요청 ID 만 남기고, 글은 벡터를 만들러 벤더로만 가요. 차감은 응답을 보낸 직후에 정산돼서, 바로 뒤에 GET /v1/credits 를 보면 아직 안 줄었을 수 있어요. 임베딩 모델을 바꾸면 벡터를 처음부터 다시 만드세요 — 다른 모델로 만든 벡터끼리는 길이가 같아도 비교가 맞지 않아요(벤더 동작). 질문도 같은 모델로 임베딩하세요. 끝날 모델은 GET /v1/models 줄의 retirement 칸이 날짜(UTC)와 바꿔 넣을 모델(successors)을 미리 알려 줘요(모양은 「모델」 장 · 11월 1일 기준 임베딩 줄은 모두 예고 없이 null). 그날이 지나면 그 모델은 404 model_not_found 이고 문장엔 끝난 날 없이 비슷한 임베딩 모델 이름만 와요 — 그 전에 넣어 둔 글을 새 모델로 다시 임베딩하고 질문도 같이 바꾸세요. 다시 임베딩할 수 있게 원문을 같이 저장해 두세요.
요청 파라미터#
요청 본문 (JSON)
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| model필수 | 임베딩 모델 id | 채팅 모델을 넣으시면 400 으로 /v1/chat/completions 로 가시라고 알려드려요. 목록에 없는 이름이면 404 model_not_found 와 비슷한 임베딩 모델 이름을 알려드려요. |
| input필수 | 문자열 또는 문자열 배열 | 한 번에 몇 개 보낼지는 저희가 세지 않아요. 막는 건 셋이에요 — 벤더 한도(OpenAI 는 입력 하나 8,192토큰 · 한 요청 2,048개 · 합계 30만 토큰 — 벤더 공개 한도), 요청 본문 4.5MB, 벤더 응답 35초(아래 「실패하면」). 구글 모델(gemini-embedding-…)의 입력 하나 · 한 요청 개수 한도는 이 장에 적지 않았어요 — 저희가 세지 않고 그대로 넘겨서, 넘으면 모델 회사 거절이 400 vendor_rejected 로 와요(그땐 묶음을 반으로 나눠 보내요). 묶음 하나에는 (본문 바이트 ÷ 2) 토큰어치 몫이 잡혀요 — 예를 들어 1,500자 한글 글 50편(약 22만 바이트)을 text-embedding-3-small 로 보내면 약 2크레딧을 잡아 둬요(차감이 아니에요 — 차감은 아래 센 토큰으로 · 10월 기준 · 단가 정본은 GET https://oneport.kr/v1/models). 잔액이나 키 한도가 그보다 적으면 그 묶음이 먼저 막혀요. 배열로 여러 개를 한 번에 보내실 수 있어요. input 이 빈 문자열이거나 빈 배열이면 400 「input 을 지정해주세요.」예요. 배열 안의 빈 칸은 저희가 거르지 않고 넘겨요 — 빼고 보내 주세요. 4.5MB 를 넘으면 저희 코드에 닿기 전에 호스팅이 413 을 줘요 — 몸통이 JSON 이 아니라 글자(Request Entity Too Large · FUNCTION_PAYLOAD_TOO_LARGE)라 error.type 이 없어요(Python SDK 에선 e.type 이 None 이고 e.body 가 dict 가 아니라 글자예요 — e.body.get(…) 보다 상태 코드를 먼저 보세요 · Node SDK 에선 err.error · err.type 이 undefined 라 err.status 로 봐요 · SDK 동작). 상태 코드 413 으로 가려 「반으로 나눠 다시」로 처리하세요. 한 요청을 작게 — 수십~수백 개씩 — 나눠 보내 주세요. 스페이스 전송 정책을 켠 스페이스 키는 한 요청에 담는 글의 양에 상한이 있어요 — 넘으면 400 space_content_policy 이고 error.code 가 content_limit 이에요(2026-10-29 부터 글 문과 같아요). 문장은 「한 번에 보내는 글이 너무 많아요. 나눠서 보내 주세요.」예요. 묶음을 나누면 풀려요. 같은 type 이 503(code policy_unavailable)이나 409(code policy_changed)로 오면 잠시 뒤 그대로 다시 보내요 — 요금은 없어요. 다른 code(blocked_term 등)는 「에러」 장 space_content_policy 줄을 보세요. 차감은 usage.prompt_tokens 만큼이에요. 모든 임베딩 모델은 부르기 전에 몫을 잡아요 — 저희가 받은 본문 전체(model · dimensions · SDK 가 스스로 싣는 encoding_format 칸까지)를 칸 사이 공백 없이 다시 이은 JSON 의 UTF-8 바이트 ÷ 2 토큰(최소 1,000 토큰)이에요. 한글 한 글자는 3바이트라 약 1.5토큰으로 잡혀요. 이건 잡아 두는 몫이라 사용량 어림에 쓰지 마세요 — 실제로 사용하는 크레딧은 센 토큰으로 다시 셈해요(usage.prompt_tokens × input_credits_per_mtok ÷ 100만). 잡아 두는 몫은 상한이 아니라서 실제 사용이 이보다 클 수도 있어요 — 그러면 그 차이까지 차감돼요(그 호출은 끝까지 돼요). 남는 몫은 정산 때 풀려요. OpenAI 는 한 요청 합계 30만 토큰이라(벤더 공개 한도) 한 묶음 값은 많아야 30만 × 단가 ÷ 100만이에요 — text-embedding-3-small 이면 약 5.5 크레딧이에요. 큰 작업은 작은 묶음 하나를 먼저 보내 usage.prompt_tokens ÷ 글자 수로 비율을 재고, 그 비율을 전체 글자 수에 곱해 어림하세요. 몫은 요청마다 따로 잡혀서, 묶음을 차례로 보내면 한 묶음 몫만 잡히고 여러 묶음을 동시에 보내면 몫이 더해져 잡혀요. 바이트는 두 곳에서 따로 재요 — 잡아 두는 몫은 저희가 다시 이은 UTF-8 로 재서(한글 1글자 3바이트) SDK 가 어떻게 보내든 같고, 4.5MB 는 보내신 본문 그대로라 \uXXXX 로 가면 한글 1글자가 6바이트예요 — Python openai SDK(3.42.0 에서 확인)와 Node(JSON.stringify)는 \uXXXX 없이 UTF-8 그대로 보내서 1글자 3바이트예요(SDK 동작). 묶음을 1MB 아래로 두면 4.5MB 는 신경 안 쓰셔도 돼요. 잔액(402)과 키의 월 한도(429)는 이 몫으로 재서, 한도 가까이에서는 큰 묶음이 먼저 막힐 수 있어요(남은 몫은 GET /v1/key · 하루 한도는 이미 쓴 몫만 봐요). 구글 모델은 모델 회사 응답에 usage 가 없어서 구글의 토큰 세기로 따로 세어 차감하고 그 수를 usage 에 넣어 드려요. 그 세기가 실패하면 이 몫을 그대로 차감하고 응답에 usage 가 없어요 — 이때는 실제보다 많이 사용될 수 있어요. 응답은 크기와 상관없이 다 흘려 드려요. curl 이나 encoding_format: "float" 로 숫자 그대로 받으면 1536차원 벡터 하나가 약 34KB 라 큰 묶음은 응답도 커요 — encoding_format: "base64" 면 약 4분의 1 이에요. Python · Node OpenAI SDK 는 안 적으면 base64 로 받아서 이미 작아요(SDK 동작). |
| dimensions · encoding_format | 벤더 문서에 있는 값 | 저희가 거르지 않고 그대로 넘겨요 — 그 밖의 칸(user 등)도 마찬가지라 받을지는 모델 회사가 정하고, 받지 않으면 400 이에요(칸을 가리키면 reason vendor_param_rejected · error.param). 벡터 길이는 모델과 dimensions 로 벤더가 정해요 — 저희는 바꾸지 않아요. dimensions 를 줄여도 값은 같아요 — 값은 입력 토큰(usage.prompt_tokens)으로만 매겨요. dimensions 를 안 주면 text-embedding-3-small 은 1536, text-embedding-3-large 는 3072 길이로 와요. OpenAI 임베딩은 길이 1로 정규화돼 와서 내적이 곧 코사인 유사도예요(벤더 동작). 벡터 DB 칸 길이는 첫 응답의 data[0].embedding 길이로 정하시고, 질문을 임베딩할 때도 넣을 때와 같은 model · dimensions 를 주세요. Python · Node OpenAI SDK 는 encoding_format 을 안 적으면 스스로 base64 로 받아 숫자로 풀어 줘요. "base64" 를 직접 적으면 풀지 않고 글자(float32 리틀엔디언)로 줘요(SDK 동작). Node SDK 에서 머리글(x-should-retry 등)은 err.headers 로 읽어요 — v4 는 객체(err.headers["x-should-retry"]), v5 는 Headers(err.headers.get("x-should-retry"))예요(SDK 동작). |
실패하면 받은 것마다 이렇게 해요 — 까닭은 아래 「실패하면」이에요.
| 받은 것 | 할 일 |
|---|---|
| 400(reason 없음) · 401 · 403 · 404 | 멈추고 문장대로 고쳐요. |
| 400 vendor_param_rejected | error.param 칸 값을 고쳐요(나눠도 같아요). |
| 400 vendor_rejected · 413(몸통이 글자) · 400 space_content_policy(code content_limit) · 504 | 묶음을 반으로 나눠 바로 보내요(하나뿐이면 그 글을 두 조각으로). |
| 402 hold_exceeds_balance · 429 key_month_limit · hold_exceeds_key_limit · group_budget | 묶음을 줄여요(하나만 보내도 막히면 멈춰요). |
| 402 · 429 held_by_others | Retry-After(5초) 뒤 그대로 보내요. |
| 429 rate_limit_error | Retry-After(1~60초) 뒤 그대로 보내요. |
| 503 api_error | Retry-After(2초) 뒤 그대로 보내요. |
| 502 upstream_error · space_content_policy 503(code policy_unavailable) · 409(code policy_changed) | 몇 초 쉬고 그대로 보내요(Retry-After 없음). |
| 402 below_minimum_balance · 429 key_day_limit · group_closed · group_not_started · group_ended | 멈춰요 — 충전 · 한국 시간 내일 0시 · 스페이스 관리자. |
| 상태 코드 없음(연결 오류 · 시간 초과) | 이미 차감됐을 수 있어요 — 다시 보낼지 직접 정해요. |
이 문이 받는 모델#
어림은 아래 표 말고 GET https://oneport.kr/v1/models 의 input_credits_per_mtok 로 하세요 — 표는 보기 쉽게 반올림해서 text-embedding-3-small 이 18 이지만 목록 값은 18.4, text-embedding-3-large 는 120 이지만 119.57 이에요(10월 기준). 나머지 셋도 같아요 — 표의 92 · 138 · 184 는 목록에서 91.98 · 137.97 · 183.96 이에요. 정확한 값과 RAG 답변에 쓸 채팅 모델 단가는 GET https://oneport.kr/v1/models 에 있어요 — 응답은 {"object": "list", "data": [...]} 이고, 줄마다 id · kind · endpoint · pricing 이 와요. pricing.input_credits_per_mtok · output_credits_per_mtok 는 100만 토큰당 크레딧이에요. 임베딩 줄도 pricing.rates 에 input_text 한 줄이 와요(값은 input_credits_per_mtok 과 같아요) — 글 모델과 같은 코드로 읽으셔도 돼요. 임베딩 줄은 kind 가 "embedding" 이고 출력이 없어서 output_credits_per_mtok 칸이 아예 없어요 — 코드에선 없는 칸으로 다뤄 주세요. 답변용 채팅 모델은 kind 가 chat 인 것(endpoint 가 POST /v1/chat/completions)에서 고르세요 — kind 가 responses 인 pro 등급은 /v1/responses 로만 불려요. 채팅 모델 표와 단가는 https://oneport.kr/docs/reference/chat.md 에도 있어요. 임베딩과 채팅을 같이 쓰시면 두 값을 더해 계산하세요 — 예를 들어 RAG 답변을 gpt-5-mini(입력 229.95 · 출력 1,839.6 크레딧/100만 토큰, 10-26 목록 값)로 하면 근거 조각 3개(약 3,000토큰)를 넣고 500토큰으로 답할 때 질문 한 번에 약 1.6 크레딧이에요. 다만 gpt-5-mini 는 추론 모델이라 생각한 토큰도 출력 단가로 세요(usage.completion_tokens 에 들어 있어요) — 그래서 보이는 답이 500토큰이어도 차감은 이보다 클 수 있어요. reasoning_effort 를 "low" 로 주면 줄어요. 출력 상한은 max_tokens 로 보내셔도 저희가 max_completion_tokens 로 옮겨 보내요(둘 다 주시면 max_completion_tokens 가 가요). 미리 잡는 몫은 둘 중 큰 값(안 적으면 8,192)으로 잡고, 생각한 토큰도 이 상한 안에 들어요(벤더 동작). gemini-embedding-… 은 제미나이 팩이나 모델을 정하지 않은 크레딧으로만 불려요 — GPT · 클로드 팩 크레딧뿐이면 요금이 붙기 전에 403 model_not_in_plan 이에요. text-embedding-… 은 어느 크레딧으로든 불러요.
임베딩
| 모델 | 입력100만 토큰당 크레딧 |
|---|---|
| text-embedding-3-smallText Embedding 3 Small | 18 |
| text-embedding-3-largeText Embedding 3 Large | 120 |
| text-embedding-ada-002Text Embedding Ada 002 | 92 |
| gemini-embedding-001Gemini Embedding 001 | 138 |
| gemini-embedding-2Gemini Embedding 2 | 184 |