OpenAI drop-in replacement

This tutorial takes an app that already calls OpenAI and moves it onto Roadie without adopting a new SDK. Roadie exposes an OpenAI-compatible surface at /openai/v1, so the official OpenAI SDKs — and anything that speaks the OpenAI wire format — work unchanged. You change exactly two things: the base URL and the API key. By the end you will have the same chat, streaming, embeddings, and image code running through Roadie, with your provider keys held server-side (BYOK), per-end-user attribution, and request logs — and you will have confirmed parity against your old OpenAI path.

This is the tutorial version of the OpenAI drop-in quickstart: it starts from an existing app, walks the switch in both Node and Python, and verifies the result.

Prerequisites

In the dashboard:

Create a project — its development and production environments are created for you.
Add and validate an OpenAI provider credential (BYOK). See Providers & BYOK. (Add an Anthropic key too if you want to reach Claude through the same client — see step 6.)
Create a secret key (rd_sk_…) for the environment you want to call.

Put the key in your environment:

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 instead.

1. Where you are today

A typical starting point calls OpenAI directly. The base URL is implicit and the key is an OpenAI key:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY, // sk-…
});

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])  # sk-…

2. Point the client at Roadie

Set baseURL to the OpenAI-compatible surface and pass your Roadie secret key. Nothing else in your call sites changes.

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

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
)

That is the entire migration. The remaining steps confirm each surface still works.

3. Verify a chat completion

Run one non-streaming completion and read the response exactly as before. The X-Request-Id response header ties this call to your Roadie logs.

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?' },
  ],
  user: 'user_42', // attributed as the end-user id — powers per-user limits + analytics
});

console.log(completion.choices[0].message.content);
console.log('tokens:', completion.usage?.total_tokens);
console.log('request id:', completion._request_id);

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?"},
    ],
    user="user_42",  # attributed as the end-user id
)

print(completion.choices[0].message.content)
print("tokens:", completion.usage.total_tokens)

Open the dashboard’s request logs and confirm the call appears, attributed to user_42, with the model served and token counts. That is the parity check: same response shape, plus metering you did not have before.

How `model` resolves

The model field accepts three forms:

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

4. Streaming still works verbatim

Pass stream: true and iterate the deltas — no change from OpenAI.

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

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,
    stream_options={"include_usage": True},
)

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

5. Embeddings and images

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, never a URL
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, never a URL
image = client.images.generate(
    model="gpt-image-1",
    prompt="A watercolor fox on a transparent background.",
)
png_base64 = image.data[0].b64_json

Images always come back as b64_json (never a URL) and n is capped at 1. Both images.generate and images.edit are supported. Image generation uses your OpenAI credential (gpt-image-1); there is no separate image key to add.

6. Reach Anthropic through the same client

Because a qualified provider/model id routes directly, you can send Claude requests through the OpenAI SDK — the one thing you could not do talking to OpenAI directly:

const completion = await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-5',
  messages: [{ role: 'user', content: 'Hello from the OpenAI SDK, via Anthropic.' }],
});

completion = client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "Hello from the OpenAI SDK, via Anthropic."}],
)

This needs a validated Anthropic provider credential in the same environment. OpenAI and Anthropic are the two providers supported today.

7. Errors map to the OpenAI error classes

Roadie returns the OpenAI error envelope, so the OpenAI SDKs deserialize failures into the same typed classes you already catch. The HTTP status the SDK keys on is preserved:

What happened	HTTP	OpenAI SDK error
Bad or revoked key	401	`AuthenticationError` (`code: invalid_api_key`)
Rate limit exceeded	429	`RateLimitError`
Quota or budget cap hit	429	`RateLimitError` (`code: insufficient_quota`)
Provider failure after fallback	5xx	`APIError`

import OpenAI from 'openai';

try {
  await client.chat.completions.create({ model: 'gpt-4o', messages });
} catch (err) {
  if (err instanceof OpenAI.RateLimitError) {
    // 429 — over a rate limit, quota, or budget. Back off or show a limit state.
  } else if (err instanceof OpenAI.AuthenticationError) {
    // 401 — your ROADIE_API_KEY is missing, wrong, or revoked.
  } else {
    throw err;
  }
}

import openai

try:
    client.chat.completions.create(model="gpt-4o", messages=messages)
except openai.RateLimitError:
    # 429 — over a rate limit, quota, or budget.
    ...
except openai.AuthenticationError:
    # 401 — your ROADIE_API_KEY is missing, wrong, or revoked.
    ...

On the native surface Roadie distinguishes quota_error (429) from budget_error (402), but the OpenAI schema has no 402, so both are reported here as insufficient_quota at 429. See the error mapping.

What you built

You migrated a working OpenAI app onto Roadie by changing only the base URL and the key. You kept your existing SDK, code, and error handling, and you gained: BYOK for OpenAI and Anthropic, per-end-user attribution, usage metering, request logs, and a path to cross-provider fallback — all without a rewrite. Point the client back at OpenAI whenever you like; there is no lock-in.

Next steps

Build a Node chat backend

Adopt @roadie/sdk for typed errors, retries, usage, cost, and requestId.

Per-user limits

Now that calls are attributed, give each user their own limits and quotas.

Cross-provider fallback

Fail over from OpenAI to Anthropic behind a single alias.

Observability

Read the usage, cost, and logs your migration just started producing.

​Prerequisites

​1. Where you are today

​2. Point the client at Roadie

​3. Verify a chat completion

​How model resolves

​4. Streaming still works verbatim

​5. Embeddings and images

​6. Reach Anthropic through the same client

​7. Errors map to the OpenAI error classes

​What you built

​Next steps

Build a Node chat backend

Per-user limits

Cross-provider fallback

Observability

Prerequisites

1. Where you are today

2. Point the client at Roadie

3. Verify a chat completion

How `model` resolves

4. Streaming still works verbatim

5. Embeddings and images

6. Reach Anthropic through the same client

7. Errors map to the OpenAI error classes

What you built

Next steps