Code language

railwail on npm · 1.0.0

Railwail SDK

A small TypeScript client for the Railwail API: one function per task, no base URLs to remember, zero dependencies. It covers request/response chat, images, embeddings, the model catalog and job lookups. For streaming, tools, JSON output, video or audio use the OpenAI SDK or plain HTTP.

Installation

bash

npm install railwail

Version 1.0.0 is the published release. ESM and CommonJS builds, no dependencies. It needs a global fetch, so Node.js 18 or newer (or any runtime that provides fetch).

Create a client

The default export is a factory. The SDK does not read environment variables by itself, so pass the key explicitly.

client.mjs

import railwail from "railwail";

const rw = railwail(process.env.RAILWAIL_API_KEY);

Or use the class with options (both are the same client; see Configuration):

client.mjs

import { Railwail } from "railwail";

const rw = new Railwail(process.env.RAILWAIL_API_KEY, {
  baseUrl: "https://railwail.com", // default
  timeout: 120000,                 // ms, default 2 minutes
});

Methods

Method	What it does	Returns
rw.run()	One call for chat, image or embedding models; picks the endpoint from the model name	`string \| ImageResult[] \| number[][]`
rw.chat()	Chat completion with the full response and token usage	`ChatResponse`
rw.image()	Images from a prompt	`ImageResponse`
rw.embed()	Vector embeddings for one text or a list	`EmbeddingResponse`
rw.models()	List and filter the model catalog	`ModelListResponse`
rw.model()	One model with prices and configuration	`Model`
rw.job()	Status and result of a job by id	`Job`

What the SDK does not do

Need	Use instead
Streaming, tool calls, JSON schema output, image input	OpenAI SDK with `baseURL: "https://railwail.com/api/v1"` · Chat Completions
Video generation	/api/v1/videos/generations
Text to speech, transcription	audio/speech · audio/transcriptions
Retries, rate-limit headers	fetch or the OpenAI SDK (Rate limits)
Python	The OpenAI Python SDK; there is no railwail package on PyPI (guide)

How rw.run() picks the endpoint

Inside the SDK, rw.run() looks at the model slug: a built-in list of image models plus the substrings flux, dall-e, stable-diffusion, ideogram and recraft go to images, slugs containing embed go to embeddings, everything else goes to chat. Image models whose slug matches none of those (for example imagen-4-flagship or sdxl-replicate) need the type option:

TypeScript

await rw.run("flux-1-schnell", "A cat in a spacesuit");                         // image
await rw.run("imagen-4-flagship", "A cat in a spacesuit", { type: "image" });  // image, explicit
await rw.run("gpt-4o-mini", "Hello", { max_tokens: 100 });                      // chat

Video and speech models are not supported by the SDK

Their slugs match none of the rules, so rw.run() would send them to chat, which answers 400 model_not_supported. Call their REST endpoints instead.

Explore methods

rw.run()

One call for chat, image and embedding models.

rw.chat()

Chat completions with usage.

rw.image()

Images, options per model, job ids.

rw.embed()

Embeddings and the endpoint status.

rw.models()

List and filter the catalog.

rw.job()

Job status, output, cost, timing.

RailwailError

API errors and what else can throw.

Configuration

Key, base URL, timeout, runtimes.