Embeddings

텍스트를 검색과 유사도 계산에 사용할 벡터로 변환하세요.

단일 입력과 배치 입력 및 출력 인코딩을 OpenAI 호환 임베딩 형식으로 다룹니다.

POSThttps://gw.letsur.ai/v1/embeddings

AUTHAuthorization: Bearer <API_KEY>

요청 필드

필드	타입	요구 여부	기본값	설명
`model`	string	필수	—	임베딩 모델 코드 (에셋)
`input`	string \| array	필수	—	단일 문자열 또는 배치(배열)
`encoding_format`	string	선택	`float`	`float` 또는 `base64`
`dimensions`	integer	선택	모델별	출력 차원 (모델이 지원할 때만)

입력 제약

입력 한계는 모델마다 다릅니다. 정확한 값은 에셋에서 확인하며, 초과하면 input_too_long 또는 batch_too_large 에러를 반환합니다.

항목	값
단일 입력 토큰 한계	모델별
배치 최대 크기	모델별
한 번에 보낼 수 있는 총 토큰	모델별

`dimensions`

일부 모델에서는 출력 차원을 줄여 받을 수 있습니다. 저장과 검색 비용을 줄일 때 사용하며, 지원 범위와 허용 값은 에셋 상세를 기준으로 확인합니다.


client.embeddings.create(
    model="<MODEL_CODE>",
    input="안녕",
    dimensions=512,  # 에셋 상세에서 지원하는 값으로 변경
)

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

응답 (200)


{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.001, -0.024]
    }
  ],
  "model": "<MODEL_CODE>",
  "usage": {
    "prompt_tokens": 5,
    "total_tokens": 5
  },
  "estimated_cost": {
    "amount": "0.00000010",
    "currency": "unit",
    "disclaimer": "Estimated based on published pricing. Actual charges may differ."
  }
}

필드	의미
`data[].embedding`	float 배열입니다 (`encoding_format`가 `base64`면 base64 문자열). 순서는 `input` 배열 순서를 따릅니다
`usage.prompt_tokens`	입력 토큰 수입니다 (output 토큰 없음)
`estimated_cost`	응답 최상위의 호출별 비용 객체입니다. 의미와 `null` 처리 기준은 요청별 비용을 따릅니다

요청과 응답 예시

아래 예제는 Bash 또는 서버 runtime의 LETSUR_API_KEY 환경 변수를 읽습니다. 키 설정과 첫 실행은 AI 게이트웨이 시작하기에서 확인합니다.

cURL


(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/embeddings \
    --header @- \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<MODEL_CODE>",
      "input": "안녕"
    }' <<EOF
Authorization: Bearer ${LETSUR_API_KEY}
EOF
)

Python


import os
 
from openai import OpenAI
 
client = OpenAI(api_key=os.environ["LETSUR_API_KEY"], base_url="https://gw.letsur.ai/v1")
 
response = client.embeddings.create(
    model="<MODEL_CODE>",
    input="안녕",
)
 
vector = response.data[0].embedding

TypeScript


import OpenAI from 'openai'
 
const apiKey = process.env.LETSUR_API_KEY
if (!apiKey) throw new Error('LETSUR_API_KEY가 필요합니다.')
 
const client = new OpenAI({ apiKey, baseURL: 'https://gw.letsur.ai/v1' })
 
const response = await client.embeddings.create({
  model: '<MODEL_CODE>',
  input: '안녕',
})
 
const vector = response.data[0].embedding

배치 입력

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


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

배치는 여러 입력을 한 요청으로 처리하는 방식입니다. 실제 비용은 입력 사용량과 현재 모델 단가를 기준으로 확인합니다.

엔드포인트와 모델별 제약

usage는 입력 토큰 수를 반환하며 output 토큰 사용량은 없습니다.
스트리밍은 지원하지 않습니다. 임베딩은 한 번에 결과를 돌려주는 동기 호출입니다.
단일 입력 토큰 한계와 배치 최대 크기는 모델마다 다릅니다. 정확한 한계는 에셋에서 확인합니다.

오류와 복구

이 엔드포인트 문맥에서 자주 확인할 오류를 표시합니다. 인증과 월 사용 한도 같은 공통 에러는 에러 코드와 한도에서 확인합니다.

오류	의미와 대응
`model_not_found` (404)	에셋 목록에 없는 모델입니다. 대응: 에셋에서 모델 코드와 Embeddings 지원 여부를 다시 확인합니다.
`input_too_long` (400)	단일 입력의 토큰 수가 모델 한계를 초과했습니다. 대응: 입력을 더 짧은 단위로 나눕니다.
`batch_too_large` (400)	배치 크기가 모델 한계를 초과했습니다. 대응: 한 요청에 보내는 `input` 배열의 항목 수를 줄입니다.
`invalid_parameter` (400)	`dimensions`를 지원하지 않는 모델에 보낸 경우 등입니다. 대응: 응답의 `detail`을 확인해 지원하지 않는 요청 필드를 제거하거나 수정합니다.