API reference

Embeddings API

Base URL https://api.similar.dev/v1. The endpoint follows the OpenAI embeddings wire format, so any client that already speaks that shape works after changing the base URL, API key, and model ID.

Quickstart in your language

Each snippet embeds two documents with the English flagship and reads back 512-dimensional vectors. Replace sme_your_account_... with your key.

embed.py
from openai import OpenAI

client = OpenAI(
    api_key="sme_your_account_...",
    base_url="https://api.similar.dev/v1",
)

response = client.embeddings.create(
    model="similar.dev-en-v1-medium-512",
    input=["First document.", "Second document."],
)

vectors = [item.embedding for item in response.data]
print(len(vectors[0]))  # 512

Authentication

Send your key as Authorization: Bearer sme_.... The API also accepts X-API-Key and, for quick tests, ?api_key=. Keys are minted after the initial credit deposit on the Developer plan.

POST /v1/embeddings

FieldTypeNotes
modelstringAny published model ID. See the catalog below.
inputstring or string[]Up to 100 documents per request.
input_typestring, optionalDefaults to document.
dimsinteger, optionalClip output below 512 with renormalization. Omit for the full 512.

Response: {"object": "list", "data": [{"object": "embedding", "index": 0, "embedding": [...]}], "model": "...", "usage": {"prompt_tokens": n, "total_tokens": n}}.

Model IDs

IDLocaleBest for
similar.dev-en-v1-medium-512en-USEnglish flagship. Retrieval, clustering, semantic search.
similar.dev-en-v1-lite-512en-USHigh-volume English pipelines where cost dominates.
similar.dev-lang3-lite-512en-US, es-419, pt-BRCross-language document similarity in one space.

GET /v1/models

Authenticated clients receive every model ID available to the account. Select models by ID in code rather than assuming the current default is the whole catalog.

Similarity

Compare vectors with cosine similarity. Outputs are float32 and not guaranteed to have unit L2 length; normalize inside your index if it requires unit vectors.

Limits

Model lifecycle

Every published model ID remains callable for a minimum of five years from launch before any retirement notice. Language-specific endpoints and custom-fit models will carry the same commitment when released.

Start with $10 deposit