Railwail
Sign In

SDK · embeddings

rw.embed()

Vector embeddings for one text or a list of texts, for search, clustering and retrieval. Calls POST /api/v1/embeddings; the key needs the embeddings scope.

Signature

TypeScript
rw.embed(model: string, input: string | string[], options?: EmbeddingOptions): Promise<EmbeddingResponse>

Parameters

modelrequired
string
text-embedding-3-small or text-embedding-3-large.
inputrequired
string | string[]
One text or a list of up to 2,048. The whole call is one job: charged once, all or nothing, vectors in input order.
options.encoding_format
stringkeep float
Leave it out. "base64" works on the API (float32, little-endian, like OpenAI), but 1.0.0 types embedding as number[] and does not decode it.Default float

Response

TypeScript
interface EmbeddingResponse {
  object: "list";
  data: {
    object: "embedding";
    embedding: number[];
    index: number;
  }[];
  model: string;
  usage: {
    prompt_tokens: number;
    total_tokens: number;
  };
}

text-embedding-3-small returns 1,536 dimensions, text-embedding-3-large 3,072. Shorter vectors (dimensions) are not typed in 1.0.0: use the REST API or the OpenAI SDK for them. One call returns at most 2,000,000 values (inputs × dimensions), otherwise it throws 413 too_many_embedding_values before anything is charged. All limits and errors: POST /api/v1/embeddings.

Examples

One text

TypeScript
const res = await rw.embed("text-embedding-3-small", "Hello world");
console.log(res.data[0].embedding.length);

Several texts in one call

TypeScript
const res = await rw.embed("text-embedding-3-small", [
  "How do I reset my password?",
  "I forgot my login credentials",
  "What are your pricing plans?",
]);

for (const item of res.data) {
  console.log(item.index, item.embedding.length);
}

Cosine similarity

TypeScript
function cosine(a: number[], b: number[]): number {
  let dot = 0, na = 0, nb = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    na += a[i] * a[i];
    nb += b[i] * b[i];
  }
  return dot / (Math.sqrt(na) * Math.sqrt(nb));
}

const docs = ["JavaScript tutorial", "Python guide", "Cooking recipes"];
const [docsRes, queryRes] = await Promise.all([
  rw.embed("text-embedding-3-small", docs),
  rw.embed("text-embedding-3-small", "How to learn programming"),
]);

const query = queryRes.data[0].embedding;
const ranked = docsRes.data
  .map((d, i) => ({ doc: docs[i], score: cosine(query, d.embedding) }))
  .sort((a, b) => b.score - a.score);
console.log(ranked[0].doc);
rw.embed() — Railwail Docs