Embeddings

OpenAI-compatible embeddings. Calls to this endpoint go through the same API keys, budgets, usage limits and usage reporting as chat requests, so agents and apps that embed text show up in your usage data instead of bypassing it.

The request body is forwarded to the provider as raw JSON and the provider's response comes back unchanged. That keeps encoding_format: "base64" (each data[].embedding is then a base64 string, not an array) and token-array input working as the OpenAI API defines them.

Choosing a model

Use a model from GET /v1/models whose output is embedding, in author/model format, for example openai/text-embedding-3-large. Embedding models appear in the console with an Embedding badge.

The two kinds of model are not interchangeable: an embedding model sent to a chat endpoint, or a chat model sent to /v1/embeddings, is rejected with a 400 and the code model_not_supported.

Vector size

Pass dimensions to choose the vector size on models that support it, such as the OpenAI text-embedding-3 models. There is no fixed-size model id: text-embedding-3-large with dimensions: 1536 is the way to get 1536-dimension vectors.

Gemini embedding models do not accept dimensions through the gateway. A request that includes it returns a 400 rather than a vector of a different size than the one you asked for.

Fallback

If a provider fails, the gateway retries and then falls back to another provider of the same model. It never falls back to a different model, and routing strategies do not reroute this endpoint, because vectors from different models are not comparable. The X-Edgee-Provider response header names the provider that served the request, and X-Edgee-Fallback-Used is present when a fallback served it.

Usage and cost

Usage is recorded from the provider's usage.prompt_tokens. Gemini's embeddings endpoint reports no usage, so for Gemini the gateway counts the input tokens with Gemini's countTokens and returns that count in usage. Embeddings are billed on input tokens only, so output, cached and reasoning cost are always zero. Requests count against the same organization budgets and usage limits as chat requests.

Debug logs

When debug logging is enabled for a request, the vectors in the response are replaced by a size marker such as [redacted: 1536 floats] before the log is stored. The request input is kept.

curl --include --no-buffer --globoff --request POST 'https://edgee.io/v1/embeddings' \
  --header "Authorization: Bearer $EDGEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "model": "openai/text-embedding-3-large",
  "input": "The quick brown fox",
  "dimensions": 1536
}'

{
  "model": "openai/text-embedding-3-large",
  "input": "The quick brown fox",
  "dimensions": 1536
}

{
  "object": "list",
  "model": "text-embedding-3-large",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0023064255,
        -0.009327292
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 4,
    "total_tokens": 4
  }
}