Embeddings API

Overview

Perplexity’s Embeddings API generates high-quality text embeddings for semantic search and retrieval. Choose between standard embeddings for independent texts or contextualized embeddings for document chunks that share context.

We recommend using our official SDKs for a more convenient and type-safe way to interact with the Embeddings API.

Pricing

Pay-as-you-go pricing for all APIs. No subscription required.

Available Models

Model	Dimensions	Context	MRL	Quantization	Price ($/1M tokens)
`pplx-embed-v1-0.6b`	1024	32K	Yes	INT8/BINARY	$0.004
`pplx-embed-v1-4b`	2560	32K	Yes	INT8/BINARY	$0.03
`pplx-embed-context-v1-0.6b`	1024	32K	Yes	INT8/BINARY	$0.008
`pplx-embed-context-v1-4b`	2560	32K	Yes	INT8/BINARY	$0.05

All models use mean pooling and require no instruction prefix—you can embed text directly without prompt engineering.

Perplexity embeddings are unnormalized. Always compare base64_int8 embeddings via cosine similarity (not inner product or L2 distance). Compare base64_binary embeddings via Hamming distance. See Best Practices for details and normalization helpers.

When to use which:

Standard embeddings (pplx-embed-v1-*) - Independent texts, search queries, single sentences
Contextualized embeddings (pplx-embed-context-v1-*) - Document chunks that benefit from shared context (e.g., paragraphs from the same article)

Installation

pip install perplexityai numpy

npm install @perplexity-ai/perplexity_ai

Authentication

Set your API key as an environment variable:

macOS/Linux
Windows

export PERPLEXITY_API_KEY="your_api_key_here"

setx PERPLEXITY_API_KEY "your_api_key_here"

Confirm the key is set without printing it:

macOS/Linux
Windows

test -n "$PERPLEXITY_API_KEY" && echo "PERPLEXITY_API_KEY is set" || echo "PERPLEXITY_API_KEY is not set"

if ($env:PERPLEXITY_API_KEY) { "PERPLEXITY_API_KEY is set" } else { "PERPLEXITY_API_KEY is not set" }

Never print the key or any part of it. Commands like env, echo $PERPLEXITY_API_KEY, or a prefix or length check leave the key in shell history, logs, and coding-agent transcripts. Read the key from the environment in code and tests, and don’t paste it into fixtures or commit messages.

Add embeddings to an existing project

A standalone script that embeds a few strings and prints vectors proves the key works, but nothing in your app calls it, so your users never see a result. Instead, one module owns the client, an indexing function takes the records your app already has and saves each vector where that record already lives, and an existing route or view calls a ranking function that reads those stored vectors. The example below adds related help articles to a support app, with Python under app/ and TypeScript under src/.

Create one embeddings module

Put the client in a single module so the model ID, batching, decoding, and similarity metric live in one place. The library reads PERPLEXITY_API_KEY from the environment; do not pass the key in code or commit it. embed returns the base64 int8 strings the API sends back. Store that string with the record (a text column, a JSON field, or a document property) and decode it when you compare.Python: app/embeddings.py. TypeScript: src/embeddings.ts.

import base64
from typing import Final

import numpy as np
from perplexity import Perplexity

MODEL: Final = "pplx-embed-v1-4b"
# A request takes up to 512 texts and 120,000 tokens in total. Lower this if your records are long.
BATCH_SIZE = 100

_client: Perplexity | None = None


def client() -> Perplexity:
    """One client per process. Reads PERPLEXITY_API_KEY from the environment."""
    global _client
    if _client is None:
        _client = Perplexity()
    return _client


def embed(texts: list[str]) -> list[str]:
    """Return one base64 int8 embedding per input text, in input order."""
    out: list[str] = []
    for i in range(0, len(texts), BATCH_SIZE):
        response = client().embeddings.create(input=texts[i : i + BATCH_SIZE], model=MODEL)
        for item in sorted(response.data or [], key=lambda d: d.index or 0):
            if not item.embedding:
                raise RuntimeError(f"Embeddings API returned no embedding for input {item.index}")
            out.append(item.embedding)
    return out


