Developer docs

Point your OpenAI client at Realrouter.

The API keeps familiar OpenAI-style routes for responses, chat completions, files, and models. Replace the base URL, use your Realrouter key, and keep your client code small.

Quickstart

Install the official OpenAI SDK and set the Realrouter base URL. The dashboard will show your API key once when it is created.

quickstart.ts

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.REALROUTER_KEY,
  baseURL: "https://api.realrouter.org/v1",
});

const response = await client.responses.create({
  model: "gpt-5.4-mini",
  input: "Summarize this note in Chinese.",
});

console.log(response.output_text);

$0.375from / 1M input tokens

No monthly feerecharge when needed

OpenAI SDKcompatible base URL

quickstart.py

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["REALROUTER_KEY"],
    base_url="https://api.realrouter.org/v1",
)

response = client.responses.create(
    model="gpt-5.4-mini",
    input="Summarize this note in Chinese.",
)

print(response.output_text)

Endpoints

POST /v1/responses for the primary OpenAI-compatible responses API.
POST /v1/chat/completions for legacy chat completion clients.
GET /v1/models for available models, capabilities, and pricing metadata.
POST /v1/files and GET /v1/files/:id for supported file inputs.

Tools and modalities

Realrouter forwards the tools parameter only for tool types it can translate into OpenAI-compatible request and streaming shapes. Unknown or unsupported tool types return 400 with unsupported_tool.

Vision input and PDF input_file are supported input modalities, not tools. PDF uploads use purpose=user_data, are limited to 25 MB per file, and each response request can include up to 50 MB of inline or referenced file content.

Tool type

Status

Notes

web_search

Supported

Also accepts web_search_preview. Streaming emits web search in-progress and completed events on /v1/responses.

image_generation

Supported

Also accepts image_generation_call. Generated images are stored in Realrouter blob storage and returned as signed URLs. Not enabled for gpt-5.3-codex-spark.

function

Supported

Custom function calling. Realrouter forwards declarations and returns function calls, but your client executes tools and sends results in the next request.

file_search

Not supported yet

Requests with this tool return an unsupported_tool error. PDF/file input is supported separately as input_file.

code_interpreter

Not supported yet

Requests with this tool return an unsupported_tool error.

computer_use

Not supported yet

Requests with this tool return an unsupported_tool error.

mcp

Not supported yet

Requests with this tool return an unsupported_tool error.

Web search

web-search.ts

const response = await client.responses.create({
  model: "gpt-5.3-codex-spark",
  input: "Search the web and summarize today's top AI platform news.",
  tools: [{ type: "web_search" }],
});

Function calling

Function calling is stateless. Realrouter returns function_call items or chat tool_calls; your app runs the function and sends the result back with the relevant conversation context.

function-calling.ts

const first = await client.responses.create({
  model: "gpt-5.5",
  input: "What is the weather in Toronto?",
  tools: [{
    type: "function",
    name: "get_weather",
    description: "Get current weather for a city.",
    parameters: {
      type: "object",
      properties: { city: { type: "string" } },
      required: ["city"],
      additionalProperties: false,
    },
  }],
  tool_choice: { type: "function", name: "get_weather" },
});

const call = first.output.find((item) => item.type === "function_call");
const toolResult = await getWeather(JSON.parse(call.arguments));

const final = await client.responses.create({
  model: "gpt-5.5",
  input: [
    { role: "user", content: "What is the weather in Toronto?" },
    call,
    { type: "function_call_output", call_id: call.call_id, output: JSON.stringify(toolResult) },
  ],
  tools: first.tools,
});

PDF and file input

upload-pdf.sh

curl https://api.realrouter.org/v1/files \
  -H "Authorization: Bearer $REALROUTER_API_KEY" \
  -F purpose=user_data \
  -F file=@document.pdf

pdf-input.ts

const response = await client.responses.create({
  model: "gpt-5.4-mini",
  input: [{
    role: "user",
    content: [
      { type: "input_file", file_id: "file-..." },
      { type: "input_text", text: "Summarize this PDF." },
    ],
  }],
});

Image generation

image-generation.ts

const response = await client.responses.create({
  model: "gpt-5.4-mini",
  input: "Generate a small product icon for a code API gateway.",
  tools: [{ type: "image_generation" }],
});

Billing model

Realrouter uses account balance. API calls debit token usage after successful completion, and checkout packs add balance through Stripe. Dashboard endpoints will expose balance, transactions, and usage summaries.

Website deployment

The website is a client-side Next.js App Router project configured for static export. It can be hosted independently later, or served by the Rust API server now.

Create API Key View Models