API Documentation

NeoRouter provides an OpenAI-compatible API. Change your base_url and api_key — everything else works as-is.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer ocr_your_api_key_here

Get your API key from the dashboard after signing up.

Chat Completions

POST /v1/chat/completions

Request

{
  "model": "auto",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Write a Python function to sort a list."}
  ],
  "stream": true,
  "temperature": 0.7
}

Set model to "auto" for intelligent routing, or specify a model directly.

Response (Streaming)

Server-Sent Events (SSE) format, compatible with OpenAI SDK:

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"Hello"},"index":0}]}

data: [DONE]

Response Headers

Header	Description
X-NeoRouter-Model	Actual model used
X-NeoRouter-Task	Classified task type
X-NeoRouter-Difficulty	Classified difficulty level
X-NeoRouter-Cost	Estimated cost ($)

Model Overrides

Include these tags in your message to force a specific model:

Tag	Effect
@opus or @think	Force Claude Opus (most capable)
@gemini or @research	Force Gemini Pro
@codex or @terminal	Force O4 Mini
@cheap or @fast	Force cheapest model

Supported Content Types

• Text messages
• Images (base64 or URL — sent as image_url content parts)
• PDFs (base64 — auto-extracted)
• Excel/CSV files (base64 — auto-parsed)
• Audio files (base64)

Rate Limits & Errors

Code	Meaning
401	Missing or invalid API key
402	Insufficient credits — add more at /billing
403	Account deactivated
429	Rate limit exceeded — retry after a moment
500	All providers failed

SDK Examples

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://your-neorouter-url/v1",
    api_key="ocr_your_key_here"
)

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)

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

Node.js

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://your-neorouter-url/v1',
  apiKey: 'ocr_your_key_here'
});

const stream = await client.chat.completions.create({
  model: 'auto',
  messages: [{ role: 'user', content: 'Hello!' }],
  stream: true
});

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

curl

curl https://your-neorouter-url/v1/chat/completions \
  -H "Authorization: Bearer ocr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}],"stream":true}'

Claude Code

Add to ~/.claude/settings.json:

{
  "apiProvider": "custom",
  "customApiUrl": "https://your-neorouter-url",
  "customApiKey": "ocr_your_key_here"
}

Available Models

See the full model list at /models.

GET /v1/models — OpenAI-compatible model listing