AI-API - Words and vector for pictures (image

Opensolr API Endpoint: `image_index`

Overview

The image_index endpoint reads up to 5 pictures in one call and answers, for each of them, two things at once: the words that describe what the picture shows, and the search vector of those words. It is what Opensolr Photos uses to put a photo into an index, and it is open to any account whose plan includes vector search.

Before it existed, indexing a picture took two calls and two AI requests: image_clip for the words, then batch_embed for the vector. image_index does both on the same box, through the same caches, and counts one AI request per picture. A picture never comes back half done: its slot holds words and vector together, or a reason why it was not read.

Endpoint URL

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

Supports only POST requests.

Authentication & Core Parameters

Parameter	Type	Required	Description
email	string	Yes	Your Opensolr registration email address.
api_key	string	Yes	Your API key from the Opensolr dashboard.
index_name	string	Yes	Name of your Opensolr index the pictures belong to.

Image Parameters

Parameter	Type	Required	Default	Description
images	array	Yes	–	1 to 5 pictures, each as base64. A `data:` URI prefix is accepted. As a JSON body, or as a JSON string in a form field.
top_k	integer	No	12	How many labels per picture. Values are clamped to a maximum of 50.

Example

curl -s -X POST "https://api.opensolr.com/solr_manager/api/image_index" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"you@example.com\",\"api_key\":\"YOUR_API_KEY\",\"index_name\":\"my_index\",\"images\":[\"$(base64 -w0 photo1.jpg)\",\"$(base64 -w0 photo2.jpg)\"]}"

Response

{
  "status": true,
  "charged": 2,
  "results": [
    {
      "status": true,
      "text": "Atlantic walrus, Walrus, Pacific walrus, Tusk, Bearded Seal",
      "labels": [{"label": "Atlantic walrus", "score": 0.31}, {"label": "Walrus", "score": 0.29}],
      "model": "openai/clip-vit-large-patch14",
      "embedding": [0.0123, -0.0456, "... 1024 numbers ..."],
      "embed_model": "opensolr-1024"
    },
    {
      "status": false,
      "msg": "UNSUPPORTED_IMAGE_TYPE_TEXT_PLAIN"
    }
  ]
}

Field	Description
results	One entry per picture, in the order you sent them.
status	Per picture: `true` with words and vector, `false` with a `msg` saying why.
text	The labels joined with ", ", the text the vector was made from.
labels	Each label with its cosine similarity, highest first.
model	The CLIP checkpoint that produced the labels.
embedding	The search vector of `text`, ready for a dense vector field in your index.
embed_model	The embedding model tag, with the vector's dimension.
charged	How many AI requests the call counted. Pictures served from cache count nothing.

What a picture costs

One AI request per picture that needed the GPU, for the words or for the vector. Never two.
A picture seen before, by this endpoint or by image_clip, is answered from cache and counts nothing. The same goes for words already embedded.
A picture that fails (unsupported format, too large, a service error) counts nothing.
If the vector cannot be made, the words are not handed out either: that picture is reported as EMBEDDING_FAILED and should be sent again later. This is what keeps an index free of pictures with words but no vector.

Accepted images

Limit	Value
Pictures per call	5
Maximum size	20 MB per picture
Formats	JPEG, PNG, WEBP, GIF, BMP, TIFF, JPEG 2000, HEIC/HEIF, AVIF
Maximum pixels	50 megapixels

A picture is judged by its bytes, never by its file name or declared type. A refused picture does not fail the call: its slot carries the reason, the others are answered.

Errors

HTTP	Meaning
400	`images` missing or empty, or more than 5 pictures in one call.
404	The index is not yours, or does not exist.
429	Rate limit, or the monthly AI request cap would be exceeded by this call.

A plan without vector search gets {"status": false, "msg": "VECTOR_NOT_ALLOWED"} and nothing is read or counted.

Special Notes

The monthly cap is checked for the whole call before anything runs: a call of 5 pictures needs 5 requests left. With fewer left, send fewer pictures.
The endpoint is rate limited per minute and per hour like every other Opensolr API endpoint.
If you use a scoped API key, tick image_index in the key's scopes.
Your pictures are not stored. They are processed in memory and discarded; only the words they produced are kept, keyed by a hash of the picture, so a repeat costs nothing.
Labels are English. Vector search crosses languages on its own.
This endpoint lives on api.opensolr.com, like every other AI endpoint. For words only, without a vector, use image_clip.

AI-API - Words and vector for pictures (image_index)

Opensolr API Endpoint: image_index