Embeddings

Embeddings are numerical representations of text that capture semantic meaning — they convert text into vectors (arrays of numbers) usable for a range of machine learning tasks. BazaarLink provides a unified, OpenAI Embeddings API-compatible endpoint so you can call embedding models from multiple providers through one interface.

Embedding responses use an opaque BazaarLink request id that matches x-request-id; use it with GET /v1/generation. The non-streaming response also returns the same id in x-generation-id. usage.cost is the USD amount charged to the customer for this request. Stats may take a few seconds after completion; retry a 404 briefly.

What are Embeddings?

Embeddings transform text into high-dimensional vectors where semantically similar texts sit closer together in vector space — for example, "cat" and "kitten" would have similar embeddings, while "cat" and "airplane" would be far apart. These vector representations let machines understand relationships between pieces of text, making them foundational to many AI applications.

Common Use Cases

Use Case

Description

RAG (Retrieval-Augmented Generation)Build systems that retrieve relevant context from a knowledge base before generating an answer — embeddings find the most relevant documents to include in the LLM's context.

Semantic SearchConvert documents and queries into embeddings, then find the most relevant documents by vector similarity — this understands meaning rather than just matching keywords, giving better results than keyword search alone.

Recommendation SystemsGenerate embeddings for items (products, articles, videos) and user preferences to recommend similar items — vector comparison surfaces semantically related items even without shared keywords.

Clustering & ClassificationGroup similar documents or classify text by analyzing embedding patterns — documents with similar embeddings usually belong to the same topic or category.

Duplicate DetectionFind duplicate or near-duplicate content by comparing embedding similarity — this works even when the content has been paraphrased or reworded.

Anomaly DetectionSpot unusual or outlier content by identifying embeddings that deviate significantly from the dataset's typical pattern.

POST/v1/embeddings

Note

If an upstream source does not support the requested embeddings model, a request can try another available source for that model. If none is available, the request returns an error.

Parameters

modelrequired

string

The embedding model to use, e.g. "openai/text-embedding-3-small".

inputrequired

string | string[] | ContentItem[]

Text to embed — a single string, an array of strings for one batch call, or (for models that support it) an array of {content:[...]} items mixing text and image_url parts.

dimensions

integer

Requested output vector size. Only honored by models that support variable dimensions (e.g. the OpenAI text-embedding-3 family); forwarded to the upstream provider as-is and ignored by models that don't support it.

encoding_format

string

Requested embedding encoding, e.g. "float" or "base64". Forwarded to the upstream provider as-is — support depends on the model.

provider

object

Unsupported. The entire object is ignored and removed before forwarding; it cannot select an upstream or price tier.

Basic Request

1
2
3
4
5
6
7
8
9
10
11
12
13
from openai import OpenAI

client = OpenAI(
    base_url="https://api.bazaarlink.ai/v1",
    api_key="sk-bl-YOUR_API_KEY",
)

response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input="The quick brown fox jumps over the lazy dog",
)

print(response.data[0].embedding)  # 1536-dimensional vector

Batch Processing

Send an array of strings to embed multiple texts in a single request — cheaper and faster than one call per text.

1
2
3
4
5
6
7
8
9
10
11
response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=[
        "Machine learning is a subset of artificial intelligence",
        "Deep learning uses neural networks with multiple layers",
        "Natural language processing enables computers to understand text",
    ],
)

for i, item in enumerate(response.data):
    print(f"Embedding {i}: {len(item.embedding)} dimensions")

Multimodal Input (Image + Text)

Models with image input support (output_modalities includes "embeddings" and inputModalities includes "image") accept input items shaped as {content:[{type:"text",...}, {type:"image_url",...}]}, letting you embed an image alone or jointly with text.

Model-dependent

Only some embedding models accept image input — check a model's supported modalities on the Models page before sending image_url content. Text-only models will reject this shape.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import requests

response = requests.post(
    "https://api.bazaarlink.ai/v1/embeddings",
    headers={
        "Authorization": "Bearer sk-bl-YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "google/gemini-embedding-2-preview",
        "input": [{
            "content": [
                {"type": "text", "text": "A scenic boardwalk through a green meadow"},
                {"type": "image_url", "image_url": {"url": "https://example.com/boardwalk.jpg"}},
            ]
        }],
        "encoding_format": "float",
    },
)

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

Finding Embedding Models

There's no dedicated embeddings model-listing endpoint — call GET /v1/models and filter client-side for entries whose output_modalities includes "embeddings", or browse the Models page.

Limitations

No streaming — embeddings are always returned as a complete response, unlike chat completions.
Each model has a maximum input length; text beyond that limit is truncated or rejected upstream.
Embeddings for identical input are deterministic — no temperature or randomness involved.

Best Practices

Choose a model for your speed/quality/cost tradeoff — smaller models (e.g. qwen/qwen3-embedding-4b) are cheaper and faster; larger ones (e.g. openai/text-embedding-3-large) generally embed with higher fidelity.
Batch multiple texts into one request instead of one call per text — fewer round trips, lower overhead.
Cache results — embeddings for the same input never change, so store them rather than regenerating.
Compare with cosine similarity, not Euclidean distance — it's scale-invariant and works better for high-dimensional vectors.
Watch each model's context length — long documents may need chunking before embedding.