Batch vector embeddings

batch_embed turns many texts into meaning vectors in one call: up to 50 texts, encoded together, much faster than calling embed once per text. Each text is embedded as a document, the way Opensolr embeds your pages.

01 · The request

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

GET or POST. Send payloads as an array in a JSON body, or as a JSON array written into a form field.

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 `batch_embed`: Authentication and keys.
`index_name`	yes	One of your indexes. It decides whose AI allowance is used; nothing is written to it.
`payloads`	yes	A JSON array of 1 to 50 texts, each from 2 to 50,000 characters.

There is no is_query here: every text is embedded as a document. To embed a search question, use embed with is_query=1.

02 · The answer

{
  "embeddings": [[0.0123, -0.0456, 0.0789], [0.0345, -0.0678, 0.0012]],
  "dimension": 1024,
  "count": 2,
  "tokens_used": [9, 412],
  "truncated": [false, false],
  "embed_max_tokens": 512
}

(the vectors are shortened: each real one has 1,024 numbers)

Field	What it holds
`embeddings`	One vector per text, in the order you sent them.
`dimension`	The size of each vector: 1,024.
`count`	How many vectors came back.
`tokens_used`	Per text, how many tokens went into its vector. `null` for a text that came from cache.
`truncated`	Per text, `true` when the text was longer than the model's window and its end was left out. `null` for a text that came from cache.
`embed_max_tokens`	The model's window, in tokens. `null` when every text came from cache.

03 · Refusals

Answer	Why
`{"error":"payloads must be a non-empty JSON array of strings"}` (HTTP 400)	`payloads` is missing, empty or not an array.
`{"error":"Batch size exceeds maximum of 50 items", ...}`	More than 50 texts.
`{"error":"Invalid payload at index N: ..."}`	Text number N (counted from 0) is not a string or is shorter than 2 characters.
`{"error":"Payload at index N exceeds maximum of 50000 characters"}`	Text number N is too long.
`{"error":"Embedding service unavailable","embeddings":null}`	The vectors could not be made. Nothing was counted; send it again later.
`VECTOR_NOT_ALLOWED` (HTTP 403)	AI is switched off on the plan of the account that owns the index.
`ERROR_AI_MONTHLY_QUOTA_EXCEEDED` (HTTP 429)	This month's AI allowance would be exceeded. The check counts every text of the call, so a call of 50 texts needs 50 requests left.

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

04 · What it uses from your plan

Each text that needed a new vector counts as one AI request of the account that owns the index. A text embedded before comes from cache and costs nothing.

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

05 · Examples

curl -s -X POST https://api.opensolr.com/solr_manager/api/batch_embed \
  -H "Content-Type: application/json" \
  -d '{
    "email": "YOUR_EMAIL",
    "api_key": "YOUR_API_KEY",
    "index_name": "YOUR_INDEX",
    "payloads": ["Distributed search across shards", "Real-time indexing with soft commits"]
  }'

<?php
$texts = ['Distributed search across shards', 'Real-time indexing with soft commits'];

$ch = curl_init('https://api.opensolr.com/solr_manager/api/batch_embed');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 120,
    CURLOPT_POSTFIELDS     => http_build_query([
        'email'      => 'YOUR_EMAIL',
        'api_key'    => 'YOUR_API_KEY',
        'index_name' => 'YOUR_INDEX',
        'payloads'   => json_encode($texts),
    ]),
]);
$r = json_decode(curl_exec($ch), true);
curl_close($ch);

if (isset($r['embeddings'])) {
    foreach ($r['embeddings'] as $i => $vector) {
        echo $texts[$i], ': ', count($vector), ' numbers', PHP_EOL;
    }
} else {
    echo 'Error: ', json_encode($r), PHP_EOL;
}

import json
import requests

texts = ["Distributed search across shards", "Real-time indexing with soft commits"]

r = requests.post("https://api.opensolr.com/solr_manager/api/batch_embed", data={
    "email": "YOUR_EMAIL",
    "api_key": "YOUR_API_KEY",
    "index_name": "YOUR_INDEX",
    "payloads": json.dumps(texts),
}, timeout=120).json()

if "embeddings" in r:
    for text, vector in zip(texts, r["embeddings"]):
        print(text, len(vector))
else:
    print("Error:", r)

06 · Related

One text or one search question: embed.

Vectors for the documents already in an index: embed_opensolr_index.

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

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