Embeddings
Use embedding responses with an OpenAI-compatible request.
Check request and response handling for search, retrieval, clustering, and recommendation workflows with returned vectors while keeping keys server-side and usage visible.
Last updated: July 6, 2026. Examples use safe placeholders and do not include real API keys, secrets, or customer data.
Recommended first use
Start with a small batch, store vectors with source metadata, then add queueing, retries, and rate-limit monitoring before indexing a large corpus.
Setup path
Four steps from text to a returned vector shape.
Step 1
Authenticate server-side
Use an API key with embeddings:write scope from trusted server-side code.
Open sectionStep 2
Send text input
Post one string or an array of strings to the OpenAI-compatible embeddings endpoint.
Open sectionStep 3
Read vectors with metadata
Validate the returned vector shape with your document ID, source, and any search filters your product needs.
Open sectionStep 4
Monitor usage
Track request count, prompt tokens, rate state, and 429 responses before large indexing jobs.
Open sectionEndpoint
Post text to the embeddings endpoint.
Use the OpenAI-compatible /v1 endpoint with a scoped server-side key. Keep raw content out of logs unless your data policy allows it.
| Item | Value | Notes |
|---|---|---|
| Method | POST | Send JSON to the embeddings endpoint. |
| Endpoint | https://unlimitedcodex.com/v1/embeddings | Use the same /v1 base URL as chat completions and image request validation. |
| Authorization | Bearer token | Use a scoped API key with embeddings:write access. |
| Content type | application/json | The request body must be valid JSON. |
Request shape
Send one input or a small batch.
The smallest useful request includes a model and input. Use array input when your client can map each returned index to a source record.
| Field | Status | Notes |
|---|---|---|
| model | Recommended | Pass an embedding model value explicitly. Use the model value from your delivered setup details. |
| input | Required | Send one non-empty string or an array of non-empty strings. |
| encoding_format | Optional | Use float for numeric vectors or base64 when your storage layer prefers an encoded payload. |
const response = await fetch("https://unlimitedcodex.com/v1/embeddings", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.UCX_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "ucx-embedding-3-small",
input: [
"Release checklist for a safe API launch.",
"Rate states and usage review before rollout."
],
encoding_format: "float"
})
});
const body = await response.json();
if (!response.ok) {
throw new Error(body.error?.code ?? "embedding_request_failed");
}
const vectors = body.data.map((item) => item.embedding);Response shape
Store the vector and the source context together.
The response includes one embedding object per input plus usage fields for reporting and cost review.
| Field | Meaning | Notes |
|---|---|---|
| object | list | Identifies the response as a list of embedding objects. |
| data[].embedding | number[] or base64 | Matches the requested encoding_format. |
| data[].index | input position | Use this to map array inputs back to source records. |
| usage.prompt_tokens | input token count | Counts the text volume used for usage reporting and rate-limit review. |
{
"object": "list",
"id": "embd_example",
"model": "ucx-embedding-3-small",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.1221, -0.7442, 0.0314]
}
],
"usage": {
"prompt_tokens": 18,
"total_tokens": 18
}
}{
"model": "ucx-embedding-3-small",
"input": "Short text to index.",
"encoding_format": "base64"
}Limits and errors
Treat indexing as a rate-aware job.
Embedding workloads can grow quickly when a corpus changes. Build progress tracking, retries, and rate checks into your indexing pipeline.
The endpoint returns OpenAI-compatible vectors so teams can confirm parsing, usage reporting, and storage behavior before larger embeddings workloads.
Embedding requests count as one request plus prompt tokens.
Array input is useful for small batches, but large indexing jobs should use your own queue and backoff.
The endpoint returns a complete list response; embeddings are not streamed.
Use 429 handling from the rate-limit guide before indexing a large corpus.
Do not send secrets, regulated data, or customer text unless your agreement permits that use.
FAQ
Embeddings questions.
Can I send multiple texts in one embeddings request?
Yes. The input field accepts one non-empty string or an array of non-empty strings. The response includes an index for each returned embedding.
Which scope does an embeddings key need?
Use an API key with embeddings:write scope. Keep the key server-side and send it as a Bearer token.
Do embeddings stream?
No. The embeddings endpoint returns a complete list response with data and usage fields.
How should I handle large indexing jobs?
Chunk work into small batches, store progress in your own system, retry transient failures with backoff, and pause on rate pressure until capacity changes.
Free tools
Validate and estimate embedding workloads
Validate payloads, estimate tokens, model quota pressure, and compare costs before indexing production data.
Request Validator
Validate chat, embeddings, and image JSON payloads against unlimitedcodex OpenAI-compatible rules.
Token Estimator
Estimate token volume from prompt or response text before quota planning and launch.
Quota Estimator
Convert MAU and prompt assumptions into monthly tokens, requests, and quota threshold warnings.
Cost Calculator
Estimate OpenAI monthly spend and compare it to flat unlimitedcodex weekly or monthly packages.
Next step
Pair embeddings with auth, rate limits, and error handling.
Before indexing customer-facing content, confirm key scope, data handling rules, rate-limit behavior, and retry policy.