def decode(b64: str) -> np.ndarray:
    """Decode a stored base64 int8 embedding to float32."""
    return np.frombuffer(base64.b64decode(b64), dtype=np.int8).astype(np.float32)


def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
    """Perplexity embeddings are unnormalized. Compare with cosine, not a raw dot product."""
    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))

import Perplexity from '@perplexity-ai/perplexity_ai';

export const MODEL = "pplx-embed-v1-4b";
// A request takes up to 512 texts and 120,000 tokens in total. Lower this if your records are long.
const BATCH_SIZE = 100;

let client: Perplexity | undefined;

function getClient(): Perplexity {
    // One client per process. The SDK reads PERPLEXITY_API_KEY from the environment.
    if (!client) {
        client = new Perplexity();
    }
    return client;
}

export async function embed(texts: string[]): Promise<string[]> {
    // Return one base64 int8 embedding per input text, in input order.
    const out: string[] = [];
    for (let i = 0; i < texts.length; i += BATCH_SIZE) {
        const response = await getClient().embeddings.create({
            input: texts.slice(i, i + BATCH_SIZE),
            model: MODEL,
        });
        const items = [...(response.data ?? [])].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
        for (const item of items) {
            if (!item.embedding) {
                throw new Error(`Embeddings API returned no embedding for input ${item.index}`);
            }
            out.push(item.embedding);
        }
    }
    return out;
}

export function decode(b64: string): Float32Array {
    // Decode a stored base64 int8 embedding to float32.
    const buffer = Buffer.from(b64, 'base64');
    const int8 = new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
    return Float32Array.from(int8);
}

export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
    // Perplexity embeddings are unnormalized. Compare with cosine, not a raw dot product.
    let dot = 0, normA = 0, normB = 0;
    for (let i = 0; i < a.length; i++) {
        dot += a[i] * b[i];
        normA += a[i] * a[i];
        normB += b[i] * b[i];
    }
    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

Index the records your app already has, then rank from storage

Two functions, both working against the app’s existing article store. index_articles embeds every article that has body text and no vector yet and saves the vector on that article through the store the app already uses. related_articles embeds only the incoming question and ranks the stored vectors. Neither builds its own client, and the embedding function is a parameter with a default so tests can pass a fake. When an article’s body changes, clear its stored embedding (None in Python, null in TypeScript) in the same update so the next index_articles run embeds the new text.Python: app/support/related_articles.py. TypeScript: src/support/relatedArticles.ts.

from collections.abc import Callable
from typing import Protocol

from app.embeddings import cosine_similarity, decode, embed


class Article(Protocol):
    id: str
    body: str
    embedding: str | None  # base64 int8 from the Embeddings API, stored with the row


class ArticleStore(Protocol):
    def all(self) -> list[Article]: ...
    def save_embedding(self, article_id: str, embedding: str) -> None: ...


EmbedFn = Callable[[list[str]], list[str]]


def index_articles(store: ArticleStore, embed_fn: EmbedFn = embed) -> int:
    """Embed articles that have no vector yet and save each vector on its article.

    Call this from the existing publish hook, or once as a backfill.
    """
    # The API rejects empty strings, so skip articles with no body text.
    pending = [article for article in store.all() if article.embedding is None and article.body.strip()]
    if not pending:
        return 0
    for article, vector in zip(pending, embed_fn([article.body for article in pending]), strict=True):
        store.save_embedding(article.id, vector)
    return len(pending)


def related_articles(
    question: str,
    store: ArticleStore,
    top_k: int = 3,
    embed_fn: EmbedFn = embed,
) -> list[tuple[Article, float]]:
    """Rank indexed articles by similarity to a customer question.

    Called from the existing ticket view, where it replaces a keyword match.
    """
    indexed = [(article, article.embedding) for article in store.all() if article.embedding is not None]
    if not indexed:
        return []
    question_vector = decode(embed_fn([question])[0])
    scored = [(article, cosine_similarity(question_vector, decode(vector))) for article, vector in indexed]
    scored.sort(key=lambda pair: pair[1], reverse=True)
    return scored[:top_k]

