Skip to main content

Embeddings

POST /v1/embeddings follows the OpenAI embeddings shape. Embedding models are a separate part of the catalog: they carry "embedding": true in GET /v1/models and can't chat, and chat models can't embed.

Endpoint​

POST https://api.mindshub.ai/v1/embeddings

Quick example​

import os
from openai import OpenAI

client = OpenAI(
base_url="https://api.mindshub.ai/v1",
api_key=os.environ["MINDSHUB_API_KEY"],
)

response = client.embeddings.create(model="embed-small", input=["first text", "second text"])
vectors = [item.embedding for item in response.data]

Models​

AliasModelDimensionsdimensions acceptedPrice per 1M input tokens
embed-smalltext-embedding-3-small1,536yes, 1 to 1,536$0.02

embed-3-small names the same model and never moves to another one; use it if your stored vectors must keep matching. Vectors from different models can't be compared, so changing models means re-embedding your corpus.

Request parameters​

ParameterHandlingNotes
modeladaptedAn embedding alias from GET /v1/models ("embedding": true) resolves to a concrete provider model. The response names the model that served, which can be sent back as-is. A chat alias is a 400: chat models cannot embed.
inputforwardedA string, an array of strings, an array of token ids, or an array of token-id arrays, relayed as sent. OpenAI's limits (2,048 inputs, 8,192 tokens per input, 300,000 tokens per request) are enforced by the provider, and its 400 is relayed with its original message.
encoding_formatforwardedfloat or base64; any other value is a 400. Omitted, the response carries floats. The OpenAI Python SDK asks for base64 when the caller sets nothing and decodes it itself, so both encodings are relayed unchanged.
dimensionsconditionalForwarded to models that can shorten their vectors (text-embedding-3-*). A model that returns one fixed size refuses it with a 400 naming dimensions rather than dropping it: a vector of a length the caller did not ask for fails later, in their vector store, and less legibly.
userforwardedRelayed to the provider. Requests are attributed by API key regardless.

This table is generated from PARAM_SUPPORT in minds/requests/embeddings_request.py, which a unit test holds to the OpenAI SDK's own parameter list.

Request body​

The full request and response schemas are on the generated reference page: POST /v1/embeddings.

Response​

{
"object": "list",
"data": [
{"object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789]}
],
"model": "text-embedding-3-small",
"usage": {"prompt_tokens": 4, "total_tokens": 4}
}

The real embedding array has 1,536 values; it's truncated here. model names the model that served, as on the chat endpoints. Embedding calls are input-only: usage has prompt_tokens and total_tokens, no completion tokens.

Lane-specific behaviour​

  • Embeddings always bill to the wallet and never draw the included allowance: an empty wallet refuses them like any other paid request. The rate is low ($0.02 per million tokens), but it isn't free.
  • A chat alias sent here is a 400 with param: "model", and an embedding alias sent to a chat endpoint is refused the same way: chat models can't embed, and embedding models can't chat.

Differences from OpenAI​

The request and response shapes are OpenAI's, and the official SDKs work unchanged. Where behaviour differs:

  • dimensions on a model that can't shorten its vectors is a 400 naming dimensions, as on OpenAI, even though other unsupported parameters are usually dropped here: a vector of a length you didn't ask for would fail later, in your vector store. Every current alias supports it.
  • model in the response names the model that served (for example text-embedding-3-small), not the alias you sent. Either can be sent back.
  • Input limits (2,048 inputs, 8,192 tokens per input, 300,000 tokens per request on OpenAI's models) are the provider's, and its 400 is relayed with its own message.
  • Unknown request fields are ignored rather than refused.
  • Served embedding calls aren't traced in Traces yet; refusals are.

Errors​

Errors use the OpenAI envelope and follow the standard taxonomy in Errors; upstream provider errors are relayed with their original status codes.