Interface: EmbedTextOptions
Defined in: packages/agentos/src/api/embedText.ts:65
Options for an embedText call.
At minimum, input must be provided. Provider/model resolution follows
the same rules as generateText: supply provider, model
(the combined provider:model string is also accepted), or rely on
env-var auto-detection.
Example
const opts: EmbedTextOptions = {
provider: 'openai',
model: 'text-embedding-3-small',
input: ['Hello world', 'Goodbye world'],
dimensions: 256,
};
Properties
abortSignal?
optionalabortSignal:AbortSignal
Defined in: packages/agentos/src/api/embedText.ts:154
Ends 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.
apiKey?
optionalapiKey:string
Defined in: packages/agentos/src/api/embedText.ts:123
Override the API key instead of reading from environment variables.
baseUrl?
optionalbaseUrl:string
Defined in: packages/agentos/src/api/embedText.ts:137
Override 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.
budget?
optionalbudget:SpendBudget|SpendBudgetOptions
Defined in: packages/agentos/src/api/embedText.ts:148
A 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. On a budget with a spend meter, every request the call sends (each batch, and each
retry Gemini makes) carries the id its reservation is under in the header AGENTOS_OPERATION_ID_HEADER names.
dimensions?
optionaldimensions:number
Defined in: packages/agentos/src/api/embedText.ts:109
Desired 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.
input
input:
string|string[]
Defined in: packages/agentos/src/api/embedText.ts:100
Text(s) to embed. Pass a single string for one embedding or an array for batch processing.
Example
// Single input
input: 'Hello world'
// Batch input
input: ['Hello world', 'Goodbye world']
maxAttempts?
optionalmaxAttempts:number
Defined in: packages/agentos/src/api/embedText.ts:160
The 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.
maxInputsPerRequest?
optionalmaxInputsPerRequest:number
Defined in: packages/agentos/src/api/embedText.ts:120
Maximum 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.
model?
optionalmodel:string
Defined in: packages/agentos/src/api/embedText.ts:86
Model identifier. Prefer the plain model name with provider set;
the combined "provider:model" string is also accepted.
Example
`"text-embedding-3-small"` (with `provider: 'openai'`), `"nomic-embed-text"`
onAttempt()?
optionalonAttempt: (outcome) =>void
Defined in: packages/agentos/src/api/embedText.ts:166
Called 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.
Parameters
outcome
Returns
void
provider?
optionalprovider:string
Defined in: packages/agentos/src/api/embedText.ts:78
Provider 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.
Example
`"openai"`, `"mistral"`, `"ollama"`, `"gemini"`
usageLedger?
optionalusageLedger:AgentOSUsageLedgerOptions
Defined in: packages/agentos/src/api/embedText.ts:140
Optional durable usage ledger configuration for helper-level accounting.