POST /v1/embeddings

Create numeric vectors with an explicitly configured embedding model.

No current prepared translation is available. The English source is shown without machine translation.

Embeddings turn text into numeric vectors for semantic search, retrieval-augmented generation (RAG), clustering and similarity comparisons. Your application stores the vectors, searches for relevant material and may then pass that material to a separate text-generation model. This endpoint returns vectors, not a conversational answer.

Choose a model

Use an enabled model listed under Embeddings / vectors in the model catalog and available to your API key. The model must explicitly support the embeddings endpoint and have a working upstream route and applicable input-token tariff. A chat model or a familiar model name does not automatically support embeddings. An alias is resolved before endpoint validation, forwarding and billing.

embedding-model below is a placeholder. Replace it with the exact model ID or enabled alias from your own catalog; the release does not add or activate provider models automatically.

Request

curl https://api.model-gate.com/v1/embeddings \
  -H "Authorization: Bearer $MODEL_GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "embedding-model",
    "input": ["First text", "Second text"],
    "encoding_format": "float"
  }'

Field	Meaning
`model`	Required model ID or enabled alias with explicit embeddings support.
`input`	A nonempty string, a nonempty list of nonempty strings, a list of nonnegative integer token IDs, or a nonempty list of nonempty token-ID lists. Do not mix these forms. Token IDs must match the selected provider's tokenizer.
`encoding_format`	Optional `float` or `base64`, if supported by the selected provider. The example explicitly requests numeric arrays.
`dimensions`	Optional positive integer, only when the selected model supports changing its vector size.

The selected provider determines token limits, batch size and supported dimensions. Model Gate validates the request shape; it does not silently truncate text, guess token counts or substitute another model. stream: true and native async: true are not supported for this endpoint. A normal request returns one JSON response. The Files/Batch interface can execute supported embedding items separately.

Response

This is a synthetic, shortened example. The numbers and token count are illustrative.

{
  "object": "list",
  "model": "embedding-model",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.012, -0.044]},
    {"object": "embedding", "index": 1, "embedding": [0.031, 0.009]}
  ],
  "usage": {"prompt_tokens": 6, "total_tokens": 6}
}

Use index to associate each vector with its input and store the full returned vector. Keep the embedding model and dimensions consistent for indexed material and search queries. Rebuild the index when changing to an incompatible model or dimension.

Errors

A model endpoint-capability rejection returns HTTP 400 before a provider request. The gateway uses this OpenAI-compatible envelope:

{
  "error": {
    "code": "model_endpoint_not_supported",
    "message": "The selected model is not enabled for this endpoint.",
    "type": "invalid_request_error"
  }
}

Gateway code	What to correct
`model_endpoint_not_supported`	Select a model explicitly configured to support this endpoint. A chat endpoint flag does not grant embeddings support.
`invalid_embeddings_input`	Supply one supported, nonempty input form; do not mix text and token-ID forms.
`invalid_dimensions`	Use a positive integer. Whether a valid dimension is available remains the selected provider's constraint.
`invalid_encoding_format`	Use `float` or `base64`.
`embeddings_stream_not_supported`	Remove `stream: true` and use the single JSON response.
`async_not_supported`	Remove `async: true`; use the separate supported batch interface when appropriate.
`invalid_async_stream_combination`	Do not request native async and streaming together.

These validation failures use HTTP 400 with type invalid_request_error. Correct the request instead of automatically repeating it. Keep X-Request-ID for diagnostics. Provider error bodies and codes are not promised to match this example; authentication, account limits and sanitized upstream failures follow the general errors reference.

Usage and verification

Embeddings are billed from the provider's actual input-token usage. Vector coordinates are not output/completion tokens. A reported total_tokens must agree with input usage; its absence does not replace an explicit input count. Missing or contradictory usage is never inferred from text length or vector dimensions and is not treated as free successful usage. Your account tariff and existing API-key, group and access rules still apply.

For administrators: save the model with Embeddings / vectors selected under configured endpoints, add the intended route and input-token price, and then explicitly run OpenAI Embeddings → Embeddings / vectors in capability verification. For a dedicated embedding model, leave the text endpoints unchecked. Saving does not run a probe. The manual probe makes one billable request with two short inputs, checks finite vectors and complete indices, and separately checks provider-reported input usage. A verified probe establishes that response contract, not semantic quality or provider identity; it does not enable a disabled model.

The manual verification probe accepts JSON responses up to 256 KiB and rejects duplicate JSON keys. A larger response is inconclusive for this bounded probe; this does not set the public API vector-size limit. No automatic repeat request is made.