Embeddings

텍스트나 이미지를 벡터로 바꾸는 엔드포인트입니다. 검색, 추천, 분류, 중복 판정처럼 의미가 얼마나 가까운지를 다루는 기능의 재료가 됩니다.

요청·응답 형식은 OpenAI Embeddings API와 같아서, 기존 코드의 base_url만 바꾸면 그대로 동작합니다.

Method	Path	설명
POST	`/v1/gateway/embeddings/`	임베딩 생성

모델	차원	이미지	비고
`text-embedding-3-small`	1536	—	가장 저렴합니다
`text-embedding-3-large`	3072	—
`gemini-embedding-2`	3072	지원	이미지 1장을 크기와 무관하게 258토큰으로 셉니다
`text-embedding-v4`	1024	—
`qwen3.7-text-embedding`	1024	—
`tongyi-embedding-vision-plus`	1152	지원	이미지 토큰을 실제 크기대로 셉니다

dimensions로 줄일 수 있는 모델이 있으므로, 표의 차원은 기본값입니다.

임베딩 모델을 /v1/gateway/chat/completions/에 보내면 400과 함께 올바른 경로를 안내합니다. 반대로 대화 모델을 이 엔드포인트에 보내도 마찬가지입니다.

model

string

required

위 표의 모델 이름.

input

string | array

required

임베딩할 대상. 문자열 하나, 문자열 배열, 또는 이미지 객체 배열을 받습니다. 배열 순서는 응답의 index로 그대로 보존됩니다.

이미지는 image_url 객체로 넘깁니다. url은 base64 데이터 URL이어야 하며, 외부 링크는 받지 않습니다.

dimensions

integer

반환할 벡터 차원. 모델이 지원하는 경우에만 유효합니다. 예를 들어 text-embedding-3-small에 256을 주면 256차원이 돌아옵니다.

encoding_format

string

float(기본값) 또는 base64. base64를 주면 embedding이 숫자 배열이 아니라 문자열로 돌아옵니다. 전송량이 줄어 대량 처리에 유리합니다.

task_type

string

Gemini 임베딩 모델 전용. RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY 등 용도를 알려 주면 그에 맞게 벡터를 만듭니다.

이미지를 넣으면 usage에 image_tokens가 함께 옵니다.

배열 크기 제한은 신경 쓰지 않아도 됩니다. 일부 제공자는 한 번에 받는 개수가 10~20개로 제한되지만, 게이트웨이가 알아서 나눠 호출하고 순서를 맞춰 돌려줍니다.
과금은 입력 토큰 기준입니다. 이미지 토큰도 같은 사용 내역에 합산됩니다.
조직에서 개인정보 필터를 켠 경우 input의 모든 문자열이 검사 대상입니다. 검사 자체에도 요금이 붙으므로, 대량 색인 작업 전에 관리자와 설정을 확인해 보세요.
이 엔드포인트는 문서 변환(OCR)을 하지 않습니다. 이미지는 그대로 제공자 모델에 전달됩니다.

마지막 수정 날짜: Sep 18, 2026

/gemini/v1beta

/rerank