API Reference

Base URLs, authentication, headers, endpoint families, and response conventions for the R9S gateway API.

The R9S gateway API is exposed through an OpenAI-compatible base URL:

https://gw.r9s.ai/v1

Current referenced API version: 0.2.1.

Authentication

Use bearer token authentication for all model API requests:

Authorization: Bearer <R9S_API_KEY>

Runtime API keys should be stored on the server side. Do not expose them in browser code, mobile app bundles, public repositories, or analytics events.

Standard headers

Send JSON requests with these headers:

Authorization: Bearer <R9S_API_KEY>
Content-Type: application/json
Accept: application/json

For application attribution, include:

HTTP-Referer: https://example.com
X-Title: Example App

Endpoint families

Endpoint Method Purpose
/models GET List available models
/models/{model} GET Retrieve model metadata
/chat/completions POST Create OpenAI-compatible chat completions
/responses POST Create Responses API requests
/messages POST Create Anthropic-compatible Claude messages
/completions POST Create legacy text completions
/edits POST Create text edits
/images/generations POST Generate images
/images/edits POST Edit or extend images
/embeddings POST Create embeddings
/engines/{model}/embeddings POST Create embeddings with an engine-style path
/moderations POST Moderate text input
/audio/speech POST Convert text to speech
/audio/transcriptions POST Transcribe audio
/audio/translations POST Translate audio to English
/search POST Execute web search through a configured search engine
/nextrouter/proxy/{channelid}/{target} POST Proxy a request to a specific channel and target path

Request example

curl https://gw.r9s.ai/v1/chat/completions \
  -H "Authorization: Bearer $R9S_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ]
  }'

Response shape

Inference endpoints return the response shape expected by the compatible API family. For example, chat completions return choices, model details, and usage fields when the upstream model reports usage.

Streaming

Endpoints that support streaming use the request field:

{
  "stream": true
}

Streaming is recommended for interactive chat, coding, and agent experiences. Do not enable streaming when using request options that require non-streaming responses, such as logprobs on chat completions.

Error handling

Handle these classes explicitly:

Status Typical cause Client behavior
400 Invalid payload, unsupported parameter, context limit Fix request shape
401 Missing or invalid API key Re-authenticate or rotate key
403 Model, organization, or scope not allowed Check account access
404 Unknown endpoint or model path Confirm endpoint and model ID
429 Rate limit or quota pressure Retry with backoff or reduce concurrency
5xx Transient gateway or upstream provider error Retry with jitter and inspect logs

For production services, log the HTTP status, request ID, model name, endpoint, and retry count.