Skip to main content
Use an embedding model deployed in your workspace to generate vectors for one or more inputs. The response uses OpenAI’s { data: [{embedding, index}] } shape. The public Model Library currently lists no hosted embedding model. Set MODEL_ID to your deployed embedding model’s id, then confirm that your key can reach it with GET /v1/models.

Request

Parameters

string
required
The id of an embedding model deployed in your workspace and reachable by your key.
string | string[]
required
Single string or array of strings to embed. An array is processed as one request, so batching inputs avoids a separate call per string and counts as a single request against your rate limits. Billing is per input token either way.
string
default:"float"
"float" (array of numbers) or "base64" (compact, use when wire size matters).

Response

The values below are illustrative. The vector is shortened for readability.

Billing

Hosted embedding requests can use a coding plan. Standby covers chat only. See Plan usage and funding for response headers and what happens at a plan limit. Embeddings are billed per input token only.

Batch size limits

The input array can carry up to 2048 strings per request, with a combined token budget that depends on the model: Each input string is also subject to the model’s per-input context limit (typically 512 or 8192 tokens). Inputs longer than the limit are truncated to the model’s context limit; the returned usage.prompt_tokens reflects the tokens actually embedded.

Pooling and normalization

The vector returned is the model’s canonical pooled output:
  • BGE family: CLS-token pooling, L2-normalized
  • E5 family: mean pooling over the final hidden state, L2-normalized
  • Nomic / GTE: mean pooling, L2-normalized
Because vectors arrive L2-normalized, cosine similarity reduces to a dot product in downstream code. Most vector databases (pgvector with vector_cosine_ops, Pinecone, Weaviate) handle this transparently.

Idempotency and retries

The endpoint is deterministic for the same deployed model and input. Send an Idempotency-Key and a retried call replays the stored result instead of running again. See Idempotent retries. Use X-Client-Request-Id when you need to correlate a batch with logs or support tickets:

Errors

Failures use the OpenAI-style error envelope. A 404 model_not_found means the id in model is not a model this key can reach. Deploy the model in your workspace, then call GET /v1/models to confirm the id before retrying.

Rerank

Relevance scoring that reorders candidate documents against a query.

Rate limits

Per-key budgets and burst behavior.

Errors

Full error code reference.