An embedding alias that won't swap under you

The call

curl https://freemodel.online/v1/embeddings \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto/embed","input":"the quick brown fox"}'

from openai import OpenAI

client = OpenAI(
    base_url="https://freemodel.online/v1",
    api_key="sk-your-key",
)

r = client.embeddings.create(
    model="auto/embed",
    input=["first document", "second document"],
)
print(len(r.data[0].embedding))   # 1024

input takes a single string or an array. The response is the OpenAI shape ({data, model, usage}), so any client that already speaks embeddings reads it without a shim.

Why there is no fallback chain

Most routing layers treat a dead model as a dead request and retry on the next candidate. For chat that is harmless: a different model still answers your question, and you can see the answer changed.

For embeddings it destroys your data.

Embedding models do not share a coordinate system. We measured three candidates that all return 1024-dimensional vectors: same length, same type, same JSON. Ask all three for the embedding of the same sentence and compare them:

A vs B   0.003
A vs C   0.010
B vs C   0.006

Effectively zero. They are three orthogonal vector spaces that happen to have the same number of dimensions, which is exactly why the failure is so easy to miss. Nothing about the response looks wrong.

Embed your documents with model A. Query with model B. The result is not worse retrieval. It is random retrieval, with no error and no warning, and you find out weeks later when search results stop making sense.

So auto/embed has one candidate. If that model is unavailable the request fails and says so. Failing loudly is the only safe behaviour when the alternative is silently poisoning an index you spent months building.

The full write-up, including the code to reproduce those three numbers against your own endpoints, is in Three 1024-Dimension Embedding Models, Three Coordinate Systems.

When the model changes

Swapping the embedding model behind an alias is a breaking change, not an upgrade. So it ships as a new name, auto/embed-v2, and the old one keeps working.

That means your options are explicit:

• Pin auto/embed and nothing moves under you.
• Move to the new name on your own schedule, rebuild the index, keep both live during the cutover.

What will not happen is the alias being repointed while you sleep.

What you get

The other three entries in the list (qwen-embed/text-embedding-v3, text-embedding-v4 and qwen3.7-text-embedding) are callable by name if you want to experiment or you already standardised on one. The alias exists so that production code has something stable to pin.

Embeddings are free to call while the endpoint is in preview. If that changes it will be announced here before it takes effect, and existing keys keep working.

Related capabilities

The same naming scheme covers the other non-chat modalities — one alias per capability, listed in /v1/models:

Sources

Every third-party figure quoted on this site was read from the vendor documentation linked below, on the date stated. None of these links are affiliate links and none of these vendors paid to be listed. If a number here disagrees with the page it came from, the page is right — tell us and it gets corrected.

• OpenRouter — credit-purchase fees and free-model rate limits
• OpenRouter — rate-limit reference
• OpenRouter — public model list
• LiteLLM — licence, deployment options and supported models
• Cloudflare AI Gateway — features and pricing
• Vercel AI Gateway — features
• Portkey — plans
• Helicone — plans
• Model Context Protocol — specification
• OpenAI Python SDK — base_url and OPENAI_BASE_URL
• Anthropic Messages API — request format

Key numbers

• 4 条 embedding 条目
• 3 个可直接调用的模型名
• 1 个固定别名
• 4 embedding entries in /v1/models: 3 model names, 1 alias (auto/embed).
• 1024 dimensions from every candidate — same length, different coordinate systems.
• Cosine similarity between the 3 models on one sentence: 0.003, 0.010, 0.006.
• 1 model behind the alias, 0 fallbacks, by design.

How to use it, step by step

1. Step 1. Call POST /v1/embeddings with model: "auto/embed" and one string or an array of strings.
2. Step 2. Read data[0].embedding — 1024 floats, OpenAI response shape.
3. Step 3. Store the vectors with the model name the response reports, and re-embed if that name ever changes.

FAQ

Why not fail over to another embedding model?

Because the vectors would not be comparable. Cosine similarity between two of these models measured 0.003–0.010 on the same sentence, so a silent swap turns retrieval into noise without raising an error.

How do I know which model answered?

The response carries the model name. Store it alongside the vectors.

When does auto/embed change models?

Only when the current model is retired upstream. Not on a slow response, not on a rate limit.

When to use it — and when not to

Use embeddings for retrieval, not generation: semantic search over your own docs, clustering support tickets, near-duplicate detection, or building a RAG index. The output is a vector, so the consumer is always a distance function or a vector store.

Do not use it when you need an answer in natural language — that is a chat model's job — or when your corpus is small enough that keyword search already works. For a 200-page handbook, BM25 plus a good title is often enough; embeddings earn their keep when vocabulary mismatch is the bottleneck.

Limits worth designing around

• One model per alias: vectors from different embedding models are not comparable. The alias pins a model so your index does not silently break.
• Fixed dimensions: store the dimension with the vector and reject mismatches at write time.
• Input length: long documents must be chunked. Chunk on paragraph boundaries with a small overlap, and keep the chunk id next to the vector.
• No built-in index: the API returns vectors; storage, ANN index, and re-indexing are your responsibility.
• Data path: text leaves your infrastructure and reaches the upstream provider. Do not embed secrets.

Cost and latency

Embeddings are the cheapest part of a RAG pipeline per call, but the volume is large: one document can produce dozens of chunks. Estimate chunks first (average 300–500 tokens per chunk), then calls per document, then re-index frequency. A model change means re-embedding the entire corpus — budget for that before you pick an alias.

Latency is dominated by batch size and network. Batch 16–64 chunks per request where the API allows it; one request per chunk wastes round trips. Measure p95 on a 1,000-chunk sample before committing to a chunk size.

Two more questions

Can I mix vectors from two aliases? No. Different models place the same sentence in different coordinate systems; cosine similarity between them is noise. Re-embed instead.

How do I know retrieval got better? Build a 50-question evaluation set with known answers, measure recall@5 and MRR before and after changing chunking or model. Without a fixed eval set, every change looks like an improvement.