Embeddings

POST /v1/embeddings 로 텍스트를 임베딩 벡터로 변환합니다. RAG, 검색, 유사도 계산에 사용합니다.


POST https://gw.letsur.ai/v1/embeddings

인증

방식	헤더
Gateway 키	`Authorization: Bearer <API_KEY>`

요청 파라미터

파라미터	타입	필수	기본값	설명
`model`	string	○	—	임베딩 모델 코드 (카탈로그)
`input`	string \| array	○	—	단일 문자열 또는 배치(배열)
`encoding_format`	string	×	`float`	`float` 또는 `base64`
`dimensions`	integer	×	모델별	출력 차원 (모델이 지원할 때만)

입력 제약

항목	값
단일 입력 토큰 한계	모델별 (예: `text-embedding-3-small`은 8,191 토큰)
배치 최대 크기	모델별 (보통 2,048 입력)
한 번에 보낼 수 있는 총 토큰	모델별

정확한 한계는 카탈로그에서 확인합니다. 한계를 초과하면 input_too_long 또는 batch_too_large 에러를 반환합니다.

차원 (`dimensions`)

OpenAI text-embedding-3 시리즈 등 일부 모델에서는 출력 차원을 줄여 받을 수 있습니다 (예: 기본 1,536 → 512). 저장과 검색 비용을 줄일 때 사용합니다.


client.embeddings.create(
    model="text-embedding-3-small",
    input="안녕",
    dimensions=512,
)

지원하지 않는 모델에 dimensions를 보내면 값이 무시되거나 invalid_parameter 에러를 반환합니다. 지원 여부는 카탈로그에서 확인합니다.

응답 (200)


{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.001, -0.024]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 5,
    "total_tokens": 5,
    "estimated_cost": 0.00000001
  }
}

필드	의미
`data[].embedding`	float 배열입니다 (`encoding_format`가 `base64`면 base64 문자열). 순서는 `input` 배열 순서를 따릅니다
`usage.prompt_tokens`	입력 토큰 수입니다 (output 토큰 없음)
`usage.estimated_cost`	Letsur가 추가한 필드로, input 토큰 단가에 토큰 수를 곱한 값입니다 (요금)

예시

cURL


curl https://gw.letsur.ai/v1/embeddings \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "안녕"
  }'

Python


from openai import OpenAI
 
client = OpenAI(api_key="<API_KEY>", base_url="https://gw.letsur.ai/v1")
 
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="안녕",
)
 
vector = response.data[0].embedding  # 1,536 차원 (기본)

TypeScript


import OpenAI from 'openai'
 
const client = new OpenAI({ apiKey: '<API_KEY>', baseURL: 'https://gw.letsur.ai/v1' })
 
const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: '안녕',
})
 
const vector = response.data[0].embedding

배치 입력

input 에 배열을 넘기면 여러 문장을 한 번에 임베딩할 수 있습니다.


response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["문장 1", "문장 2", "문장 3"],
)
 
vectors = [item.embedding for item in response.data]
# vectors[0]은 "문장 1"의 임베딩, vectors[1]은 "문장 2", ...

배치는 한 호출에 묶인 입력을 합쳐 한도를 1회만 차감합니다. 입력 1개씩 N번 호출할 때보다 비용이 적게 듭니다.

에러 (이 엔드포인트 고유)

코드	HTTP	의미
`model_not_found`	404	카탈로그에 없는 모델입니다
`input_too_long`	400	단일 입력 토큰이 모델 한계를 초과했습니다
`batch_too_large`	400	배치 크기가 모델 한계를 초과했습니다
`invalid_parameter`	400	`dimensions`를 지원하지 않는 모델에 보낸 경우 등입니다

공통 에러는 에러 코드에서 확인합니다.

한도와 제약

비용은 input 토큰만 기준으로 계산합니다 (output 토큰 없음).
스트리밍은 지원하지 않습니다. 임베딩은 한 번에 결과를 돌려주는 동기 호출입니다.
단일 입력 토큰 한계와 배치 최대 크기는 모델마다 다릅니다. 정확한 한계는 카탈로그에서 확인합니다.