Using OpenAI SDKs

You do not have to adopt a Roadie SDK. Roadie exposes an OpenAI-compatible surface under /openai/v1, so the official OpenAI SDKs — and anything else that speaks the OpenAI wire format — work unchanged. Only two things change versus calling OpenAI directly:

Base URL → /openai/v1
API key → a Roadie secret key (rd_sk_…, server) or a client token (browser / mobile)

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. This page is the compatibility reference; for a step-by-step first call see the OpenAI drop-in quickstart.

Configure the client

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://gateway.roadie.paroaria.ai/openai/v1',
  apiKey: process.env.ROADIE_API_KEY, // an 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"],  # an rd_sk_… secret key
)

// Using MacPaw/OpenAI (or any OpenAI-compatible client):
let client = OpenAI(configuration: .init(
    token: bearerToken,                    // an rd_sk_… key (server) or a client token
    host: "gateway.roadie.paroaria.ai",
    basePath: "/openai/v1"
))

These are the stock OpenAI packages (npm install openai, pip install openai) — not a Roadie fork. On iOS, RoadieKit covers images; use an OpenAI-compatible Swift client for chat and embeddings (see the iOS SDK).

A secret key grants full access to your project’s data plane — keep it server-side. For browser and mobile apps, use a short-lived client token as the API key against this same surface. A publishable key (rd_pk_…) is mint-only and is rejected 403 here.

What works

The same client reaches every OpenAI-compatible endpoint with no extra setup:

Endpoint	OpenAI SDK call	Notes
Chat completions	`client.chat.completions.create(...)`	Streaming, tools, JSON mode, and vision all pass through.
Embeddings	`client.embeddings.create(...)`	Accepts a string or an array of strings.
Images	`client.images.generate(...)` / `client.images.edit(...)`	See the image differences below.
Models	`client.models.list()`	The catalog available to this credential (Models).

// Chat (Node) — call it exactly as you would OpenAI.
const completion = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'In one sentence, what is Roadie?' }],
});

// Streaming: 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 ?? '');
}

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

Differences to expect

The surface is faithful, but a few things differ from calling OpenAI directly:

Images return base64 only. Image responses are always b64_json (never a URL), and n is capped at 1 per request (n > 1 is rejected). Both images.generate (/images/generations) and images.edit (/images/edits) are supported. See Images.

Errors are mapped, statuses preserved. Failures use the OpenAI error envelope (so the OpenAI SDKs deserialize them into their typed error classes), while the HTTP status the SDK branches on is kept. The Roadie error taxonomy maps onto OpenAI’s type/code:

Roadie type	HTTP	OpenAI `type`
`authentication_error`	401	`invalid_request_error` (`code: invalid_api_key`)
`permission_error`	403	`invalid_request_error`
`not_found_error`	404	`invalid_request_error`
`invalid_request_error` / `idempotency_error`	400 / 409	`invalid_request_error`
`rate_limit_error`	429	`rate_limit_error`
`quota_error` / `budget_error`	429	`insufficient_quota` (`code: insufficient_quota`)
`provider_error` / `internal_error`	5xx	`api_error`

Platform-native fields aren’t on this surface. metadata and provider_options are not part of the OpenAI shape. To attribute a request to an end user, pass the OpenAI user string. For the full platform fields (and a normalized usage + cost + requestId response), use the native /v1/chat endpoint or the @roadie/sdk.
Streaming usage is opt-in. Ask for an end-of-stream token summary with stream_options: { include_usage: true } — the final chunk then carries usage.
Idempotency is automatic. The OpenAI SDKs set an Idempotency-Key on non-streaming requests; a retry with the same key and body replays the stored response without re-executing or re-metering.

When to reach for a Roadie SDK instead

The OpenAI-compatible surface is the zero-friction path — nothing to learn, nothing to migrate, and no lock-in (point the same client back at OpenAI whenever you want). 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

OpenAI drop-in quickstart

Your first call in two changes — base URL and key.

Migrate from OpenAI

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

TypeScript SDK

Typed errors, retries, and a normalized response.

Rate limits, quotas & budgets

Cap spend and usage before it happens.

Get started

Core concepts

Guides

SDKs

Using OpenAI SDKs

Configure the client

What works

Model names

Differences to expect

When to reach for a Roadie SDK instead

Next steps

OpenAI drop-in quickstart

Migrate from OpenAI

TypeScript SDK

Rate limits, quotas & budgets

​Configure the client

​What works

​Model names

​Differences to expect

​When to reach for a Roadie SDK instead

​Next steps

OpenAI drop-in quickstart

Migrate from OpenAI

TypeScript SDK

Rate limits, quotas & budgets

Configure the client

What works

Model names

Differences to expect

When to reach for a Roadie SDK instead

Next steps