import { cosineSimilarity, decode, embed } from '../embeddings';

export interface Article {
    id: string;
    body: string;
    embedding: string | null; // base64 int8 from the Embeddings API, stored with the record
}

export interface ArticleStore {
    all(): Promise<Article[]>;
    saveEmbedding(articleId: string, embedding: string): Promise<void>;
}

export type EmbedFn = (texts: string[]) => Promise<string[]>;

// Embed articles that have no vector yet and save each vector on its article.
// Call this from the existing publish hook, or once as a backfill.
export async function indexArticles(store: ArticleStore, embedFn: EmbedFn = embed): Promise<number> {
    // The API rejects empty strings, so skip articles with no body text.
    const pending = (await store.all()).filter((article) => article.embedding === null && article.body.trim() !== '');
    if (pending.length === 0) {
        return 0;
    }
    const vectors = await embedFn(pending.map((article) => article.body));
    if (vectors.length !== pending.length) {
        throw new Error(`Expected ${pending.length} embeddings, got ${vectors.length}`);
    }
    for (const [i, article] of pending.entries()) {
        await store.saveEmbedding(article.id, vectors[i]);
    }
    return pending.length;
}

// Rank indexed articles by similarity to a customer question.
// Called from the existing ticket view, where it replaces a keyword match.
export async function relatedArticles(
    question: string,
    store: ArticleStore,
    topK = 3,
    embedFn: EmbedFn = embed,
): Promise<Array<{ article: Article; score: number }>> {
    const indexed = (await store.all()).filter((article) => article.embedding !== null);
    if (indexed.length === 0) {
        return [];
    }
    const [questionVector] = (await embedFn([question])).map(decode);
    return indexed
        .map((article) => ({ article, score: cosineSimilarity(questionVector, decode(article.embedding as string)) }))
        .sort((a, b) => b.score - a.score)
        .slice(0, topK);
}

Then call it from the route or view that already renders the ticket. The change in the existing handler is one call plus one response field:

# app/routes/tickets.py (existing route)
from app.support.related_articles import related_articles


@router.get("/tickets/{ticket_id}")
def show_ticket(ticket_id: str):
    ticket = tickets.get(ticket_id)
    related = related_articles(ticket.question, article_store)
    return {
        "ticket": ticket,
        "related_articles": [{"id": article.id, "score": round(score, 3)} for article, score in related],
    }

// src/app/api/tickets/[id]/route.ts (existing Next.js route)
import { relatedArticles } from '@/support/relatedArticles';

export async function GET(_request: Request, { params }: { params: Promise<{ id: string }> }) {
    const { id } = await params;
    const ticket = await tickets.get(id);
    const related = await relatedArticles(ticket.question, articleStore);
    return Response.json({
        ticket,
        relatedArticles: related.map(({ article, score }) => ({ id: article.id, score: Number(score.toFixed(3)) })),
    });
}

Test the caller, then run the whole suite

Test the feature, not the API. With an in-memory store and a fake embedding function, check that indexing saves a vector on each article that lacked one, and that ranking uses cosine similarity (a large-magnitude vector must not win on dot product alone). One live check runs only when PERPLEXITY_API_KEY is set.Python: tests/test_related_articles.py. TypeScript: tests/relatedArticles.test.ts.

import base64
import os
from dataclasses import dataclass

import numpy as np
import pytest

from app.support.related_articles import index_articles, related_articles


@dataclass
class Article:
    id: str
    body: str
    embedding: str | None = None


class MemoryStore:
    def __init__(self, articles):
        self.articles = {article.id: article for article in articles}

    def all(self):
        return list(self.articles.values())

    def save_embedding(self, article_id, embedding):
        self.articles[article_id].embedding = embedding


def b64(*values):
    """Build a base64 int8 string the way the API returns one."""
    return base64.b64encode(np.array(values, dtype=np.int8).tobytes()).decode()


