/api/v1/chat/completions

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": "Explain what an API rate limit is in two sentences."
      }
    ],
    "max_tokens": 300
  }'

import os
from openai import OpenAI

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

response = 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,
)

print(response.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 response = 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,
});

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

IMG=$(base64 < photo.jpg | tr -d '\n')

curl https://railwail.com/api/v1/chat/completions \
  -H "Authorization: Bearer $RAILWAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "model": "gpt-4o-mini-vision",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image in one sentence."},
        {
          "type": "image_url",
          "image_url": {"url": "data:image/jpeg;base64,$IMG"}
        }
      ]
    }
  ],
  "max_tokens": 300
}
EOF

import os
import base64
from openai import OpenAI

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

with open("photo.jpg", "rb") as f:
    image = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="gpt-4o-mini-vision",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this image in one sentence."},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{image}"},
                },
            ],
        },
    ],
    max_tokens=300,
)

print(response.choices[0].message.content)

import OpenAI from "openai";
import { readFileSync } from "node:fs";

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

const image = readFileSync("photo.jpg").toString("base64");

const response = await client.chat.completions.create({
  model: "gpt-4o-mini-vision",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Describe this image in one sentence." },
        {
          type: "image_url",
          image_url: { url: `data:image/jpeg;base64,${image}` },
        },
      ],
    },
  ],
  max_tokens: 300,
});

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

{
  "id": "chatcmpl-<job id>",
  "object": "chat.completion",
  "created": <unix seconds>,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "<answer>",
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": <n>,
    "completion_tokens": <n>,
    "total_tokens": <n>
  },
  "system_fingerprint": "rw-gpt-4o-mini"
}

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 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)

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);
}

data: {"id":"chatcmpl-<job id>","object":"chat.completion.chunk","created":<unix>,"model":"gpt-4o-mini","system_fingerprint":"rw-gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant","content":"","refusal":null},"logprobs":null,"finish_reason":null}],"usage":null}

data: {…,"choices":[{"index":0,"delta":{"content":"An API rate"},"logprobs":null,"finish_reason":null}],"usage":null}

: keep-alive

data: {…,"choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}],"usage":null}

data: {…,"choices":[],"usage":{"prompt_tokens":<n>,"completion_tokens":<n>,"total_tokens":<n>}}

data: [DONE]

import json
import os
from openai import OpenAI

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

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
            "additionalProperties": False,
        },
    },
}]

def get_weather(city: str) -> dict:
    # Your implementation; a stub here.
    return {"city": city, "sky": "clear"}

messages = [{"role": "user", "content": "What is the weather in Paris right now?"}]

# 1. The model asks for the tool (finish_reason "tool_calls").
first = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=tools, max_tokens=300)
reply = first.choices[0].message
messages.append(reply)

# 2. Run every requested function, answer with role "tool".
for call in reply.tool_calls or []:
    args = json.loads(call.function.arguments)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(get_weather(args["city"]))})

# 3. The model answers with the result.
final = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=tools, max_tokens=300)
print(final.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 tools: OpenAI.ChatCompletionTool[] = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Current weather for a city",
      parameters: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
        additionalProperties: false,
      },
    },
  },
];

// Your implementation; a stub here.
function getWeather(city: string) {
  return { city, sky: "clear" };
}

const messages: OpenAI.ChatCompletionMessageParam[] = [
  { role: "user", content: "What is the weather in Paris right now?" },
];

// 1. The model asks for the tool (finish_reason "tool_calls").
const first = await client.chat.completions.create({ model: "gpt-4o-mini", messages, tools, max_tokens: 300 });
const reply = first.choices[0].message;
messages.push(reply);

// 2. Run every requested function, answer with role "tool".
for (const call of reply.tool_calls ?? []) {
  if (call.type !== "function") continue;
  const args = JSON.parse(call.function.arguments) as { city: string };
  messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(getWeather(args.city)) });
}

// 3. The model answers with the result.
const final = await client.chat.completions.create({ model: "gpt-4o-mini", messages, tools, max_tokens: 300 });
console.log(final.choices[0].message.content);

# Second request of the round trip: the assistant turn with its tool_calls,
# then one role "tool" message per call (id from the first answer).
curl https://railwail.com/api/v1/chat/completions \
  -H "Authorization: Bearer $RAILWAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "max_tokens": 300,
    "tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}],
    "messages": [
      {"role": "user", "content": "What is the weather in Paris right now?"},
      {"role": "assistant", "content": null, "tool_calls": [{"id": "CALL_ID", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}}]},
      {"role": "tool", "tool_call_id": "CALL_ID", "content": "{\"city\":\"Paris\",\"sky\":\"clear\"}"}
    ]
  }'

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": "Extract the city and country: I moved to Lyon last year."
      }
    ],
    "max_tokens": 300,
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "place",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "city": {"type": "string"},
            "country": {"type": "string"}
          },
          "required": ["city", "country"],
          "additionalProperties": false
        }
      }
    }
  }'

import os
import json
from openai import OpenAI

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

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": "Extract the city and country: I moved to Lyon last year.",
        },
    ],
    max_tokens=300,
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "place",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "country": {"type": "string"},
                },
                "required": ["city", "country"],
                "additionalProperties": False,
            },
        },
    },
)

data = json.loads(response.choices[0].message.content)
print(data)

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    {
      role: "user",
      content: "Extract the city and country: I moved to Lyon last year.",
    },
  ],
  max_tokens: 300,
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "place",
      strict: true,
      schema: {
        type: "object",
        properties: {
          city: { type: "string" },
          country: { type: "string" },
        },
        required: ["city", "country"],
        additionalProperties: false,
      },
    },
  },
});

const data = JSON.parse(response.choices[0].message.content ?? "{}");
console.log(data);

curl -sS -D - -o /dev/null https://railwail.com/api/v1/chat/completions \
  -H "Authorization: Bearer $RAILWAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "max_tokens": 50, "store": false, "messages": [{"role": "user", "content": "Hi"}]}'

# "store" is an OpenAI field railwail does not forward, so the answer names it:
# X-Railwail-Ignored-Params: store

import os
from openai import OpenAI

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

raw = client.chat.completions.with_raw_response.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hi"}],
    max_tokens=50,
)
print(raw.headers.get("x-railwail-job-id"))
print(raw.headers.get("x-railwail-ignored-params"))  # None when nothing was dropped
print(raw.headers.get("x-ratelimit-remaining"))
completion = raw.parse()
print(completion.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 { data, response } = await client.chat.completions
  .create({ model: "gpt-4o-mini", messages: [{ role: "user", content: "Hi" }], max_tokens: 50 })
  .withResponse();

console.log(response.headers.get("x-railwail-job-id"));
console.log(response.headers.get("x-railwail-ignored-params")); // null when nothing was dropped
console.log(response.headers.get("x-ratelimit-remaining"));
console.log(data.choices[0].message.content);