Embeddings API

Embeddings are numerical representations of text that capture semantic meaning. They are essential for tasks like document search, recommendation systems, and clustering. SIRAYA Model Router provides a unified API to access state-of-the-art embedding models.

Base URL

https://llm.siraya.ai/v1/embeddings

How to Generate Embeddings

Basic Request (Python)

PythoncURL

import requests

url = "https://llm.siraya.ai/v1/embeddings"
headers = {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
}
data = {
    "model": "gemini-embedding-2-preview",
    "input": "Hello world"
}

response = requests.post(url, headers=headers, json=data)
embeddings = response.json()["data"][0]["embedding"]

curl https://llm.siraya.ai/v1/embeddings \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-embedding-2-preview",
    "input": "Hello world"
  }'

Request Parameters

Parameter	Type	Description
model	string	Required. Embedding model identifier (e.g., gemini-embedding-2-preview).
input	string / array	Text(s) to embed. Either input or messages is required. See Accepted input Shapes.
messages	array	vLLM "chat-embeddings" dialect (used by Dify's OpenAI-Compatible plugin with vision enabled). An alternative to input.
encoding_format	string	float (default) or base64.
dimensions	integer	Output vector dimensions (model-dependent).
user	string	End-user identifier.
input_type	string	text / image / video / audio. Modality hint; required by some multimodal embedding models.
output_s3_uri	string	Output location for async multimodal embedding paths (video/audio). Model-dependent.
task_type	string	Retrieval task type (model-dependent): RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, QUESTION_ANSWERING, FACT_VERIFICATION, CODE_RETRIEVAL_QUERY.
title	string	Document title, used with task_type=RETRIEVAL_DOCUMENT. Model-dependent.
extra_body	object	Model-specific parameters.

Note

The vLLM extension parameters continue_final_message and add_special_tokens are accepted (for client tolerance) but are never forwarded upstream.

Batch Processing

To generate multiple embeddings in a single request, pass an array of strings to the input parameter — each element produces its own embedding:

{
  "model": "gemini-embedding-2-preview",
  "input": ["First document text", "Second document text", "Third document text"]
}

Accepted input Shapes

The adapter normalizes all of the following into the model's native call format:

Shape	Meaning
"a string"	One text input.
["a", "b"]	Two text inputs → two embeddings.
[{"type":"text","text":"…"}, {"type":"image_url","image_url":{"url":"…"}}]	Multimodal content parts (one embedding per element).
('text', 'data:image/png;base64,…')	Nested array → one combined multimodal input (text + image as a single entity).
messages: [{"role":"user","content":[…]}]	vLLM chat-embeddings: all user-role parts merged into one embedding. system/assistant parts are dropped.

Resource strings are auto-detected by prefix: data: URIs, https://, s3://, gs://, and files/… Files API references.

Multimodal Embeddings

Models that support multiple modalities accept images, video, and audio alongside text. Set input_type to hint the modality when the model requires it, and use the content-part or nested-array shapes above to embed mixed content. Async paths (video/audio) may write results to output_s3_uri.

Response

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0021, -0.0135, ...] }
  ],
  "model": "gemini-embedding-2-preview",
  "usage": { "prompt_tokens": 8, "total_tokens": 8 }
}

embedding is an array of floats, or a base64-encoded string when encoding_format=base64.

Best Practices

• Normalization: Most models return normalized embeddings. Use cosine similarity for comparing vectors.
• Caching: Since embeddings are deterministic for a given model and input, caching results can save significant costs.