ARTICLES = [
    Article("reset-password", "How to reset your password from the login page."),
    Article("export-data", "Export your workspace data as CSV or JSON."),
    Article("billing", "Update the card on file and download invoices."),
]
QUESTION = "I need to download all my data"
# The billing vector has the largest dot product with the question.
# Cosine similarity must still rank the export article first.
FAKE = {
    QUESTION: b64(1, 0, 0),
    ARTICLES[0].body: b64(0, 1, 0),
    ARTICLES[1].body: b64(20, 1, 0),
    ARTICLES[2].body: b64(50, 60, 0),
}


def fake_embed(texts):
    return [FAKE[text] for text in texts]


def fresh_store():
    return MemoryStore([Article(article.id, article.body) for article in ARTICLES])


def test_index_saves_a_vector_on_each_unindexed_article():
    store = fresh_store()
    assert index_articles(store, embed_fn=fake_embed) == 3
    assert all(article.embedding for article in store.all())
    assert index_articles(store, embed_fn=fake_embed) == 0  # nothing left to embed


def test_ranks_by_cosine_not_magnitude():
    store = fresh_store()
    index_articles(store, embed_fn=fake_embed)
    [(article, score)] = related_articles(QUESTION, store, top_k=1, embed_fn=fake_embed)
    assert article.id == "export-data"
    assert 0.99 < score <= 1.0


@pytest.mark.skipif("PERPLEXITY_API_KEY" not in os.environ, reason="live check needs an API key")
def test_live_ranking():
    store = fresh_store()
    index_articles(store)
    [(article, _)] = related_articles("I forgot my password", store, top_k=1)
    assert article.id == "reset-password"

import { test } from 'node:test';
import assert from 'node:assert/strict';

import { indexArticles, relatedArticles, type Article, type ArticleStore } from '../src/support/relatedArticles';

class MemoryStore implements ArticleStore {
    private articles: Map<string, Article>;
    constructor(articles: Article[]) {
        this.articles = new Map(articles.map((article) => [article.id, { ...article }]));
    }
    async all() {
        return [...this.articles.values()];
    }
    async saveEmbedding(articleId: string, embedding: string) {
        this.articles.get(articleId)!.embedding = embedding;
    }
}

// Build a base64 int8 string the way the API returns one.
const b64 = (...values: number[]) => Buffer.from(Int8Array.from(values).buffer).toString('base64');

const ARTICLES: Article[] = [
    { id: 'reset-password', body: 'How to reset your password from the login page.', embedding: null },
    { id: 'export-data', body: 'Export your workspace data as CSV or JSON.', embedding: null },
    { id: 'billing', body: 'Update the card on file and download invoices.', embedding: null },
];
const QUESTION = 'I need to download all my data';
// The billing vector has the largest dot product with the question.
// Cosine similarity must still rank the export article first.
const FAKE: Record<string, string> = {
    [QUESTION]: b64(1, 0, 0),
    [ARTICLES[0].body]: b64(0, 1, 0),
    [ARTICLES[1].body]: b64(20, 1, 0),
    [ARTICLES[2].body]: b64(50, 60, 0),
};
const fakeEmbed = async (texts: string[]) => texts.map((text) => FAKE[text]);

test('index saves a vector on each unindexed article', async () => {
    const store = new MemoryStore(ARTICLES);
    assert.equal(await indexArticles(store, fakeEmbed), 3);
    assert.ok((await store.all()).every((article) => article.embedding));
    assert.equal(await indexArticles(store, fakeEmbed), 0); // nothing left to embed
});

test('ranks by cosine, not magnitude', async () => {
    const store = new MemoryStore(ARTICLES);
    await indexArticles(store, fakeEmbed);
    const [top] = await relatedArticles(QUESTION, store, 1, fakeEmbed);
    assert.equal(top.article.id, 'export-data');
    assert.ok(top.score > 0.99 && top.score <= 1);
});

test('live ranking', { skip: !process.env.PERPLEXITY_API_KEY }, async () => {
    const store = new MemoryStore(ARTICLES);
    await indexArticles(store);
    const [top] = await relatedArticles('I forgot my password', store, 1);
    assert.equal(top.article.id, 'reset-password');
});

Run the new test, then the project’s full test command, so the change is checked the same way the rest of the app is:

pytest tests/test_related_articles.py
pytest

npx tsx --test tests/relatedArticles.test.ts
npm test

