Text Embeddings API Reference

Overview

Text Embeddings runs all-MiniLM-L6-v2, a 6-layer sentence-transformer, on APIVerve's own servers through ONNX Runtime. Each text is tokenized, passed through the model, mean-pooled over its tokens and scaled to unit length, giving a 384-dimension vector. The model reads at most 256 word pieces, so a text longer than about 180 words is split into 180-word chunks; each chunk is embedded and the chunk vectors are averaged and normalized again, so every text yields exactly one vector.

Send `text` for a single string or `texts` for a JSON array, not both. Text is trimmed before embedding. A text over 10,000 characters, a request over 50,000, more than 32 texts, or an empty string returns 400; more than 4 texts on the Free plan returns 403. When `compare` is present it is embedded in the same model call and `similarity` is the cosine of the angle between each vector and the compare vector, rounded to 4 places. Paraphrases typically score 0.6 to 0.9 and unrelated sentences under 0.2.

Vector values are rounded to 6 decimal places. Because the vectors are normalized, a plain dot product in your own code or vector database gives the same cosine similarity. Vectors are only comparable with vectors from this same model, so re-embed your corpus if you switch models.

Live Test Text Embeddings API →

Endpoint

One host, one path per API. The block below shows this call in four languages; every one of them is the same HTTP request. Making requests covers the timeouts, retries and parameter rules that apply to all of them. The SDKs wrap the same call in a typed client.

POSThttps://api.apiverve.com/v1/textembeddings

curl -X POST https://api.apiverve.com/v1/textembeddings \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "How do I reset my password?",
  "compare": "I forgot my login credentials"
}'

const res = await fetch('https://api.apiverve.com/v1/textembeddings', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "text": "How do I reset my password?",
  "compare": "I forgot my login credentials"
}),
});

if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

const { data } = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.apiverve.com/v1/textembeddings",
    headers={"x-api-key": "your_api_key_here"},
    json={
    "text": "How do I reset my password?",
    "compare": "I forgot my login credentials"
},
    timeout=15,
)
res.raise_for_status()

