Overview
v2 embeds text and images into a shared space, so a text query can retrieve documents, passages, photos, and document screenshots. Use one vector per document for document-level retrieval, or context-aware vectors per chunk to retrieve specific passages. The 9B model’s 1024-dimensional MRL output and the 0.6B model’s 1024-dimensional output share the same embedding space, so you can index with either model and query with the other.Models
- 0.6B: Recommended default for higher throughput and lower latency.
- 9B: Choose for retrieval quality.
Basic Usage
Queries
Embed search queries with the same model you used for the documents andinput_type: "query". Each query returns one embedding in data[i].embedding:
query only for the text a user types to search. Titles, summaries, FAQ entries, and any other text you index are documents, even when they are short. Embedding the same string as a query and as a document gives two different vectors for optimised performance.
Document
Standard document usage
For standard whole-document embeddings, pass a string or a flat array of strings withinput_type: "document". Each string is a complete document and returns one vector in data[i].embedding. You do not need to split the document into chunks, but it must fit within the model’s token limit.
Document chunks
Each chunk is embedded in the context of its entire document. Pass documents as nested arrays, with one ordered array of chunks per document andinput_type: "document"; the API returns one context-aware embedding per chunk.
Response (excerpt)
Response (excerpt)
embedding is a base64 string of signed 8-bit integers, one per dimension. Decode it before storing or comparing it.
Images
Send JPEG, PNG, or WebP images as base64 data URIs withinput_type: "document". Animated images are not supported.
num_chunks defaults to 1, returning one embedding per image. Increasing it can improve retrieval performance for document screenshots, such as research paper pages or other text-rich images. Each region is embedded separately, from top to bottom. Small images may return fewer regions than requested.
Response (excerpt, num_chunks: 4)
Response (excerpt, num_chunks: 4)
num_chunks above 1, each image returns a list object whose data holds one embedding per region, ordered from top to bottom. With the default num_chunks: 1, each image returns a single embedding in data[i].embedding, as for whole documents.
Search images or regions with text queries using input_type: "query".
Image token usage depends on image size and num_chunks; see usage.prompt_tokens for the exact count.
Inputs
The shape ofinput decides the shape of the response:
A request holds either text or images, not both. Queries must be plain strings; a nested array or an image with
input_type: "query" returns HTTP 400.
Parameters
UsePOST /v1/embeddings.
Decode
base64_int8 to signed int8 values, cast to float32, and use cosine similarity. For inner product, L2-normalize both query and document vectors first. Use Hamming distance for base64_binary.v1 Models
v1 models will be phased out during 2027. New users should use v2 models; existing users are encouraged to migrate to v2.
All v1 models accept text only; omit
input_type and num_chunks. dimensions accepts multiples of 8 from 128 to 1024 (0.6B) or 2560 (4B). encoding_format accepts base64_int8 (default) or base64_binary.
Input limits: Up to 512 texts or documents per request, 32,768 tokens per text or document, and 120,000 tokens per request. Empty strings and chunk lists are rejected. Contextualized models accept up to 16,000 total chunks.
Standard Embeddings
pplx-embed-v1-0.6b and pplx-embed-v1-4b use POST /v1/embeddings to embed independent texts. Send a string or flat array of strings for documents and queries, using the same model for both. Each input returns one vector in data[i].embedding.
Basic Usage
Generate embeddings for a list of texts:Response (excerpt)
Response (excerpt)
Contextualized Embeddings
pplx-embed-context-v1-0.6b and pplx-embed-context-v1-4b use mean pooling and require no instruction prefix. They run on POST /v1/contextualizedembeddings and embed text only. Embed queries with the same model by wrapping each query as a single-element inner list (e.g., [[query]]). The same chunking rules apply: non-overlapping chunks, in source order.
Response (excerpt)
Response (excerpt)
Related Resources
Quickstart
Get started with v2 embeddings for whole documents, queries, chunks, and images.
Search Your Docs Folder
A command-line tool that indexes a folder of Markdown with pplx-embed-v2 in dense and contextual mode, shows the top chunks side by side, and scores both on your questions.