Skip to main content

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?​

optional abortSignal: 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?​

optional apiKey: string

Defined in: packages/agentos/src/api/embedText.ts:123

Override the API key instead of reading from environment variables.


baseUrl?​

optional baseUrl: 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?​

optional budget: 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?​

optional dimensions: 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?​

optional maxAttempts: 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?​

optional maxInputsPerRequest: 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?​

optional model: 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()?​

optional onAttempt: (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​

AttemptOutcome

Returns​

void


provider?​

optional provider: 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?​

optional usageLedger: AgentOSUsageLedgerOptions

Defined in: packages/agentos/src/api/embedText.ts:140

Optional durable usage ledger configuration for helper-level accounting.