Documentation

Build with Railwail

One SDK to access 100+ AI models. Text, images, video, audio — all with a single package.

$npm install railwail

Base URL:https://railwail.com/api/v1

Official SDK

Railwail SDK

The simplest way to use every AI model. One function call — no boilerplate, no configuration, no base URLs to remember.

Install

npm install railwail

Text Generation

const reply = await rw.run(
  "gpt-4",
  "Explain AI"
);

Image Generation

const imgs = await rw.run(
  "flux-schnell",
  "A cat in space"
);

Embeddings

const vecs = await rw.run(
  "text-embedding-3-small",
  "Hello",
  { type: "embed" }
);

Quick Start

Get up and running in under a minute.

Get your API key

Go to the Settings page to create your API key. Keys are prefixed with rw_live_.

Install the SDK

Install the official Railwail SDK from npm. Zero dependencies.

Terminal

npm install railwail

Make your first request

Two lines of code to generate text, images, or anything else.

JavaScript / TypeScript

import railwail from "railwail";

const rw = railwail("rw_live_xxxxx");

// Text generation
const reply = await rw.run("gpt-4", "Explain quantum computing");

// Image generation
const images = await rw.run("flux-schnell", "A sunset over Tokyo");

SDK Reference

Full reference for all SDK methods. The SDK auto-detects the right endpoint based on the model you use.

Universal

rw.run(model, input, options?)

The main method. Automatically routes to the right endpoint based on the model name. Returns a string for text, an array for images, or vectors for embeddings.

Examples

// String prompt → text response
const text = await rw.run("gpt-4", "Hello!");

// Message array → chat with history
const reply = await rw.run("claude-3-opus", [
  { role: "system", content: "You are a pirate." },
  { role: "user", content: "Tell me a joke" },
]);

// Image model → returns image URLs
const images = await rw.run("flux-schnell", "A cat in space");
console.log(images[0].url);

// Force endpoint type with { type: "embed" }
const vecs = await rw.run("text-embedding-3-small", "Hello", { type: "embed" });

Parameters

Parameter	Type	Description
model	string	Model slug (e.g. "gpt-4", "flux-schnell")
input	string \| ChatMessage[]	Prompt string or array of messages
options.type	string	Force endpoint: "chat", "image", or "embed"
options.temperature	number	Sampling temperature (0-2)
options.max_tokens	number	Maximum output tokens

Text

rw.chat(model, messages, options?)

Full chat completion response with usage stats. Returns the complete OpenAI-compatible response object.

Example

const res = await rw.chat("gpt-4", [
  { role: "user", content: "Hello!" }
], { temperature: 0.7, max_tokens: 500 });

console.log(res.choices[0].message.content);
console.log(res.usage); // { prompt_tokens, completion_tokens, total_tokens }

Image

rw.image(model, prompt, options?)

Generate images from a text prompt. Returns created timestamp and array of image objects with URLs.

Example

const res = await rw.image("flux-schnell", "A cyberpunk cityscape", {
  size: "1024x1024",
  n: 2,
  negative_prompt: "blurry, low quality",
});

for (const img of res.data) {
  console.log(img.url);
}

Options

Option	Type	Description
n	number	Number of images (1-4)
size	string	"256x256", "512x512", "1024x1024", "1024x1792", "1792x1024"
negative_prompt	string	Things to exclude from the image

Embeddings

rw.embed(model, input, options?)

Generate vector embeddings for text. Input can be a single string or an array of strings.

Example

const res = await rw.embed("text-embedding-3-small", ["Hello", "World"]);

for (const item of res.data) {
  console.log(item.embedding.length); // vector dimensions
}

Browse

rw.models(options?) / rw.model(slug)

List available models or get details for a specific one. Filter by category, provider, or featured status.

Examples

// List all image models
const imageModels = await rw.models({ category: "image" });

// Get details for a specific model
const model = await rw.model("flux-schnell");
console.log(model.name, model.pricing);

// List featured models with limit
const featured = await rw.models({ featured: true, limit: 10 });

Status

rw.job(id)

Check the status and result of an asynchronous generation job.

Example

const job = await rw.job("job_abc123");
console.log(job.status); // "completed" | "queued" | "processing" | "failed"
console.log(job.output_url); // result URL for images/video

Errors

RailwailError

All API errors throw a RailwailError with status code, error type, and human-readable message.

Error handling

import { RailwailError } from "railwail";

try {
  await rw.run("gpt-4", "Hello");
} catch (err) {
  if (err instanceof RailwailError) {
    console.log(err.status);  // 401, 402, 429, etc.
    console.log(err.code);    // "invalid_api_key", "insufficient_credits"
    console.log(err.message); // Human-readable error
  }
}

Config

Constructor Options

You can also import the Railwail class directly for more control.

Configuration

import { Railwail } from "railwail";

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

Authentication

All requests require an API key. When using the SDK, pass it to the constructor. For direct API calls, use a Bearer token in the Authorization header.

Header

Authorization: Bearer rw_live_xxxxx

Where to get your key: Generate API keys at railwail.com/settings. Keys prefixed with rw_live_ are for production and rw_test_ for testing.

API Endpoints

Direct REST API — fully OpenAI-compatible. Use these if you prefer raw HTTP or the OpenAI SDK.

POST

/api/v1/chat/completions

Chat completions with any text model

gpt-4o

claude-sonnet

gemini-pro

llama-3.1-70b

deepseek-chat

+ more

POST

/api/v1/images/generations

Generate images from text prompts

flux-schnell

flux-1.1-pro

dall-e-3

stable-diffusion-3.5

+ more

POST

/api/v1/embeddings

Generate vector embeddings

text-embedding-3-small

text-embedding-3-large

+ more

GET

/api/v1/models

List all available models with filtering

GET

/api/v1/models/:slug

Get details for a specific model

GET

/api/v1/jobs/:id

Check job status and get results

Code Examples

Examples using the OpenAI SDK (the API is fully compatible).

bash

curl https://railwail.com/api/v1/chat/completions \
  -H "Authorization: Bearer rw_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Rate Limits

Rate limits are applied per API key.

Tier	Rate Limit	Details
Free	10 requests/minute	Default for new accounts
Paid	60 requests/minute	For accounts with purchased credits
Enterprise	Custom	Contact us for higher limits

Error Codes

The API uses standard HTTP status codes to indicate success or failure.

Code	Status	Description
400	Bad Request	The request body is malformed or missing required fields
401	Unauthorized	Invalid or missing API key
402	Insufficient Credits	Your account does not have enough credits for this request
429	Rate Limit Exceeded	Too many requests. Retry after the cooldown period
500	Internal Server Error	Something went wrong on our end. Please try again later