---
title: "Embeddings"
method: POST
path: "/v1/embeddings"
tags: ["Search Foundation Models"]
---

# Embeddings

`POST /v1/embeddings`

Generate embeddings for text, images, or documents.

World-class multimodal multilingual embeddings for semantic search,
similarity matching, clustering, and classification tasks.

## Request body

- union
  - EmbeddingsV2Request — Jina Embeddings v2 text embedding models.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `normalized` boolean, nullable — If true (default), embeddings are L2-normalized to unit length.
    - `truncate` boolean, nullable — If true, truncates input exceeding the model's max token limit instead of returning an error.
    - `model` 'jina-embeddings-v2-base-en' | 'jina-embeddings-v2-base-zh' | 'jina-embeddings-v2-base-de' | 'jina-embeddings-v2-base-es' | 'jina-embeddings-v2-base-code', required — The embedding model to use.
    - `input` union, required — Text to embed: a string, `TextDoc`, or a list of items.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
  - EmbeddingsV3Request — Jina Embeddings v3 with task-specific optimization and flexible dimensions.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `normalized` boolean, nullable — If true (default), embeddings are L2-normalized to unit length.
    - `truncate` boolean, nullable — If true, truncates input exceeding the model's max token limit instead of returning an error.
    - `model` 'jina-embeddings-v3', required — The embedding model to use.
    - `input` union, required — Text to embed: a string, `TextDoc`, or a list of items.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
    - `task` 'retrieval.query' | 'retrieval.passage' | 'text-matching' | 'classification' | 'separation', nullable — Task optimization: `retrieval.query` for queries, `retrieval.passage` for documents, `text-matching` for similarity, `classification`, or `separation` for clustering.
    - `late_chunking` boolean, nullable — If true, concatenates all inputs and processes as one sequence before splitting. Useful for context across chunks.
    - `dimensions` integer, nullable — Number of dimensions for the output embedding. Range: 1-1024.
  - EmbeddingsV5Request — Jina Embeddings v5 model with task-specific LoRA adapters and flexible dimensions. Small/nano sizes support text-only; the omni variant also accepts images, videos, audio, and PDFs in a single shared vector space. Each top-level list item is a single modality (one Doc class), with one exception: a `MergedContentGroup` (`{"content": [...]}`) fuses multiple chunks (text + image/video/audio) into a single embedding via one model forward pass.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `normalized` boolean, nullable — If true (default), embeddings are L2-normalized to unit length.
    - `truncate` boolean, nullable — If true, truncates input exceeding the model's max token limit instead of returning an error.
    - `model` 'jina-embeddings-v5-text-nano' | 'jina-embeddings-v5-text-small' | 'jina-embeddings-v5-omni-small' | 'jina-embeddings-v5-omni-nano', required — The embedding model to use.
    - `input` union, required — Content to embed: a string, `TextDoc`, `ImageDoc`, `VideoDoc`, `AudioDoc`, `PDFDoc`, or a list of items. List items may also be `{content: [...]}` groups — mixed-modality chunks fused into ONE embedding per group. PDFs must be sent as single inputs, not in a list. Text-only model variants reject non-text items.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - ImageDoc
        - `image` string, required — Image as a URL or base64-encoded string.
      - VideoDoc
        - `video` string, required — Video as a URL or base64-encoded string.
      - AudioDoc
        - `audio` string, required — Audio as a URL or base64-encoded string.
      - PDFDoc
        - `pdf` string, required — PDF as a URL or base64-encoded string.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
          - ImageDoc
            - `image` string, required — Image as a URL or base64-encoded string.
          - VideoDoc
            - `video` string, required — Video as a URL or base64-encoded string.
          - AudioDoc
            - `audio` string, required — Audio as a URL or base64-encoded string.
          - MergedContentGroup — Mixed-modality chunks fused into ONE embedding per group. The executor sends every chunk to the model in a single forward pass (interleaved per the model's special-token convention) and returns one vector per `MergedContentGroup`. Order within `content` is semantically meaningful — re-ordering may change the resulting embedding. PDFs are intentionally not allowed inside `content`: they're rasterized to N per-page image prompts, which doesn't compose with single-pass fusion. Send PDFs as standalone single-input requests instead.
            - `content` union[], required — Ordered list of modality chunks (text / image / video / audio). Must contain at least one chunk.
              - …
    - `task` 'retrieval.query' | 'retrieval.passage' | 'text-matching' | 'clustering' | 'classification', nullable — Task optimization: `retrieval.query` for queries, `retrieval.passage` for documents, `text-matching` for similarity, `clustering`, or `classification`.
    - `dimensions` integer, nullable — Number of dimensions for the output embedding. Range: 1-1024.
  - EmbeddingsV4Request — Jina Embeddings v4 multimodal model for text, images, and PDFs.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `model` 'jina-embeddings-v4', required — The embedding model to use.
    - `input` union, required — Content to embed: a string, `TextDoc`, `ImageDoc`, `PDFDoc`, or a list of items. PDFs must be sent individually. Images up to 8MB; PDFs up to 8MB.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - ImageDoc
        - `image` string, required — Image as a URL or base64-encoded string.
      - PDFDoc
        - `pdf` string, required — PDF as a URL or base64-encoded string.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
          - ImageDoc
            - `image` string, required — Image as a URL or base64-encoded string.
    - `truncate` boolean, nullable — If true, truncates input exceeding the model's max token limit instead of returning an error.
    - `late_chunking` boolean, nullable — If true, concatenates all text inputs and processes as one sequence before splitting. Only works with text.
    - `dimensions` integer, nullable — Number of dimensions for the output embedding. Range: 1-2048.
    - `task` 'text-matching' | 'retrieval.query' | 'retrieval.passage' | 'code.query' | 'code.passage', nullable — Task optimization: `text-matching` (default), `retrieval.query`, `retrieval.passage`, `code.query`, or `code.passage`.
    - `return_multivector` boolean, nullable — If true, returns one embedding per token. Cannot be used with `dimensions`.
    - `return_tokenized_input` boolean, nullable — If true, returns tokens alongside multi-vector embeddings. Requires `return_multivector=true`.
  - CodeEmbeddings500MRequest — Code embedding model (500M) for code search and understanding.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `model` 'jina-code-embeddings-0.5b', required — The code embedding model to use.
    - `input` union, required — Code or text to embed: a string, `TextDoc`, or a list of items.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
    - `truncate` boolean, nullable — If true, truncates input exceeding the model's max token limit instead of returning an error.
    - `dimensions` integer, nullable — Number of dimensions for the output embedding. Range: 1-896.
    - `task` 'nl2code.query' | 'nl2code.passage' | 'qa.query' | 'qa.passage' | 'code2code.query' | 'code2code.passage' | 'code2nl.query' | 'code2nl.passage' | 'code2completion.query' | 'code2completion.passage', nullable — Task type: `nl2code`, `qa`, `code2code`, `code2nl`, or `code2completion`. Use `.query` for queries, `.passage` for documents.
  - CodeEmbeddings1500MRequest — Code embedding model (1.5B) for code search and understanding.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `model` 'jina-code-embeddings-1.5b', required — The code embedding model to use.
    - `input` union, required — Code or text to embed: a string, `TextDoc`, or a list of items.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
    - `truncate` boolean, nullable — If true, truncates input exceeding the model's max token limit instead of returning an error.
    - `dimensions` integer, nullable — Number of dimensions for the output embedding. Range: 1-1536.
    - `task` 'nl2code.query' | 'nl2code.passage' | 'qa.query' | 'qa.passage' | 'code2code.query' | 'code2code.passage' | 'code2nl.query' | 'code2nl.passage' | 'code2completion.query' | 'code2completion.passage', nullable — Task type: `nl2code`, `qa`, `code2code`, `code2nl`, or `code2completion`. Use `.query` for queries, `.passage` for documents.
  - ClipV1Request — CLIP v1 multimodal model for images and text in a shared vector space.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `normalized` boolean, nullable — If true (default), embeddings are L2-normalized to unit length.
    - `truncate` boolean, nullable — If true, truncates input exceeding the model's max token limit instead of returning an error.
    - `model` 'jina-clip-v1', required — The CLIP model to use.
    - `input` union, required — Content to embed: a string, `TextDoc`, `ImageDoc`, `PDFDoc`, or a list of items. PDFs must be sent individually. Images up to 8MB.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - ImageDoc
        - `image` string, required — Image as a URL or base64-encoded string.
      - PDFDoc
        - `pdf` string, required — PDF as a URL or base64-encoded string.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
          - ImageDoc
            - `image` string, required — Image as a URL or base64-encoded string.
  - ClipV2Request — CLIP v2 with Matryoshka representation learning for flexible dimensions.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `normalized` boolean, nullable — If true (default), embeddings are L2-normalized to unit length.
    - `truncate` boolean, nullable — If true, truncates input exceeding the model's max token limit instead of returning an error.
    - `model` 'jina-clip-v2', required — The CLIP model to use.
    - `input` union, required — Content to embed: a string, `TextDoc`, `ImageDoc`, `PDFDoc`, or a list of items. PDFs must be sent individually. Images up to 8MB.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - ImageDoc
        - `image` string, required — Image as a URL or base64-encoded string.
      - PDFDoc
        - `pdf` string, required — PDF as a URL or base64-encoded string.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
          - ImageDoc
            - `image` string, required — Image as a URL or base64-encoded string.
    - `task` 'retrieval.query', nullable — Set to `retrieval.query` to optimize for search queries. Leave unset for documents.
    - `dimensions` integer, nullable — Number of dimensions for the output embedding. Range: 1-1024.
  - ColbertV1Request — ColBERT v1 for token-level late interaction retrieval.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `model` 'jina-colbert-v1-en', required — The ColBERT model to use.
    - `input` union, required — Text to embed: a string, `TextDoc`, or a list of items.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
    - `input_type` 'query' | 'document', nullable — Role of the input: `query` for search queries, `document` for passages.
  - ColbertV2Request — ColBERT v2 with Matryoshka representation learning for flexible dimensions.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `model` 'jina-colbert-v2', required — The ColBERT model to use.
    - `input` union, required — Text to embed: a string, `TextDoc`, or a list of items.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
    - `input_type` 'query' | 'document', nullable — Role of the input: `query` for search queries, `document` for passages.
    - `dimensions` 64 | 96 | 128, nullable — Dimensions per token: `64`, `96`, or `128`. Defaults to 128.
  - ELSERV2Request — ELSER v2 request schema.
    - `embedding_type` union — Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these.
      - 'float' | 'base64' | 'binary' | 'ubinary'
      - string[]
    - `model` 'elser-v2', required — The sparse embedding model to use.
    - `input` union, required — Text to embed: a string, `TextDoc`, or a list of items.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - union[]
        - union
          - string
          - TextDoc
            - `text` string, required — Text content to process.
    - `task` 'retrieval.query' | 'retrieval.passage', nullable — Task optimization: `retrieval.query` for queries, `retrieval.passage` for documents.

## Response `200`

Successful Response

- EmbeddingResponse — Response containing embeddings for all input items.
  - `model` string, required — The model used to generate the embeddings.
  - `object` string — Object type, always `list`.
  - `usage` union, required — Token usage statistics.
    - EmbeddingUsage — Token usage statistics for embedding requests. `prompt_tokens` counts text input tokens (including the task prefix and any structural/special framing). For text-only models — and any response that doesn't populate a per-modality breakdown — it equals `total_tokens`. For multimodal v5-omni responses, `total_tokens` is the aggregate across all modalities and the per-modality fields (`image_tokens` / `audio_tokens` / `video_tokens`) are sub-counts, so the invariant holds exactly (absent per-modality fields count as 0): total_tokens == prompt_tokens + image_tokens + audio_tokens + video_tokens PDF pages are rendered to images and counted in `image_tokens`. All MM fields are Optional so text-only responses don't have to populate them, and serializers should drop unset fields (`exclude_none=True`).
      - `total_tokens` integer, required — Total number of tokens processed.
      - `prompt_tokens` integer, required — Number of text input tokens. For multimodal responses the per-modality fields below account for non-text tokens; for text-only responses this equals `total_tokens`.
      - `image_tokens` integer, nullable — Number of tokens from image inputs.
      - `audio_tokens` integer, nullable — Number of tokens from audio inputs.
      - `video_tokens` integer, nullable — Number of tokens from video inputs.
    - ELSERV2EmbeddingUsage — Token usage statistics for Elser v2 embedding requests.
      - `total_tokens` integer, required — Total number of tokens processed.
      - `input_tokens` integer, required — Number of tokens in the input.
      - `output_tokens` integer, required — Number of tokens in the output.
    - BaseUsage
      - `total_tokens` integer, required — Total number of tokens processed.
  - `data` union, required — List of embeddings, one per input item. For sparse embeddings (elser-v2), this is a list of dicts mapping tokens to scores.
    - SingleEmbeddingData[]
      - `object` string — Object type, always `embedding`.
      - `index` integer, required — Position of this embedding in the input list.
      - `embedding` union, required — The embedding vector: a list of floats for dense embeddings, a dict of token->score for sparse embeddings, or a base64 string for other encodings.
        - string
        - number[]
        - object
    - MultiEmbeddingData[]
      - `object` string — Object type, always `embeddings` for multi-vector output.
      - `index` integer, required — Position of this result in the input list.
      - `embeddings` union, required — Per-token embedding vectors. Each is a list of floats or base64 string.
        - string[]
        - array[]
          - number[]
      - `tokenized_input` string[], nullable — Tokens corresponding to each embedding, if `return_tokenized_input=true`.
    - object[]

## Other responses

- `400` — - **INPUT_MODEL_NOT_FOUND**: Model 'model_name' not found. Available models: .... - **INPUT_INVALID_LABELS**: Invalid training labels. At least {min_labels} unique labels are required for training. - **INPUT_LABEL_LIMIT_EXCEEDED**: Label limit exceeded: {current} labels provided, maximum N allowed for your plan. Reduce the number of labels or upgrade your plan at https://jina.ai/api-dashboard/key-manager. - **INPUT_TOKEN_LIMIT_EXCEEDED**: Input text exceeds the model's maximum of {max_tokens} tokens. Use 'truncate: true' to automatically truncate, or split into smaller chunks.
- `401` — - **AUTH_MISSING_API_KEY**: Authentication required. Provide your API key via the Authorization header: 'Authorization: Bearer <api-key>'. Get your API key at https://jina.ai/api-dashboard/key-manager. - **AUTH_INVALID_API_KEY**: Invalid API key. Verify your API key at https://jina.ai/api-dashboard/key-manager or generate a new one. - **AUTH_INVALID_FORMAT**: Invalid authorization format. Use 'Authorization: Bearer <api-key>' with a valid Jina API key (65 characters, starts with 'jina_').
- `403` — - **AUTHZ_INSUFFICIENT_BALANCE**: Insufficient account balance. Top up your account at https://jina.ai/api-dashboard/key-manager. - **AUTHZ_RESOURCE_LIMIT_EXCEEDED**: Resource limit exceeded for your plan. Current: {current}, limit: N. Delete existing resources or upgrade your plan at https://jina.ai/api-dashboard/key-manager.
- `404` — - **RESOURCE_NOT_FOUND**: {resource_type} '{resource_id}' not found or access denied. Verify the ID and your permissions.
- `409` — - **CONFLICT_RESOURCE_BUSY**: {resource_type} '{resource_id}' is currently being modified. Please retry after a few moments.
- `422` — Validation Error
- `429` — - **RATE_REQUEST_LIMIT_EXCEEDED**: Request rate limit exceeded: {current}/N requests per minute. Reduce request frequency or upgrade your plan at https://jina.ai/api-dashboard/key-manager. - **RATE_TOKEN_LIMIT_EXCEEDED**: Token rate limit exceeded: {current:,}/{limit:,} tokens per minute. Reduce batch sizes or upgrade your plan at https://jina.ai/api-dashboard/key-manager. - **RATE_CONCURRENCY_LIMIT_EXCEEDED**: Concurrency limit exceeded: {current}/N concurrent requests. Wait for pending requests to complete before sending new ones. - **RATE_IP_LIMIT_EXCEEDED**: IP rate limit exceeded. Too many requests from this IP address. Reduce request frequency.
- `500` — - **INTERNAL_ERROR**: An unexpected error occurred. If this persists, contact support with the request_id from this response.
- `503` — - **SERVICE_UNAVAILABLE**: Service temporarily unavailable. Please retry with exponential backoff.
- `504` — - **SERVICE_TIMEOUT**: Service request timed out. Try with smaller inputs or retry later.

---

[API](https://skmtc.net/jina/apis/jina-search-foundation-api.md) · [All operations](https://skmtc.net/jina/apis/jina-search-foundation-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/jina/jina-search-foundation-api/revisions/0ae64d1cd6e1/schema)