Docs

From zero to first routed token in about five minutes

The gateway speaks the OpenAI request shape. If your stack already calls a compatible endpoint, switching is a base URL, a key, and a deploy.

Quickstart

Three steps, one deploy

Sign up, point your client at the gateway, and pass a model id from the catalog. Everything after that is your existing code.

  1. 01

    Create a key

    Sign up, copy your key. It starts with lw-sk-. One key reaches every provider in the catalog.

  2. 02

    Point at the gateway

    Set the base URL to https://api.liquidwhale.com/v1 and swap the key. The request shape is OpenAI-compatible, so nothing else moves.

  3. 03

    Call any model

    Pass the model id from the catalog. If a provider wobbles, the gateway reroutes and reports it in response headers.

Environment

Two exports, any shell. Your SDK picks them up untouched.

env.sh
export OPENAI_BASE_URL="https://api.liquidwhale.com/v1"
export OPENAI_API_KEY="lw-sk-your-key"

First call

The same request in all three flavors, copy button included.

quickstart.curl
curl https://api.liquidwhale.com/v1/chat/completions \
  -H "Authorization: Bearer $LIQUIDWHALE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "helios-5",
    "messages": [
      { "role": "user", "content": "Summarize this changelog in one line." }
    ]
  }'

Compatibility

The shape is open. The exit is one env var

Requests and responses keep the standard chat completion fields, including tool calls, streaming deltas, and structured output. Nothing is proprietary, so pointing the same code somewhere else later is a two line diff. We think that is the only honest way to build infrastructure.

SDKs: python, node, go, and raw curl all work.

migrate.env
# before: a provider endpoint
OPENAI_BASE_URL=https://api.provider.example/v1
OPENAI_API_KEY=sk-...

# after: the Liquid Whale gateway, same shape
OPENAI_BASE_URL=https://api.liquidwhale.com/v1
OPENAI_API_KEY=lw-sk-your-key

Reference / endpoints

The full surface

Eight routes on one base URL. Modality tells you which body shape to send; catalog and usage routes are read-only.

Gateway API endpoints
Method Path Serves Notes Free
POST /v1/chat/completions text Chat and instruction models with streaming, tool calls, and structured output. yes
POST /v1/completions text Legacy text completion shape, kept identical for older stacks. paid
POST /v1/images/generations image Text to image across frontier diffusion models, billed per image. paid
POST /v1/videos/generations video Text to video with shot length and resolution controls, billed per second. paid
POST /v1/audio/transcriptions speech-to-text Audio in, timestamped text out, with automatic language detection. paid
POST /v1/audio/speech text-to-speech Text in, natural audio out, in dozens of voices and languages. paid
GET /v1/models catalog Every routed model with context window, modality, and live price. yes
GET /v1/usage analytics Spend, tokens, and latency per key, model, and day. yes

Routing headers

Debugging is reading a header

Every response reports the region, the provider that served it, how many attempts the router made, and a request id that ties into log search. When something looks off, the trail is already in your logs.

response.headers
# every response carries the routing trail
x-lw-route: fra1
x-lw-provider: solstice
x-lw-attempts: 1
x-lw-request-id: req_9f2c41d8

Reference / errors and limits

Error codes, rate limits, and the failover ladder

What the gateway does on each failure class, which codes retry automatically, and the limits on every tier.

  • Provider returns 429 rate limit

    Retry on the next provider serving the same model class, with jittered backoff.

    x-lw-attempts: 2
  • Provider returns 5xx or times out

    Circuit opens, traffic reroutes instantly, provider is retested in the background.

    x-lw-failover: provider-2
  • Provider degrades above latency budget

    Weighted routing shifts share toward faster healthy providers.

    x-lw-route: eu-fast
  • Model unavailable in a region

    Request lands on the nearest healthy replica that passes eval parity.

    x-lw-region: fra1

Error codes

Code Name Meaning Retry
400 invalid_request_error Malformed body, unknown parameter, or unsupported value. No
401 authentication_error Missing or revoked API key, or wrong key prefix lw-sk-. No
402 insufficient_credits Prepaid balance exhausted. Top up or enable auto recharge. After top-up
404 model_not_found Unknown model id for your key. List /v1/models to verify. No
429 rate_limit_error Key or model concurrency limit hit. The gateway retries upstream for you. Automatic
500 routing_error No healthy provider available for this model right now. Yes, with backoff

Rate limits

Scope Free tier Usage tier
Requests per minute 50 1,000, scaling on request
Concurrent requests 4 200, scaling on request
Free-tier eligible models All flagged rows in the catalog Same, plus everything paid
Monthly free allowance Every eligible model, unlimited days Not applicable
Key payload size 10 MB 50 MB

Docs done, time to call

Your key is one signup away

Create the key, export two variables, and rerun your eval suite against any model on the leaderboard. The free tier is waiting.