Embeddings

Use embeddings to vectorize text for search, clustering, or retrieval workflows. An embedding is a list of numbers that represents the meaning of an input. Texts with similar meanings produce vectors that are close to each other, which lets your application compare text by meaning instead of exact words.

POST /v1/embeddings

Request

curl https://api.voxvey.com/v1/embeddings \
  -H "Authorization: Bearer $VOXVEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": [
      "Voxvey routes provider-prefixed model IDs.",
      "The gateway exposes OpenAI-compatible endpoints."
    ]
  }'

What to do with embeddings

1. Create embeddings for the documents, chunks, or records you want to search.
2. Store each vector with the source text and metadata in your database or vector index.
3. Create an embedding for the user's query.
4. Compare the query vector to stored vectors with cosine similarity or another vector distance metric.
5. Send the closest matching source text into a Chat Completions or Responses request when you need generated output.

Response shape

Embedding vectors can be long, so examples usually truncate the numbers.

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0182, -0.0041, 0.0327]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [0.0149, -0.0028, 0.0294]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 18,
    "total_tokens": 18
  }
}

Required fields

Field	Type	Notes
model	string	Provider-prefixed embedding model ID
input	string or array	Text to embed

Notes

• The full embedding array is the value to store and compare.
• Keep the same embedding model for stored documents and incoming queries.
• Use /v1/models to discover supported embedding models.