Prepare vectors for a vector database

The steps above store the base64 string the API returns and decode it when they compare. Most vector databases want float vectors at insert time instead. The adapter below decodes each base64 int8 string into a float32 row, one row per input text in input order, and pairs each row with its record id. It stops there: it does not create a collection or write to a database. Casting the int8 values to float does not restore a full-precision embedding: you store the same quantized vector in a wider type, and cosine similarity still applies. To hand these records to a database:

Create the collection or index with the embedding dimension: 2560 for pplx-embed-v1-4b, 1024 for pplx-embed-v1-0.6b, or the dimensions value you requested.
Map each record to your database’s upsert shape. Field names and id rules differ: Pinecone expects values, and Qdrant expects vector with integer or UUID ids.
Use cosine similarity. If the database only supports inner product, L2-normalize both the stored vectors and the query vectors first (see Best Practices).

The Python example uses NumPy, and the TypeScript example uses Node.js (Buffer). Both stop with an error if the response is missing an embedding.

import base64

import numpy as np
from perplexity import Perplexity

client = Perplexity()

articles = {
    "reset-password": "How to reset your password from the login page.",
    "export-data": "Export your workspace data as CSV or JSON.",
}
response = client.embeddings.create(input=list(articles.values()), model="pplx-embed-v1-4b")

# One float32 row per input, in input order: shape (len(articles), 2560).
rows = []
for item in sorted(response.data or [], key=lambda item: item.index or 0):
    if not item.embedding:
        raise RuntimeError(f"Embeddings API returned no embedding for input {item.index}")
    rows.append(np.frombuffer(base64.b64decode(item.embedding), dtype=np.int8).astype(np.float32))
vectors = np.stack(rows)
print(vectors.shape, vectors.dtype)

# Intermediate records: map "id" and "vector" to your database's upsert fields.
records = [{"id": article_id, "vector": vectors[i].tolist()} for i, article_id in enumerate(articles)]
print(records[0]["id"], len(records[0]["vector"]))

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const articles: Record<string, string> = {
    'reset-password': 'How to reset your password from the login page.',
    'export-data': 'Export your workspace data as CSV or JSON.',
};
const response = await client.embeddings.create({
    input: Object.values(articles),
    model: 'pplx-embed-v1-4b',
});

// One Float32Array per input, in input order; each has 2560 entries. Node.js only: uses Buffer.
const vectors = [...(response.data ?? [])]
    .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
    .map((item) => {
        if (!item.embedding) {
            throw new Error(`Embeddings API returned no embedding for input ${item.index}`);
        }
        const buffer = Buffer.from(item.embedding, 'base64');
        return Float32Array.from(new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength));
    });
console.log(vectors.length, vectors[0].length);

// Intermediate records: map "id" and "vector" to your database's upsert fields.
const records = Object.keys(articles).map((id, i) => ({ id, vector: Array.from(vectors[i]) }));
console.log(records[0].id, records[0].vector.length);

For contextualized embeddings of chunks from one document, Matryoshka dimension reduction, binary embeddings and Hamming distance, and the RAG pattern, see Best Practices.

Next Steps

Standard Embeddings

Embed independent texts, queries, and sentences.

Contextualized Embeddings

Document-aware embeddings for chunks that share context.

Best Practices

Batch processing, caching, RAG patterns, and performance optimization.

Model Cards

See the model cards on HuggingFace.

Getting Started

Orchestrator API

Agent API

Search API

Decisions API

Perplexity SDK

Admin & Management

Resources

Embeddings API

Overview

Pricing

Available Models

Installation

Authentication

Add embeddings to an existing project

Prepare vectors for a vector database

Next Steps

Standard Embeddings

Contextualized Embeddings

Best Practices

Model Cards

​Overview

Pricing

​Available Models

​Installation

​Authentication

​Add embeddings to an existing project

​Prepare vectors for a vector database

​Next Steps

Standard Embeddings

Contextualized Embeddings

Best Practices

Model Cards

Overview

Available Models

Installation

Authentication

Add embeddings to an existing project

Prepare vectors for a vector database

Next Steps