Railwail
Sign In

SDK · catalog

rw.models() / rw.model()

Read the model catalog: list models with filters and pagination, or fetch one model with its prices, limits and configuration. Wraps GET /api/v1/models, which is public.

rw.models()

TypeScript
rw.models(options?: ModelListOptions): Promise<ModelListResponse>
options.category
string
One of: text, image, video, audio, speech_tts, transcription_stt, embedding, code, multimodal, vla_robotics.
options.provider
string
The infrastructure provider, one of: openai, anthropic, google, replicate, together, mistral, deepseek, elevenlabs, vastai, huggingface, custom. Lab names such as meta are not valid values.
options.featured
boolean
Only featured models.
options.limit
number
Page size, at most 500. Without it the server returns every listed model in one page.Default all (≤ 500)
options.offset
number
Skip this many models.Default 0

Unknown filter values

A category or provider outside the lists above throws a RailwailError with status 400 and the code invalid_category or invalid_provider; the message lists the allowed values.

Response

TypeScript
interface ModelListResponse {
  object: "list";
  data: Model[];
  has_more: boolean;
  total: number; // models in this list: every model that can run right now
}

Examples

TypeScript
// Every image model that can run (no limit = the whole list in one page)
const images = await rw.models({ category: "image" });
console.log(images.data.map((m) => m.id));

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

// Models served through OpenAI
const openai = await rw.models({ provider: "openai" });

// Walk every page
for (let offset = 0; ; offset += 100) {
  const page = await rw.models({ limit: 100, offset });
  // ...
  if (!page.has_more) break;
}

rw.model()

TypeScript
rw.model(slug: string): Promise<Model>
slugrequired
string
Model slug, e.g. gpt-4o-mini. A provider model id also resolves, but can match several slugs, so prefer the slug.

Model object

TypeScript
interface Model {
  id: string;                 // the slug
  object: "model";
  created: number;
  owned_by: string;           // infrastructure provider, e.g. "replicate" for FLUX models
  name: string;
  description: string;
  category: string;
  provider_model_id: string;
  image: string | null;
  pricing: {
    credit_cost_input_per_1k: number;  // legacy column, credits per 1K input tokens
    credit_cost_output_per_1k: number; // legacy column, credits per 1K output tokens
    credit_cost_fixed: number;         // legacy column, credits per run
    currency: "credits";
    credit_usd: number;                // USD per credit
  };
  // Sent by the API, not typed in railwail@1.0.0 (read them with a cast):
  //   available: boolean; unavailable_reason?: string; use_instead?: string;
  //   lifecycle?: { status?: string; successor_slug?: string; duplicate_of?: string };
  //   pricing.unit, pricing.usd, pricing.credits, pricing.basis (the rule the API bills with)
  capabilities: {
    context_window: number | null;
    max_output_tokens: number | null;
    supported_formats: string[];
  };
  metadata: {
    tags: string[];
    is_new: boolean;
    is_featured: boolean;
    avg_latency_ms: number | null;
    estimated_duration_seconds: number | null;
  };
  // rw.model() only:
  long_description?: string;
  configuration?: {
    input_schema: Record<string, unknown>;   // the model's inputs, as on its page
    default_params: Record<string, unknown>;
  };
  examples?: unknown[];
}

Example

TypeScript
const model = await rw.model("flux-1-schnell");
console.log(model.name, model.category); // name and "image"
console.log(model.owned_by);             // "replicate"
const price = model.pricing as typeof model.pricing & { unit: string; usd: number | null };
console.log(price.unit, price.usd);      // "per_image" and the USD of one default call

The list holds models that can run

rw.models() returns only models the API can run right now. rw.model(slug) also answers for a model that cannot run, with available: false, the reason and, when there is one, use_instead; calling it returns 503 model_unavailable. 1.0.0 has no option for the full catalog: call GET /api/v1/models?include_unavailable=true directly. Every model page on /models shows whether it can run.

The request is free. With a key it needs the read scope (default on new keys) and counts toward the key's rate limit.

rw.models() — Railwail Docs