Embedding Model Groups

Embedding model groups are the /v1/embeddings counterpart to model groups: a stable name your application calls, backed by one or more embedding backends behind a fallback or load-balance route. They are a separate resource from chat model groups — an embedding group's routing config, capability, and vector output are all specific to embeddings and can't be mixed into a chat model group.

Calling an Embedding Model Group

curl https://api.modelplane.dev/v1/embeddings \
  -H "Authorization: Bearer YOUR_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embed",
    "input": ["Summarize this incident report."]
  }'

model is the embedding group name, same convention as chat model groups. Routing, fallback, and backend selection all work the same way as chat model groups — the difference is entirely in what's behind the name.

Why Dimensions Matter

Vectors of different sizes aren't just incompatible — most vector stores will accept both without complaint and let you compare them anyway. Say you embed a document corpus with a 3072-dimension model and store the vectors in your index. Your embedding provider has an outage, so a query falls back to a 1536-dimension model. The vector store doesn't reject the mismatched query vector; it just returns nonsense — subtly wrong rankings, missing documents that should have matched — with no error to tell you why. That's a production incident that looks like a relevance bug, not an outage, and it can take hours to trace back to a silent fallback.

Every embedding model group declares a fixed output vector size (capability.dimensions) specifically to make this impossible. Every backend behind it must return vectors of that size. The gateway enforces it two ways:

• At configuration time, a backend explicitly declaring a different dimension is rejected — you can't create a fallback pair with incompatible outputs in the first place.
• At request time, the actual response vector length is checked against the group's declared dimensions — a mismatch (a provider silently changing a model's output size, for example) fails the request loudly with a 502 rather than writing a corrupted vector into your index.

What This Makes Safe to Build

• Real fallback for embeddings, not just for chat — pair two same-dimension models from different providers, and an outage on one no longer risks corrupting your index the way an unchecked fallback would.
• Load-balanced ingestion, spreading a high-volume embedding pipeline across multiple backends without any of them being able to slip an incompatible vector into your store.
• Provider migration at your own pace — run old and new providers in a load-balanced group while both produce the same dimension, shift traffic gradually, and re-embed your existing corpus on your own timeline instead of doing it as a single risky cutover.

Discovering Embedding Model Groups

List the embedding model groups your API key can call, including each one's dimensions, with GET /v1/models?output_modalities=embeddings:

curl "https://api.modelplane.dev/v1/models?output_modalities=embeddings" \
  -H "Authorization: Bearer YOUR_GATEWAY_API_KEY"

What Developers Do Not Need to Handle

• Which provider or backend actually served a given request.
• Fallback ordering when a backend errors or times out.
• Verifying the returned vector size matches your index — the gateway already rejects a mismatch before it reaches you.

Those are managed in the ModelPlane console, the same as chat model groups.