Keep your SDK.
Meet one API.

Make your first request

Oproute speaks the OpenAI chat completions protocol. If you already have an OpenAI client, you change two things: the base URL and the key. Nothing else about your integration changes.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://oproute.web.id/v1",
    api_key=os.environ["OPROUTE_API_KEY"],
)

response = client.chat.completions.create(
    model="model-id-from-catalog",
    messages=[{"role": "user", "content": "Hello, Oproute!"}],
)

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

Authenticate with an API key

Send the key as a bearer token on every gateway request:

Authorization: Bearer $OPROUTE_API_KEY

A key is shown exactly once, at creation. Afterwards the dashboard lists only a masked prefix, and the server stores only a keyed digest — so a database leak cannot be turned into a working credential. If you lose a key, revoke it and create a new one; there is no way to recover it.

Keys belong to your account, not to a single integration. Every key shares one access window, one rate allowance and one fair-usage counter. Creating a second key does not create a second allowance — it is a way to separate credentials, not to multiply capacity.

Dashboard sign-in is separate and uses a server-managed HttpOnly session cookie. Your API key is never used to sign in to the website.

One endpoint carries your chat traffic

POST https://oproute.web.id/v1/chat/completions

curl https://oproute.web.id/v1/chat/completions \
  -H "Authorization: Bearer $OPROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-id-from-catalog",
    "messages": [{"role": "user", "content": "Hello, Oproute!"}]
  }'

Provider-specific features are available when the model you chose declares the matching capability. A parameter that a model cannot honour is rejected with a clear error rather than silently dropped, so you never ship an integration that quietly ignores half of what you sent.

What you may send

Requests are validated before anything reaches an upstream provider. Unknown fields are rejected rather than ignored.

Hard limits

Every bound below is enforced before anything reaches a provider, so an oversized or out-of-range request costs you nothing.

Unknown fields are refused rather than ignored. That is deliberate: a typo in a parameter name would otherwise be silently dropped, and you would debug a model's behaviour instead of your own request.

Message roles

Five roles are accepted: system sets behaviour for the conversation, developer does the same where a provider supports it, user is the human turn, assistant is a prior model turn you replay to keep context, and tool carries a tool result back and pairs with the call it answers. Any other role is rejected with the index of the offending message.

What comes back

A non-streaming request returns an OpenAI-compatible completion object. The fields you will actually read are:

Token counts are a measurement of what happened, not a budget. Oproute sells access by time, so nothing here depletes and no balance exists to check.

Stream tokens as they are produced

Set stream to true and the response becomes text/event-stream. Each event is a data: line containing one OpenAI-compatible chunk, and the stream ends with the literal sentinel data: [DONE].

curl -N https://oproute.web.id/v1/chat/completions \
  -H "Authorization: Bearer $OPROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-id-from-catalog",
    "messages": [{"role": "user", "content": "Count to five"}],
    "stream": true
  }'

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1758873600,"model":"...","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1758873600,"model":"...","choices":[{"index":0,"delta":{"content":"One"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1758873600,"model":"...","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

The first chunk carries the role. Middle chunks carry delta.content fragments — concatenate them in order. The final chunk before the sentinel carries an empty delta and a finish_reason. Read delta.content, not message.content, while streaming.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://oproute.web.id/v1",
  apiKey: process.env.OPROUTE_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "model-id-from-catalog",
  messages: [{ role: "user", content: "Hello, Oproute!" }],
  stream: true,
});

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

Read the catalog before you build

Model ids are never hardcoded in your integration — ask for the catalog and choose from what is actually serving. The response is a bare JSON array:

GET https://oproute.web.id/api/v1/models

{
  "id": "deepseek-v4.1-flash",
  "name": "DeepSeek V4.1 Flash",
  "provider": "deepseek",
  "context_window": 64000,
  "capabilities": {
    "vision": false,
    "tools": true,
    "streaming": true,
    "reasoning": false
  },
  "status": "available"
}

capabilities tells you what a model can actually do. Check the flag before sending a feature: a request for a capability the route does not declare is refused with a clear error rather than silently ignored. status is available for anything that can serve traffic right now.

Every plan includes the same model access. Plans differ only in how long the access lasts, so there is no model to unlock by paying more.

Read the response headers

Successful and fair-usage-throttled completions both carry these, so a client can pace itself from the account's current state instead of guessing.

X-Oproute-Gateway: oproute.web.id
X-Oproute-Request-ID: 9f2c41d8ab70e315
X-Oproute-FUP-Limit: 75000000
X-Oproute-FUP-Used: 18204416
X-Oproute-FUP-Reset: 2026-10-03T00:00:00Z
X-Oproute-RateLimit-RPM: 70
X-Oproute-Concurrency-Limit: 4

These appear on throttled responses too, which is what lets a client back off correctly instead of retrying blind.

What bounds a busy account

Fair usage exists so one account cannot occupy capacity that others depend on. It bounds pace, never access.

The threshold counts processed tokens for the whole account over a rolling window. Every key shares one counter, so adding a key does not add headroom.

When a request is refused for pace, the response is 429 and still carries the headers above, so your client can read the current limit and wait the right amount of time.

Every error is typed

Non-success responses always use one shape, so a single error handler covers the whole API:

{
  "error": {
    "code": "provider_not_configured",
    "message": "No provider route can serve this model yet."
  }
}

Branch on error.code, never on the message text — messages are written for humans and may be reworded.

Public endpoints you can call

These need no key. They are what a pricing page or a status banner is built from.

The status endpoint reports what it measured just now. It publishes no uptime percentage and no SLA, because a figure that is promised rather than measured is worth less than no figure at all.

Before you ship

• Keep the key on the server. A key in a browser bundle or a mobile app is a public key. Proxy through your own backend instead.
• Handle 429 with backoff, not retries in a tight loop. Read X-Oproute-RateLimit-RPM and pace against it.
• Set a timeout on every call. Long generations belong on stream: true, where you get tokens as they arrive instead of waiting for the whole answer.
• Check finish_reason. A length stop means the answer was truncated — raise max_tokens or ask for something shorter.
• Log X-Oproute-Request-ID. It turns "something failed yesterday" into a question that can actually be answered.
• Rotate keys per environment. Separate keys for staging and production mean you can revoke one without touching the other.