rw.chat()

rw.chat(model: string, messages: ChatMessage[], options?: ChatOptions): Promise<ChatResponse>

interface ChatMessage {
  role: "system" | "user" | "assistant";
  content: string;
}

interface ChatOptions {
  temperature?: number;
  max_tokens?: number;
  top_p?: number;
  frequency_penalty?: number;
  presence_penalty?: number;
  stop?: string | string[];
  stream?: false;
}

interface ChatResponse {
  id: string;                  // "chatcmpl-<job id>"
  object: "chat.completion";
  created: number;             // unix seconds
  model: string;               // the model you sent
  choices: {
    index: number;
    message: { role: "assistant"; content: string };
    finish_reason: string;     // "stop" | "length" | "tool_calls" | "content_filter"
    logprobs: null;
  }[];
  usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
  system_fingerprint: string;  // "rw-<slug of the model that answered>"
}

import railwail from "railwail";

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

const res = await rw.chat(
  "gpt-4o-mini",
  [{ role: "user", content: "Say hello in three languages." }],
  { max_tokens: 300 },
);

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

import os
from openai import OpenAI

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

res = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in three languages."}],
    max_tokens=300,
)
print(res.choices[0].message.content)
print(res.usage)

curl https://railwail.com/api/v1/chat/completions \
  -H "Authorization: Bearer $RAILWAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello in three languages."}],
    "max_tokens": 300
  }'

import railwail from "railwail";

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

const res = await rw.chat(
  "claude-sonnet-4-6",
  [
    { role: "system", content: "You are a concise technical writer." },
    { role: "user", content: "Explain WebSockets in two sentences." },
  ],
  { temperature: 0.3, max_tokens: 200 },
);

console.log(res.choices[0].message.content);
console.log(res.choices[0].finish_reason); // "stop", or "length" when max_tokens was reached
console.log(res.system_fingerprint);       // "rw-claude-sonnet-4-6"

import os
from openai import OpenAI

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

res = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": "You are a concise technical writer."},
        {"role": "user", "content": "Explain WebSockets in two sentences."},
    ],
    temperature=0.3,
    max_tokens=200,
)
print(res.choices[0].message.content)
print(res.choices[0].finish_reason)

curl https://railwail.com/api/v1/chat/completions \
  -H "Authorization: Bearer $RAILWAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "system", "content": "You are a concise technical writer."},
      {"role": "user", "content": "Explain WebSockets in two sentences."}
    ],
    "temperature": 0.3,
    "max_tokens": 200
  }'

import railwail, { type ChatMessage } from "railwail";

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

const messages: ChatMessage[] = [
  { role: "user", content: "What is the capital of France?" },
];

const first = await rw.chat("gpt-4o-mini", messages, { max_tokens: 300 });
messages.push({ role: "assistant", content: first.choices[0].message.content });

// The API is stateless: send the whole conversation every time.
messages.push({ role: "user", content: "And its population?" });
const second = await rw.chat("gpt-4o-mini", messages, { max_tokens: 300 });

console.log(second.choices[0].message.content);

import os
from openai import OpenAI

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

messages = [{"role": "user", "content": "What is the capital of France?"}]

first = client.chat.completions.create(model="gpt-4o-mini", messages=messages, max_tokens=300)
messages.append({"role": "assistant", "content": first.choices[0].message.content})

# The API is stateless: send the whole conversation every time.
messages.append({"role": "user", "content": "And its population?"})
second = client.chat.completions.create(model="gpt-4o-mini", messages=messages, max_tokens=300)
print(second.choices[0].message.content)

import OpenAI from "openai";

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

const stream = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    {
      role: "user",
      content: "Explain what an API rate limit is in two sentences.",
    },
  ],
  max_tokens: 300,
  stream: true,
  stream_options: { include_usage: true },
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta;
  if (delta?.content) process.stdout.write(delta.content);
  if (chunk.usage) console.log("\n", chunk.usage);
}

import os
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": "Explain what an API rate limit is in two sentences.",
        },
    ],
    max_tokens=300,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

curl -N https://railwail.com/api/v1/chat/completions \
  -H "Authorization: Bearer $RAILWAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Explain what an API rate limit is in two sentences."
      }
    ],
    "max_tokens": 300,
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

import railwail, { RailwailError } from "railwail";

// A longer timeout for long answers (default 120 s).
const rw = railwail(process.env.RAILWAIL_API_KEY!, { timeout: 300_000 });

try {
  const res = await rw.chat("gpt-4o-mini", [{ role: "user", content: "Hello" }], { max_tokens: 300 });

  // 1.0.0 throws only for non-2xx answers. A run slower than 25 s answers 200
  // early; if it fails later, the body is { error } instead of choices.
  const body = res as typeof res & { error?: { code: string; message: string } };
  if (body.error) throw new Error(`${body.error.code}: ${body.error.message}`);

  console.log(res.choices[0].message.content);
} catch (err) {
  if (err instanceof RailwailError) {
    // JSON error from the API: err.status, err.type, err.code, err.message
    console.error(err.status, err.code, err.message);
  } else if (err instanceof Error && err.name === "AbortError") {
    // Timeout on your side. The run continues on the server and is billed.
    console.error("timed out");
  } else {
    // TypeError "fetch failed" (network) or SyntaxError (a non-JSON body, e.g. an edge 502 page)
    throw err;
  }
}