Embeddings & Semantic Search¶
POST /v1/text/embed turns a batch of strings into dense vectors. It runs on a GPU worker with the all-MiniLM-L6-v2 sentence-embedding model (384 dimensions), which is a good default for semantic search, clustering, near-duplicate detection, and RAG retrieval where you want cosine similarity over meaning rather than over words.
This is the semantic counterpart to the lexical tools in Similarity and Diff: similarity compares two strings with Levenshtein/cosine/Jaccard, embed gives you the vectors so you can compare any pair, thousands of them, or index a whole corpus.
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/v1/text/embed |
Embed a batch of 1–100 texts |
Base URL¶
https://textanalysis.toolkitapi.io
All requests need an X-API-Key header.
Request¶
The body is a bare JSON array of strings — not an object with a texts key.
| Field | Type | Required | Constraints |
|---|---|---|---|
| (body) | string[] |
Yes | 1–100 entries. Empty array → 422. More than 100 → 422. |
curl -X POST "https://textanalysis.toolkitapi.io/v1/text/embed" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '[
"How do I rotate an API key?",
"Where can I change my API credentials?",
"The cat sat on the mat."
]'
Python¶
import requests
resp = requests.post(
"https://textanalysis.toolkitapi.io/v1/text/embed",
headers={"X-API-Key": API_KEY},
json=[
"How do I rotate an API key?",
"Where can I change my API credentials?",
"The cat sat on the mat.",
],
timeout=120, # GPU cold start can take a few seconds
)
data = resp.json()
print(data["model"], data["dimensions"], data["count"])
vectors = data["embeddings"]
JavaScript¶
const resp = await fetch("https://textanalysis.toolkitapi.io/v1/text/embed", {
method: "POST",
headers: {
"X-API-Key": process.env.TOOLKIT_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify([
"How do I rotate an API key?",
"Where can I change my API credentials?",
"The cat sat on the mat.",
]),
});
const { embeddings, dimensions, model } = await resp.json();
Response¶
| Field | Type | Description |
|---|---|---|
status |
string | "ok" on success. |
embeddings |
number[][] |
One vector per input string, in the same order. |
dimensions |
integer | null | Vector length (384 for all-MiniLM-L6-v2). Use this as the source of truth — don't hardcode 384. |
model |
string | Model identifier, defaults to all-MiniLM-L6-v2. |
count |
integer | Number of vectors returned (equals the number of inputs). |
task_id |
string | Internal GPU task id — useful when filing a support ticket. |
{
"status": "ok",
"embeddings": [[0.021, -0.134, ...], [0.019, -0.129, ...], [-0.311, 0.502, ...]],
"dimensions": 384,
"model": "all-MiniLM-L6-v2",
"count": 3,
"task_id": "gpu-7f3c1a9e"
}
Recipes¶
Cosine similarity matrix (Python, no NumPy)¶
import math, requests
def cosine(a, b):
dot = sum(x * y for x, y in zip(a, b))
na = math.sqrt(sum(x * x for x in a))
nb = math.sqrt(sum(y * y for y in b))
return dot / (na * nb) if na and nb else 0.0
texts = ["reset my password", "change my password", "pizza recipes"]
vecs = requests.post(
"https://textanalysis.toolkitapi.io/v1/text/embed",
headers={"X-API-Key": API_KEY},
json=texts,
timeout=120,
).json()["embeddings"]
print(round(cosine(vecs[0], vecs[1]), 3)) # ~0.8, strongly related
print(round(cosine(vecs[0], vecs[2]), 3)) # low, unrelated
Semantic search over a knowledge base¶
import math, requests
def embed(batch):
r = requests.post(
"https://textanalysis.toolkitapi.io/v1/text/embed",
headers={"X-API-Key": API_KEY}, json=batch, timeout=120,
)
r.raise_for_status()
return r.json()["embeddings"]
def cosine(a, b):
return sum(x * y for x, y in zip(a, b)) / (
math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b)) or 1
)
docs = load_docs() # ["doc one", "doc two", ...]
doc_vecs = []
for i in range(0, len(docs), 100): # respect the 100-item cap
doc_vecs += embed(docs[i:i + 100])
query_vec = embed(["how do I authenticate requests?"])[0]
ranked = sorted(zip(docs, doc_vecs), key=lambda d: cosine(query_vec, d[1]), reverse=True)
top = [doc for doc, _ in ranked[:5]]
Near-duplicate detection¶
Embed each item once, bucket pairs whose cosine ≥ 0.95, and keep one representative per bucket. Cheaper and far more accurate on paraphrases than the lexical methods.
Storing vectors¶
Embeddings are plain JSON floats. To store them in Postgres, cast on write: INSERT INTO docs(embedding) VALUES (%s::vector) with pgvector, or keep them in a float[] column. Because the model is fixed per call, always store model next to the vector and re-embed if it changes.
Errors¶
| Status | Condition |
|---|---|
401 |
Missing / invalid API key. |
422 |
Empty array, more than 100 texts, or a non-string element. |
503 |
GPU task API is currently unavailable — retry with backoff. |
504 |
Embedding generation timed out — retry, or split a very large batch. |
500 |
GPU worker returned an error. |
Notes & gotchas¶
- Order is preserved.
embeddings[i]corresponds to inputtexts[i]; there is no id echo, so keep your own index. - Batch up. One call with 100 texts is dramatically cheaper and faster than 100 calls. The cap is hard: 100 per request.
- Cold starts. A GPU worker that has been idle may take several seconds on the first request. Use a generous client timeout (
60–120 s) and don't interpret one slow call as an outage. - Truncation. Sentence-transformer models have a fixed context (typically 256–512 tokens for MiniLM). Very long documents get truncated — chunk to a few paragraphs before embedding rather than sending whole pages.
- Normalise only if you want to. Cosine ignores magnitude; if you plan to use dot products instead, L2-normalise the vectors yourself once at write time.
- Dimensions are model-dependent. Read
dimensionsfrom the response instead of assuming 384, and always pair an index with the model that produced it.
See also¶
- Similarity and Diff — lexical comparison and unified diffs
- Readability and Summarization — extractive summaries to shrink text before embedding
- Filtering and Frequency — stop-word and keyword statistics