Capabilities

Embeddings

Create single or batched vector embeddings for retrieval workflows.

On this page

This page is for developers building semantic search, retrieval, clustering, or other vector workflows.

POST /v1/embeddings accepts an OpenAI-compatible JSON request. The gateway forwards the body and uses upstream-reported usage.cost when present.

Create embeddings with curl#

BashSyntax highlighted

curl https://api.clssai.com/v1/embeddings \
  -H "Authorization: Bearer $CLSSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/text-embedding-3-small","input":["First document","Second document"]}'

Create embeddings with Python#

PythonSyntax highlighted

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.clssai.com/v1", api_key=os.environ["CLSSAI_API_KEY"])
response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=["First document", "Second document"],
)
for item in response.data:
    print(item.index, len(item.embedding))

Create embeddings with JavaScript#

JavaScriptSyntax highlighted

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.clssai.com/v1",
  apiKey: process.env.CLSSAI_API_KEY,
});
const response = await client.embeddings.create({
  model: "openai/text-embedding-3-small",
  input: ["First document", "Second document"],
});
for (const item of response.data) console.log(item.index, item.embedding.length);

Response and limits#

JSONSyntax highlighted

{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.012,-0.004]}],"model":"text-embedding-3-small","usage":{"prompt_tokens":2,"total_tokens":2}}

The response model can use the upstream's unprefixed name. Always send the complete author/model ID in requests. Vector dimensions, normalization, maximum batch size, token limits, and truncation behavior are model-defined. The gateway does not apply a documented universal truncation rule. Keep batches bounded and handle an upstream 4xx as a signal to reduce or correct the input.

Common mistakes#

Do not mix vectors from models or dimensions in the same index.
Do not assume input is silently truncated.
Include /v1 in the OpenAI SDK base URL and omit it from the Anthropic SDK base URL.
Call from a server, preserve complete variant IDs, check empty streaming choices, and use cf-ray for tracing.

Also available (pass-through, lightly tested)#

The rerank endpoint forwards a query, documents, and result limit. Its response fields are upstream-defined.

BashSyntax highlighted

curl https://api.clssai.com/v1/rerank \
  -H "Authorization: Bearer $CLSSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"voyageai/rerank-2.5-lite","query":"best result","documents":["first result","best matching result"],"top_n":1}'

JSONSyntax highlighted

{"model":"rerank-2.5-lite","results":[{"index":1,"relevance_score":0.99}],"usage":{"total_tokens":12}}

Need a hand?

Find answers to common questions or diagnose a failed request.

Frequently asked questions →Troubleshoot errors →