Quickstart

Six steps from an empty project to a successful completion. Copy the examples and replace only the API key.

1. Create an API key

Open the ModelRail dashboard, create an API key, and copy the raw key immediately.

Things to note

The raw key is shown once when created. Store it before you leave the page.

2. Store the key

bash

export MODELRAIL_API_KEY=mr_live_...

Prefer a secrets manager in production. Do not commit keys or expose them in browser clients.

3. Configure the base URL

Inference lives under /v1 — not /api/v1.

text

Base URL: https://api.modelrail.dev/v1
Auth:     Authorization: Bearer $MODELRAIL_API_KEY

Note

OpenAI SDK clients should set baseURL: "https://api.modelrail.dev/v1".

4. Send the first request

Use modelrail-auto so ModelRail selects the appropriate workload alias.

curl "https://api.modelrail.dev/v1/chat/completions" \
  -H "Authorization: Bearer $MODELRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "modelrail-auto",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

const response = await fetch("https://api.modelrail.dev/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MODELRAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "modelrail-auto",
    messages: [{ role: "user", content: "Hello" }],
  }),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}

const completion = await response.json();
console.log(completion.choices[0]?.message?.content);
console.log(completion.model); // resolved ModelRail alias

import os
import requests

response = requests.post(
    "https://api.modelrail.dev/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['MODELRAIL_API_KEY']}"},
    json={
        "model": "modelrail-auto",
        "messages": [{"role": "user", "content": "Hello"}],
    },
)
response.raise_for_status()
completion = response.json()
print(completion["choices"][0]["message"]["content"])
print(completion["model"])  # resolved ModelRail alias

5. Read the response

A successful response is OpenAI-shaped JSON. The model field is the resolved ModelRail alias (not modelrail-auto when auto routed). Assistant text is in choices[0].message.content.

json

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "model": "modelrail-chat",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hello! How can I help?" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}

6. Continue

Optional: verify aliases with GET /v1/models. Next: Streaming, Models and aliases, or Chat completions.