Create vector embeddings

embed turns one text, or one search question, into a meaning vector: 1,024 numbers made by the same model that makes the vectors of your Opensolr Index, so the two can be compared. Nothing is stored. For many texts in one call, use batch_embed.

01 · The request

https://api.opensolr.com/solr_manager/api/embed

GET or POST, as form fields or as a JSON body.

Parameter	Required	What it is
`email`	yes	The email of your Opensolr account.
`api_key`	yes	Your API key, or a scoped key that allows `embed`: Authentication and keys.
`index_name`	yes	One of your indexes. It decides whose AI allowance is used; nothing is written to it.
`payload`	yes	The text, at least 2 characters.
`is_query`	no	`1` when the text is a search question. Leave it out for a document.

02 · A question or a document

The model, multilingual-e5-large-instruct, makes a slightly different vector for a search question than for a document. With is_query=1 the text is embedded as a question, the way Opensolr embeds what visitors type. Without it, the text is embedded as a document, the way Opensolr embeds your pages.

Use is_query=1 for the vector you search with, and leave it out for the vectors you store.

Only the start of a long text goes into the vector: the model reads a limited window of tokens and the rest is left out, at the end of a sentence when it can be. batch_embed tells you, per text, how many tokens were used and whether the text was cut.

The same text, with the same is_query, always gets the same vector, and a repeat comes from cache.

03 · The answer

The answer is the vector itself, a JSON array of 1,024 numbers, with no wrapper around it:

[0.0123, -0.0456, 0.0789, -0.0012, 0.0345]

(shortened: the real array has 1,024 numbers). When the vector could not be made, the answer is null: send it again later. Refusals come as JSON objects:

HTTP	Answer	Why
404	`{"ERROR":"Invalid payload"}`	`payload` is missing or shorter than 2 characters.
404	`ERROR_NOT_CORE_OWNER`	The index is not one your account can use.
403	`VECTOR_NOT_ALLOWED`	AI is switched off on the plan of the account that owns the index.
429	`ERROR_AI_MONTHLY_QUOTA_EXCEEDED`	This month's AI allowance is used up.

Authentication, rate limits and a wrong host answer as described in API errors.

04 · What it uses from your plan

Each new vector counts as one AI request of the account that owns the index. A text embedded before is answered from cache and costs nothing, and a call that fails costs nothing.

Every plan includes a monthly AI allowance of 500 AI requests; see pricing and API Quota.

05 · Examples

curl -s https://api.opensolr.com/solr_manager/api/embed \
  -d "email=YOUR_EMAIL" \
  -d "api_key=YOUR_API_KEY" \
  -d "index_name=YOUR_INDEX" \
  -d "is_query=1" \
  --data-urlencode "payload=cheap flights to Lisbon"

<?php
$ch = curl_init('https://api.opensolr.com/solr_manager/api/embed');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'email'      => 'YOUR_EMAIL',
        'api_key'    => 'YOUR_API_KEY',
        'index_name' => 'YOUR_INDEX',
        'payload'    => 'cheap flights to Lisbon',
        'is_query'   => '1',
    ]),
]);
$vector = json_decode(curl_exec($ch), true);
curl_close($ch);

if (is_array($vector) && isset($vector[0]) && is_numeric($vector[0])) {
    echo count($vector), ' numbers', PHP_EOL;
} else {
    echo 'No vector: ', json_encode($vector), PHP_EOL;
}

import requests

resp = requests.post("https://api.opensolr.com/solr_manager/api/embed", data={
    "email": "YOUR_EMAIL",
    "api_key": "YOUR_API_KEY",
    "index_name": "YOUR_INDEX",
    "payload": "cheap flights to Lisbon",
    "is_query": "1",
}, timeout=60)
vector = resp.json()

if isinstance(vector, list) and vector:
    print(len(vector), "numbers")
else:
    print("No vector:", vector)

06 · Store it, or search with it

To store vectors in an index of your own, it needs a vector field of 1,024 dimensions with cosine similarity. Indexes with the Opensolr schema already have it, named embeddings (core fields):

<field name="embeddings" type="knn_vector" indexed="true" stored="false"/>
<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="1024" similarityFunction="cosine"/>

Pages Opensolr crawls and documents you push get their vectors on their own: Meaning vectors, done for you.

To search with the words and the meaning of a question in one call, use embed_and_search.

To add vectors to the documents already in an index, use embed_opensolr_index.

All the vector calls in one place: Meaning vectors by API.