/api/v1/embeddings

Vector embeddings for text: semantic search, retrieval, clustering and similarity. The request follows OpenAI's embeddings.create, so the OpenAI SDKs work unchanged.

URL: https://railwail.com/api/v1/embeddings
Key scope: embeddings
Models: text-embedding-3-small · -large
Returns: vectors · X-Job-Id header

Request body

JSON. Unknown fields are rejected with 400 validation_failed.

model

string

text-embedding-3-small or text-embedding-3-large.Default text-embedding-3-small

inputrequired

string | string[]

One text or a list of up to 2,048 texts. The whole request is one job: charged once and settled on the tokens used, all or nothing. The vectors come back in input order.

encoding_format

string

float returns number arrays; base64 returns each vector as base64 of float32 values, little-endian, exactly like OpenAI. The OpenAI Node SDK asks for base64 by default and decodes it for you.Default float

dimensions

number

text-embedding-3 models only: the vector is shortened to this size and re-normalised to unit length (at most 1,536 for -small, 3,072 for -large). Other models answer 400 unsupported_parameter.

user

string

Your own end-user id, up to 256 characters.

One request returns at most 2,000,000 values (inputs × dimensions): about 1,300 inputs for text-embedding-3-small or 650 for -large, more with a smaller dimensions. Above that the answer is 413 too_many_embedding_values before anything is charged.

Examples

curl https://railwail.com/api/v1/embeddings \
  -H "Authorization: Bearer $RAILWAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": ["Hello world", "Good morning"]}'

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["RAILWAIL_API_KEY"], base_url="https://railwail.com/api/v1")

res = client.embeddings.create(model="text-embedding-3-small", input=["Hello world", "Good morning"])
print(len(res.data), len(res.data[0].embedding))  # 2 1536

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.RAILWAIL_API_KEY, baseURL: "https://railwail.com/api/v1" });

// The SDK requests base64 and decodes it into numbers.
const res = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: "Hello world",
  dimensions: 512,
});
console.log(res.data[0].embedding.length); // 512

Response

Shape of the answer; the vector is shortened.

JSON

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [<float>, <float>, ...] }
  ],
  "model": "<provider model id>",
  "usage": { "prompt_tokens": <number>, "total_tokens": <number> }
}

model echoes the provider's model id. text-embedding-3-small has 1,536 dimensions, text-embedding-3-large 3,072. The job id is in the X-Job-Id header. The vectors exist only in this answer: GET /api/v1/jobs/{id} reports the count, the size and the usage.

Errors

Status	Code	What it means
400	`validation_failed`	A field is unknown or out of range; details lists which.
400	`unsupported_parameter`	dimensions on a model that cannot be shortened (invalid_value: larger than the model's size).
400	`provider_rejected_input`	The provider refused an input (too many tokens, empty text). Refunded.
402	`insufficient_credits`	The balance does not cover the run.
402	`monthly_limit_exceeded`	The account's monthly spending limit is reached.
403	`insufficient_scope`	The key lacks the embeddings scope.
404	`model_not_found`	No embedding model with this slug.
413	`too_many_embedding_values`	More than 2,000,000 values in one request. Nothing charged.
502	`upstream_error`	The provider answered without readable vectors. Refunded.
503	`model_unavailable`	Provider or gateway error. Refunded; retry later.
504	`provider_timeout`	No answer within 85 seconds. Stopped and refunded; there is no background job to poll.

/api/v1/embeddings

Request body#

Examples#

Response#

Errors#

Request body

Examples

Response

Errors