kallme-relay // documentation

# Quickstart & Environment Setup

Connect external client tools (like Claude Code, curl, Python SDKs, or custom web clients) directly to the relay.

cURL Verification (OpenAI Format) HTTP /v1

Test connectivity directly against the public relay gateway:

bash // curl

curl -X POST https://kallme-relay.lol/relay/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer local-relay" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "hello world"}],
    "stream": false
  }'

cURL Verification (Anthropic Format) POST /v1/messages

The relay natively serves the Anthropic Messages API specification, converting payloads on-the-fly:

bash // curl anthropic

curl -X POST https://kallme-relay.lol/relay/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: local-relay" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Explain quantum superposition in 2 sentences"}]
  }'

# Claude Code & Terminal Workflows

You can route the official Claude Code CLI through kallme-relay to take advantage of pooled banked quotas.

Environment Variables Configuration CLI setup

In PowerShell or Bash, configure the base URL to route traffic into the relay:

PowerShell

$env:ANTHROPIC_BASE_URL = "https://kallme-relay.lol/relay"
$env:ANTHROPIC_API_KEY  = "local-relay"

# Optional: specify model override
claude --model claude-sonnet-4-5

Bash / Zsh

export ANTHROPIC_BASE_URL="https://kallme-relay.lol/relay"
export ANTHROPIC_API_KEY="local-relay"

claude --model claude-sonnet-4-5

# Architecture & Key Rotation

How the relay abstracts multiple upstream pools into a single resilient endpoint.

Core Relay Mechanisms

1. Stateless Protocol Adapter: Automatically bridges /v1/messages and /v1/chat/completions formats, including bidirectional SSE event streams (content_block_delta, message_delta).

2. Key Bank & Auto-Rotation: Requests cycle through active upstream accounts. On HTTP 429 (rate limit) or 403 (depleted quota), the dead key is quarantined and the request transparently retries on the next candidate with zero client disruption.

3. Pre-Auth Hold Management: Upstream services often pre-authorize holds based on max_tokens (sometimes exceeding balance limits). The relay automatically caps requested output tokens to guarantee holds succeed while maintaining seamless chunked generation.

# Endpoints Reference

All routes exposed by the Nginx reverse proxy on kallme-relay.lol.

Method	Route	Protocol	Description
POST	`/relay/v1/chat/completions`	OpenAI	Main chat endpoint with SSE streaming & tool calling support.
POST	`/relay/v1/messages`	Anthropic	Direct Anthropic API compatibility for Claude Code, Cursor, and SDKs.
GET	`/relay/v1/models`	Catalog	Returns list of 158+ live aggregated models and their availability.
POST	`/huijv/v1/chat/completions`	OpenAI	Huijv upstream pool for specialized frontier checkpoints (Astra, Sol, Luna).
GET	`/health`	Status	Relay heartbeat check and pool readiness indicator.

# Popular Models & Intelligent Fallbacks

The relay routes across 158+ models. If an upstream model is unavailable, the fallback hierarchy takes over automatically.

Frontier Model Tiers Tiered fallback

Identifier	Provider	Characteristics
`claude-opus-4-7`	Anthropic	High-precision reasoning, robust balance hold fitting.
`claude-sonnet-4-5`	Anthropic	Default generalist model for coding and agentic loops.
`gpt-6-astra`	Huijv / OpenAI	Experimental next-gen architecture, fast reasoning token stream.
`gpt-5.6-luna`	Huijv / OpenAI	Optimized for long-context creative synthesis and low latency.
`gemini-3.8-flash`	Google	Ultra-fast, high-throughput context window processing.

# Reasoning & Thought Streaming

Many models emit private scratchpads wrapped inside reasoning tags.

<thought_process> Pipeline

When reasoning models generate thinking steps, the relay extracts or streams them within an isolated thought collapsible block in the UI. In raw API streams, this appears as dedicated reasoning deltas or parsed XML blocks so that programmatic consumers can filter them cleanly.

# Troubleshooting & FAQ

HTTP 403: Hold Amount Exceeded

Cause: Upstream tries to pre-authorize estimated turn cost (prompt_tokens + max_tokens) against a sub-$1 balance hold.

Resolution: Lower max_tokens to 4096 or less in your client, or let the relay automatically apply the AIROUTER_RELAY_MAX_TOKENS_CAP clamp.

Claude Temperature Sensitivity

Certain Claude versions reject explicit temperature: 1.0 or non-default values when combined with reasoning features. The relay includes internal filters that automatically strip incompatible temperature headers before upstream dispatch.