Embeddings API — 엔드포인트와 파라미터

Embeddings API — 엔드포인트와 파라미터

Jina AI Search Foundation API는 비전·오디오·코드까지 다루는 생성·추론 API 묶음이에요. 그중 임베딩은 텍스트·이미지·코드를 고정 길이 벡터로 변환해 의미 검색, 클러스터링, 분류에 쓰여요.

출처: https://docs.jina.ai/

Endpoint: https://api.jina.ai/v1/embeddings

  • Method: POST, Authorization: HTTPBearer
  • Headers: Authorization: Bearer $JINA_API_KEY, Content-Type: application/json, Accept: application/json

요청 본문에서 중요한 파라미터를 보면 이래요.

  • model(string, required) — 사용할 모델 식별자
  • input(array, required) — 임베딩할 입력 문자열 배열
  • embedding_type(default float) — float/base64/binary/ubinary
  • task — 다운스트림 용도로 임베딩 출력을 최적화: retrieval.query, retrieval.passage, text-matching, classification, clustering
  • dimensions(integer) — 지정하면 출력 임베딩을 그 크기로 절단
  • normalized(boolean, default false) — 단위 L2 노름으로 정규화할지
  • late_chunking(boolean, default false) — 모든 문장을 하나로 이어 단일 입력으로 처리
  • truncate(boolean, default false) — 최대 컨텍스트를 넘는 꼬리를 자동으로 버릴지

대량 처리는 Batch Embeddings API가 있어요.

Endpoint: https://api.jina.ai/v1/batch/embeddings

작업 흐름은 이래요.

  1. Submit: POST /v1/batch/embeddings — 즉시 batch_id 반환(HTTP 202)
  2. Poll: GET /v1/batch/{batch_id} — 상태(submitted, processing, completed, failed, cancelled) 확인
  3. Download: 완료 후 GET /v1/batch/{batch_id}/output — 출력 JSONL 스트리밍
  4. Cancel: DELETE /v1/batch/{batch_id}
  5. Errors: GET /v1/batch/{batch_id}/errors

인라인 입력은 최대 10,000개 항목을 지원해요. 수천~수백만 문서를 처리하는 대규모 임베딩·오프라인 인덱싱에 적합해요.

레이트 리밋은 아래처럼 나뉘어요.

  • Embedding & Reranker API: 500 RPM & 1M TPM (프리미엄 2k RPM & 5M TPM)
  • r.jina.ai(Reader): 500 RPM (프리미엄 5k RPM)
  • s.jina.ai(Search): 100 RPM (프리미엄 1000 RPM)

더 알아보기