Optional providerProvider name. When supplied without model, the default embedding model
for the provider is resolved automatically from the built-in defaults.
Embeds on openai, openrouter, mistral and requesty (each at its own
OpenAI-compatible embeddings endpoint), gemini and ollama. Another
provider agentos knows has no embeddings it can send to (Anthropic, Groq,
Together AI, xAI, MiniMax, the image providers and the CLIs), and a call
to one is refused before its key is read.
`"openai"`, `"mistral"`, `"ollama"`, `"gemini"`
Optional modelModel identifier. Prefer the plain model name with provider set;
the combined "provider:model" string is also accepted.
`"text-embedding-3-small"` (with `provider: 'openai'`), `"nomic-embed-text"`
Text(s) to embed. Pass a single string for one embedding or an array for batch processing.
// Single input
input: 'Hello world'
// Batch input
input: ['Hello world', 'Goodbye world']
Optional dimensionsDesired output dimensionality. Only honoured by models that support
dimension reduction (e.g. OpenAI text-embedding-3-* with dimensions).
Ignored when the model has a fixed output size. Sent as dimensions to an
OpenAI-compatible endpoint, as output_dimension to Mistral, and as
outputDimensionality to Gemini's own API; Ollama does not receive it.
Optional maxMaximum inputs per OpenAI-compatible request, an integer from 1 to 2048. Defaults to 2048. Native Gemini and Ollama ignore this option. OpenAI allows 2048 inputs and 300,000 total input tokens per request: https://developers.openai.com/api/reference/resources/embeddings/methods/create (read 2026-10-12). Requests also stay within 300,000 UTF-8 bytes as a conservative token bound. A single input above that byte bound is rejected; callers must still respect the model's per-input token limit.
Optional apiOverride the API key instead of reading from environment variables.
Optional baseOverride the provider base URL (useful for local proxies or Ollama). An
OpenAI-compatible request goes to <baseUrl>/embeddings with the call's
key. An empty or whitespace-only value is unset: the global default's URL,
then the provider's base-URL variable, apply as with no baseUrl, and
with none the request goes to the provider's own endpoint; no request is
built on a relative /embeddings. A provider agentos does not know (a
gateway or proxy of your own) needs it, or a global default's baseUrl:
without one the call is refused, since agentos knows no endpoint for its
key. A provider with no embeddings (Anthropic, Groq, Together AI, xAI,
MiniMax) is refused whatever the base URL.
Optional usageOptional durable usage ledger configuration for helper-level accounting.
Optional budgetA spend budget for this call and, when the same SpendBudget instance is passed to several calls, for all of them: the request is checked against what is left before it is sent, its input priced at the model's row, and its cost recorded after it.
Optional abortEnds the call when it aborts: the embedding request in flight is cancelled, no further request starts, and the call rejects with the signal's reason.
Optional maxThe most requests a batch sends; a batch is sent once and never retried here, so any count from 1 allows it
and the option stands for parity with the completion calls. Below 1 is refused with a RangeError.
Optional onCalled after each request this call sent to an OpenAI-compatible endpoint, one a batch: its number (1), its HTTP status or null when none came, and whether it succeeded. Gemini's and Ollama's requests are not reported.
Options for an embedText call.
At minimum,
inputmust be provided. Provider/model resolution follows the same rules as generateText: supplyprovider,model(the combinedprovider:modelstring is also accepted), or rely on env-var auto-detection.Example