Embeddings API — OneRouter Docs

Endpoint

http
POST https://api.onerouter.app/v1/embeddings

Request Parameters

Parameter	Type	Required	Description
model	string	Yes	Embedding model ID (e.g., `text-embedding-3-large`, `text-embedding-3-small`, `voyage-3`)
input	string / array	Yes	Text to embed. Pass a string for one embedding or an array of strings for batch (up to 2048 items per request).
dimensions	integer	No	Reduce output dimensions to save storage and improve search speed. Supported by text-embedding-3 models. Must be ≤ model's max dimension.
encoding_format	string	No	`"float"` (default) or `"base64"` for compact transfer.
user	string	No	End-user identifier for abuse monitoring.

Single Embedding

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.onerouter.app/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-large",
    input="Your text string for embedding",
    dimensions=1024,  # Optional: reduce dimensions
)

embedding = response.data[0].embedding
print(f"Vector dimension: {len(embedding)}")

Batch Embedding

Send up to 2048 inputs in a single request for maximum throughput. The response preserves input order — response.data[0] corresponds to input[0].

python
# Batch embedding — process up to 2048 inputs per request
texts = ["First document", "Second document", "Third document"]

response = client.embeddings.create(
    model="text-embedding-3-large",
    input=texts,
    dimensions=1024,
)

for i, data in enumerate(response.data):
    print(f"Text {i}: vector[:5] = {data.embedding[:5]}...")

Dimension Reduction

Models like text-embedding-3-large (max 3072 dimensions) and text-embedding-3-small (max 1536) support reducing output dimensions via the dimensions parameter.

Why reduce dimensions?

Smaller storage: A vector with 256 dimensions uses 12× less space than 3072 dims
Faster search: Fewer dimensions = faster cosine similarity computation
Good enough quality: For most use cases, 256–512 dimensions retain ~95%+ of the semantic quality

Dimensions	Storage (per 1M vectors)	Quality	Best For
256	~1 GB	Good	Large-scale search, cost-sensitive apps
512	~2 GB	Great	General-purpose RAG and semantic search
1024	~4 GB	Excellent	High-accuracy search, clustering
3072	~12 GB	Maximum	Maximum accuracy, small corpora

Semantic Search Recipe

python
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# Embed your document corpus (do this once, store results)
doc_embeddings = client.embeddings.create(model="text-embedding-3-large", input=documents)

# Embed a search query
query_embedding = client.embeddings.create(model="text-embedding-3-large", input="How do I reset my password?")

# Find most similar documents
scores = [cosine_similarity(query_embedding.data[0].embedding, d.embedding) for d in doc_embeddings.data]
top_idx = np.argmax(scores)
print(f"Best match: {documents[top_idx]} (score: {scores[top_idx]:.3f})")

Pro tip: For production RAG, pair embeddings with Rerank for a two-stage pipeline: coarse retrieval with embeddings (fast + cheap), then precision reranking on the top 20–50 results.

Available Models

Model	Provider	Max Dims	Best For
text-embedding-3-large	OpenAI	3072	Maximum accuracy, flexible dimension reduction
text-embedding-3-small	OpenAI	1536	Cost-efficient, good quality
Cohere Embed v3	Cohere	1024	Multilingual, strong search performance
Voyage AI	Voyage	1024 / 2048	Code and legal document embeddings
BGE-M3	BAAI	1024	Open-source, multilingual, self-host friendly

See the Models page for the complete catalog with current per-token pricing.