OpenAI drop-in replacement

The fastest way onto Roadie is to keep the code you already have. Roadie exposes an OpenAI-compatible surface, so the official OpenAI SDKs — and anything else that speaks the OpenAI wire format — work unchanged. You do not adopt a new SDK, and you are not locked in: point the same client back at OpenAI whenever you want. Only two things change versus calling OpenAI directly:

Base URL → /openai/v1
API key → your Roadie secret key (rd_sk_…)

Everything else — models, messages, streaming, tools, JSON mode, vision, embeddings, images — stays the same.

Behind that unchanged surface you get what Roadie adds: your OpenAI and Anthropic keys held server-side (BYOK), per-end-user limits and quotas, spend budgets, usage metering, request logs, and cross-provider fallback.

1. Install the official OpenAI SDK

These are the stock OpenAI packages — not a Roadie fork.

npm install openai

pip install openai

Put your Roadie secret key in the environment. Create one in the dashboard for the environment you want to call (development or production).

export ROADIE_API_KEY="rd_sk_prod_…"

A secret key grants full access to your project’s data plane. Keep it on your server — never ship it in a browser or mobile app. For client apps, mint short-lived client tokens; they authenticate against this same surface.

2. Send a chat completion

Construct the client with the two overrides, then call it exactly as you would OpenAI.

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://gateway.roadie.paroaria.ai/openai/v1',
  apiKey: process.env.ROADIE_API_KEY, // your rd_sk_… secret key
});

const completion = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a concise assistant.' },
    { role: 'user', content: 'In one sentence, what is Roadie?' },
  ],
});

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

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.roadie.paroaria.ai/openai/v1",
    api_key=os.environ["ROADIE_API_KEY"],  # your rd_sk_… secret key
)

completion = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "In one sentence, what is Roadie?"},
    ],
)

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

Model names

The model field accepts three forms:

A bare OpenAI name like gpt-4o — resolved to openai/gpt-4o when it is in your project’s catalog (OpenAI is the default provider on this surface).
A qualified provider/model id like anthropic/claude-sonnet-5 — routes to that provider directly. This is how you reach Anthropic through the OpenAI SDK.
A project alias like smart — a stable name you define that can fail over across providers. See Models, aliases & fallback.

3. Streaming

Streaming works verbatim — pass stream: true and iterate the deltas.

const stream = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Stream a haiku about routing.' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Stream a haiku about routing."}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Ask for a usage summary at the end of a stream with stream_options: { include_usage: true } (Node) / stream_options={"include_usage": True} (Python) — the final chunk then carries the token usage.

4. Embeddings and images work too

The same client reaches embeddings and images with no extra setup.

// Embeddings
const embeddings = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: ['The quick brown fox.', 'A second document to embed.'],
});

// Images (returned as base64)
const image = await client.images.generate({
  model: 'gpt-image-1',
  prompt: 'A watercolor fox on a transparent background.',
});
const pngBase64 = image.data[0].b64_json;

# Embeddings
embeddings = client.embeddings.create(
    model="text-embedding-3-small",
    input=["The quick brown fox.", "A second document to embed."],
)

# Images (returned as base64)
image = client.images.generate(
    model="gpt-image-1",
    prompt="A watercolor fox on a transparent background.",
)
png_base64 = image.data[0].b64_json

Image responses are always returned as b64_json (never a URL), and n is capped at 1 per request. Both images.generate (/images/generations) and images.edit (/images/edits) are supported. Embeddings accept a string or an array of strings.

Authentication rule

The OpenAI-compatible surface accepts either credential type as the SDK’s API key:

A secret key (rd_sk_…) — for server-side code.
A client token (a short-lived JWT minted for an end user) — for browser and mobile apps.

A publishable key (rd_pk_…) is mint-only: it can create client tokens but cannot call model endpoints, so using one here returns 403. See Authentication.

When to reach for the Roadie SDK instead

The OpenAI-compatible surface is the zero-friction path — nothing to learn, nothing to migrate. The first-party @roadie/sdk is optional and layers on typed error classes, built-in retries and idempotency, and a normalized response with usage, cost, and the gateway requestId. Use whichever fits; both hit the same gateway.

Next steps

Node quickstart

Adopt @roadie/sdk for typed errors, retries, and streaming.

Using OpenAI SDKs

The full compatibility reference across Node, Python, and Swift.

OpenAI migration guide

What maps one-to-one and what to watch for.

Rate limits, quotas & budgets

Cap spend and usage before it happens.

Get started

Core concepts

Guides

SDKs

OpenAI drop-in replacement

1. Install the official OpenAI SDK

2. Send a chat completion

Model names

3. Streaming

4. Embeddings and images work too

Authentication rule

When to reach for the Roadie SDK instead

Next steps

Node quickstart

Using OpenAI SDKs

OpenAI migration guide

Rate limits, quotas & budgets

​1. Install the official OpenAI SDK

​2. Send a chat completion

​Model names

​3. Streaming

​4. Embeddings and images work too

​Authentication rule

​When to reach for the Roadie SDK instead

​Next steps

Node quickstart

Using OpenAI SDKs

OpenAI migration guide

Rate limits, quotas & budgets

1. Install the official OpenAI SDK

2. Send a chat completion

Model names

3. Streaming

4. Embeddings and images work too

Authentication rule

When to reach for the Roadie SDK instead

Next steps