print(res.json()["data"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "text": "How do I reset my password?",
  "compare": "I forgot my login credentials"
}`)
	req, _ := http.NewRequest("POST", "https://api.apiverve.com/v1/textembeddings", body)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "your_api_key_here")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

Replace your_api_key_here with the key from your dashboard. When the inputs arrive as a list rather than one at a time, batch requests run up to 200 of them through this same API in a single call.

Authentication

Send your key in the x-api-key header. That is the only auth step — there is no token exchange and no per-endpoint scope to configure. Authentication covers creating, rotating and revoking keys.

401 is the only auth verdict

A 401 means the key is missing, invalid or expired. A 403 means the key is valid but not permitted here — blocked by a key restriction or an IP allow-list. Running out of credits is a 429.

Parameters

Sent as JSON in the request body. Premium parameters are accepted on every plan but only take effect on plans that include them.

Parameter	Type	Description
`text`Optional	string	The text to embed, up to 10,000 characters. Send text or texts length 0–10000
`texts`Optional	array	A JSON array of texts to embed in one call: up to 32 on paid plans and 4 on the Free plan, 10,000 characters each and 50,000 in total. Send text or texts
`compare`OptionalPremium	string	Optional reference text; each embedding gets its cosine similarity to it length 0–10000

Response

Every API returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape. Response format covers the envelope, the other output formats and how premium fields are withheld.

Sample response

{
  "status": "ok",
  "error": null,
  "data": {
    "model": "all-MiniLM-L6-v2",
    "dimensions": 384,
    "normalized": true,
    "embedding": [
      0.015935,
      -0.051158,
      -0.08069,
      -0.037722,
      -0.041567,
      0.069786,
      0.012189,
      0.027276,
      0.069194,
      0.022245,
      -0.042573,
      0.037621,
      0.043625,
      -0.041836,
      -0.056157,
      0.00667,
      -0.068362,
      0.112544,
      -0.021071,
      -0.090057,
      0.004028,
      -0.031519,
      -0.041218,
      -0.011646,
      0.013743,
      -0.016609,
      -0.002956,
      0.030607,
      -0.106868,
      0.001514,
      0.001547,
      0.020945,
      0.028474,
      0.027638,
      -0.010214,
      0.04415,
      -0.042242,
      0.011779,
      0.043924,
      -0.008672,
      -0.089182,
      -0.020857,
      -0.087462,
      0.028674,
      0.08814,
      0.025155,
      -0.042181,
      0.054494,
      0.048532,
      0.009761,
      0.107937,
      0.000774,
      0.000686,
      -0.028623,
      -0.058207,
      0.059224,
      0.065291,
      0.063502,
      0.056031,
      0.041444,
      0.018389,
      0.006527,
      -0.025379,
      0.100695,
      -0.071208,
      -0.020917,
      -0.005925,
      0.004708,
      0.040568,
      -0.020998,
      -0.091728,
      -0.046622,
      -0.084695,
      -0.031808,
      0.01667,
      0.02989,
      0.005032,
      -0.055746,
      0.063165,
      0.116765,
      -0.071768,
      -0.022474,
      -0.009307,
      0.049127,
      0.118566,
      0.059996,
      0.023227,
      -0.007489,
      0.011,
      -0.040044,
      0.051527,
      -0.027689,
      -0.051349,
      -0.011261,
      -0.111196,
      -0.012924,
      0.044306,
      0.022978,
      -0.071736,
      0.056197,
      0.044321,
      -0.024127,
      0.003852,
      -0.074818,
      0.042519,
      -0.046473,
      0.117393,
      0.08601,
      -0.013658,
      0.028927,
      0.032663,
      -0.044648,
      0.012891,
      0.058705,
      0.011859,
      -0.008381,
      -0.026583,
      0.007164,
      0.017871,
      0.027932,
      -0.041322,
      0.008515,
      0.001873,
      -0.02367,
      -0.050241,
      -0.017463,
      -0.034542,
      0,
      -0.062251,
      0.004076,
      -0.036463,
      0.010555,
      -0.039321,
      -0.067142,
      0.013812,
      -0.071026,
      -0.051261,
      0.057907,
      0.023454,
      0.01625,
      -0.045207,
      -0.087902,
      -0.019768,
      0.007788,
      -0.019921,
      0.007324,
      -0.012854,
      -0.001863,
      -0.019662,
      0.017874,
      0.079734,
      -0.008303,
      0.015725,
      -0.036594,
      0.025994,
      -0.032027,
      -0.036135,
      0.019403,
      -0.017327,
      -0.000511,
      0.000872,
      0.019909,
      -0.057479,
      0.000474,
      0.075845,
      -0.030035,
      -0.042511,
      0.026453,
      -0.026771,
      -0.029517,
      0.051743,
      -0.069742,
      0.054797,
      0.000037,
      0.026588,
      0.054662,
      0.030867,
      0.008791,
      -0.051588,
      -0.002533,
      0.003057,
      0.002774,
      0.017355,
      0.007094,
      0.012687,
      -0.045407,
      -0.086406,
      -0.068595,
      0.086327,
      0.036987,
      -0.026459,
      0.001031,
      0.021954,
      -0.049635,
      0.074866,
      -0.04183,
      -0.000295,
      0.049797,
      -0.029262,
      0.013973,
      -0.023409,
      0.029798,
      -0.103474,
      0.039347,
      0.038171,
      0.05988,
      -0.052313,
      0.049653,
      -0.004409,
      0.017919,
      -0.077781,
      0.080555,
      -0.046249,
      0.016249,
      0.017335,
      0.084156,
      -0.00726,
      -0.032936,
      -0.054922,
      -0.012744,
      0.075304,
      -0.121707,
      -0.082506,
      0,
      -0.007864,
      -0.066508,
      0.030534,
      -0.022107,
      0.0539,
      -0.021819,
      -0.002716,
      0.043627,
      -0.021448,
      -0.015385,
      0.057646,
      0.122854,
      0.0182,
      -0.029586,
      0.134486,
      0.085412,
      -0.035002,
      0.090932,
      -0.125456,
      -0.00437,
      -0.102856,
      0.051666,
      -0.002521,
      -0.02113,
      0.043273,
      -0.002127,
      0.021891,
      0.082963,
      0.011011,
      0.001568,
      0.069904,
      -0.016033,
      -0.003045,
      0.153703,
      0.050273,
      -0.014532,
      0.085554,
      0.009679,
      -0.055562,
      -0.031634,
      0.005374,
      0.042663,
      -0.010425,
      -0.005738,
      -0.049902,
      -0.008218,
      0.037462,
      -0.052941,
      0.01358,
      0.037513,
      -0.028075,
      -0.065099,
      0.100573,
      -0.064201,
      -0.009629,
      0.021812,
      0.052269,
      -0.016687,
      0.005393,
      -0.102985,
      -0.025369,
      0.079842,
      -0.016843,
      0.038335,
      -0.01167,
      0.001197,
      -0.026137,
      -0.022323,
      -0.076328,
      0.062972,
      -0.044764,
      0.10601,
      0.076878,
      0.01546,
      0.106406,
      -0.109352,
      -0.071418,
      0.039775,
      -0.086625,
      -0.01426,
      0.097484,
      -0.014352,
      -0.068561,
      -0.052108,
      -0.070306,
      -0.094529,
      0.02975,
      0.049288,
      0.046155,
      -0.007938,
      -0.040781,
      -0.036678,
      0.006408,
      -0.000094,
      0.000799,
      0,
      -0.013822,
      -0.056042,
      0.082071,
      0.005924,
      0.087829,
      0.032089,
      -0.048997,
      0.01165,
      -0.088562,
      -0.088651,
      -0.038811,
      0.027432,
      0.026942,
      0.006228,
      -0.028242,
      -0.031951,
      -0.059847,
      -0.008865,
      0.022552,
      0.016139,
      -0.03609,
      -0.003508,
      -0.021258,
      -0.07641,
      0.07868,
      0.076684,
      -0.007732,
      0.084901,
      0.052902,
      -0.017653,
      -0.038105,
      0.021126,
      -0.002817,
      -0.066709,
      -0.164925,
      -0.023914,
      -0.029452,
      0.008349,
      -0.025644,
      -0.014505,
      0.010479,
      0.051549,
      0.051218,
      0.066133,
      -0.05291,
      0.003186,
      0.018309,
      0.018868,
      0.026376,
      0.008602,
      -0.110013,
      0.091777,
      0.025643,
      0.065606,
      -0.017918,
      0.005675,
      0.047761,
      -0.047534,
      -0.111482,
      -0.006169,
      0.020921,
      0.069579,
      0.001407,
      -0.082195
    ],
    "characters": 27,
    "similarity": 0.6762
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

Field	Type	Example	Description
`model`	string	`"all-MiniLM-L6-v2"`	Model that produced the vectors
`dimensions`	number	`384`	Length of each vector
`normalized`	boolean	`true`	Always true: every vector has length 1
`embedding`	array	`[0.015935, ...]`	The vector for text (single-text requests)
`characters`	number	`27`	Characters embedded from text (single-text requests)
`similarity`Premium	number	`0.6762`	Cosine similarity of text to compare, from -1 to 1 (when compare is sent)

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change. Error handling covers the full status list and which of them are worth retrying.

Status	Meaning	What to do
`400`	Input was rejected	Read `error`; it names the parameter.
`401`	Key missing or invalid	Check the header name and the key value.
`403`	Key valid, but not permitted	A key restriction or IP allow-list; see key scoping.
`429`	Rate limited, or out of credits	Read `error` to tell them apart; see rate limits.

Use cases

Semantic Search: Embed documents once, store the vectors in a vector database, and embed each search query to find passages by meaning rather than exact keywords.
Retrieval for Chatbots: Build the retrieval step of a RAG pipeline: embed knowledge-base chunks and fetch the closest ones to a user question before calling a language model.
Duplicate Detection: Flag support tickets, reviews or listings that say the same thing in different words by comparing their vectors.
Clustering and Tagging: Group feedback, articles or products by topic with k-means or any clustering library run on the vectors.

Other ways to use Text Embeddings

Set up Text Embeddings on APIVerve, or reach the same source a different way. Your APIVerve account and credits work on all of them — one key, one balance.

Give it to an AI agentConnect over MCP and your agent calls it as a native tool — Claude, Cursor, ChatGPT.VerveKit →Reference →

Ground an agent on itA cited, machine-checkable fact your model can't produce on its own.VerveContext →Reference →

Text Embeddings