SparkBright LLM Gateway

1. Overview & authentication

Base URL: https://llmproxy.api.sparkbright.me. Every request (except GET /health and the docs pages) authenticates with a SparkBright app key:

Authorization: Bearer <your-app-key>

The app key controls rate limits and which providers the app may call. Provider API keys are held by the gateway and injected server-side — clients never send upstream provider keys. An app restricted by allowedProviders gets 403 for any other provider.

endpoints POST /v1/chat/completions · GET /v1/models[?provider=] · GET /v1/models/pricing[?provider=] · GET /v1/providers · ANY /native/{provider}/{path...} · GET /health · GET / · GET /docs

2. Standard API — POST /v1/chat/completions

An OpenAI-shaped chat endpoint that works identically across providers. Pick the provider and model per request; the gateway renames the token param, clamps temperature, and drops unsupported params for you (see the parameter matrix).

Request body

{
  "provider": "openai",           // required — a provider id (see table below)
  "model": "gpt-5.5",          // required — a model id for that provider
  "messages": [                   // required — OpenAI chat messages
    { "role": "system", "content": "You are concise." },
    { "role": "user", "content": "Hello" }
  ],
  "temperature": 0.7,             // standard params, top-level (OpenAI style)
  "max_tokens": 1024,
  "stream": false,
  "conversationId": "optional-id",// server-side 90-min history merge (non-stream)
  "standardFormat": true          // default true; false returns provider-raw body
}

Params may be sent top-level (OpenAI style) or inside a legacy options{} object, in camelCase or snake_case; top-level wins. Recognized standard params: max_tokens, temperature, top_p, top_k, stop, seed, presence_penalty, frequency_penalty, response_format, tools, tool_choice, parallel_tool_calls, reasoning_effort, n, user.

Response (non-stream)

{
  "success": true,
  "provider": "openai",
  "model": "gpt-5.5",
  "response": { /* OpenAI chat.completion shape (normalized) */
    "choices": [{ "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" }]
  },
  "usage": { "prompt_tokens": 12, "completion_tokens": 34, "total_tokens": 46 },
  "conversationId": "conv-...",
  "metadata": {
    "requestId": "req-...",
    "timestamp": "2026-07-12T00:00:00.000Z",
    "rateLimitRemaining": 58,
    "dropped_params": ["top_k"]   // params silently dropped for this provider
  }
}

response is always normalized to the OpenAI chat.completion shape when standardFormat is true (the default). Set standardFormat: false to receive the provider's raw body instead. Inspect metadata.dropped_params to see exactly what the gateway removed.

curl

curl -sS https://llmproxy.api.sparkbright.me/v1/chat/completions \
  -H "Authorization: Bearer $SB_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-5.5",
    "messages": [{ "role": "user", "content": "Hello" }],
    "max_tokens": 256
  }'

JavaScript (fetch)

const res = await fetch("https://llmproxy.api.sparkbright.me/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SB_APP_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    provider: "anthropic",
    model: "claude-sonnet-5",
    messages: [{ role: "user", content: "Hello" }],
    max_tokens: 256,
  }),
});
const data = await res.json();
console.log(data.response.choices[0].message.content);

Streaming

Set "stream": true to receive Server-Sent Events. The gateway pipes the upstream SSE straight through in OpenAI delta shape (Anthropic's typed stream is translated to the same shape). Streamed responses have no JSON wrapper and skip the conversation cache.

curl -N https://llmproxy.api.sparkbright.me/v1/chat/completions \
  -H "Authorization: Bearer $SB_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "groq", "model": "openai/gpt-oss-120b",
        "messages": [{ "role": "user", "content": "Count to 3" }], "stream": true }'
# data: {"choices":[{"delta":{"content":"1"}}]}
# data: {"choices":[{"delta":{"content":"2"}}]}
# ...
# data: [DONE]

conversationId

Supply a conversationId on a non-stream request and the gateway merges prior turns from a 90-minute server-side cache, appends the new turn, and stores the assistant reply. To keep multi-turn history you must supply the same id from the first request onward. Omitted on streams.

Swapping providers & models

The request shape is identical across providers — change provider and model and nothing else. Because token-param renaming, temperature clamping, and unsupported-param dropping are handled per provider, the same body is portable. Use GET /v1/models?provider=<id> to discover live model ids, and each provider's default/cheap ids (below) as safe starting points.

Model cost — GET /v1/models/pricing

Same auth, query, and envelope as /v1/models, with a per-model pricing object (USD per 1,000,000 tokens) and a provider-level cost summary attached. Alias: /v1/models/cost. Each provider carries a cost_source: api (pricing read live from the provider — OpenRouter, Together, SambaNova), static (published rates the gateway maintains), or none (no per-token cost — Ollama is local/self-hosted, Featherless is a flat subscription). Models with no known price (e.g. openrouter/auto) return pricing:null with a cost_reason.

curl -sS https://llmproxy.api.sparkbright.me/v1/models/pricing?provider=anthropic   -H "Authorization: Bearer <app-key>"

{ "provider": "anthropic", "cost_source": "static", "cost_available": true,
  "unit": "usd_per_1m_tokens", "currency": "USD",
  "models": [ { "id": "claude-sonnet-5",
    "pricing": { "input": 3, "output": 15, "source": "static", "unit": "usd_per_1m_tokens" } } ] }

3. Native passthrough — ANY /native/{provider}/{path...}

Forward a request verbatim to a provider's own API. The gateway does no body parsing, no param validation, and no transformation — it injects provider auth (and required headers such as anthropic-version), forwards method, query, and body, and streams the response back with the provider's own status and content type. Use this to reach provider-specific features the standard route doesn't model.

The path after /native/{provider} is appended to that provider's native root:

Example: POST /native/anthropic/v1/messages reaches https://api.anthropic.com/v1/messages with x-api-key + anthropic-version injected.

4. Parameter matrix

Each cell shows two things: the native param name / range (top, grey) to use for a native passthrough call, and how the standard route maps that param for the provider (bottom; red = dropped). Table scrolls horizontally; the param column is pinned.

"passed w/ stream_options" means the gateway adds stream_options:{include_usage:true} on streams. "may 400" on a native cell means passthrough forwards the param but the provider itself may reject it.

5. Per-provider notes

OpenRouter free models

OpenRouter (provider: "openrouter") fronts hundreds of upstreams and exposes a pool of free models. Params unsupported by the chosen upstream are silently dropped, not errored.

• List free models: GET https://llmproxy.api.sparkbright.me/v1/models?provider=openrouter (or OpenRouter's own GET /models), then keep entries whose pricing.prompt == "0" and pricing.completion == "0" (they are strings). Free ids carry a :free suffix.
• Invoke a specific free model: pass the full id including the suffix, e.g. "model": "meta-llama/llama-3.3-70b-instruct:free". The suffix is mandatory to force the free tier.
• Fallback array: send a top-level models array of ids tried in order — { "model": "a:free", "models": ["a:free", "b:free"] } (forwarded because OpenRouter allows extra params).
• Auto router: "model": "openrouter/auto" lets OpenRouter pick a model for the prompt.
• Rate limits (free tier): 20 requests/min; 50 requests/day shared across all free models by default; a one-time $10 credit purchase raises the daily cap to 1000/day. Exceeding returns HTTP 429.

6. Error contract

When a provider returns a non-2xx response, the gateway returns the same HTTP status and preserves the provider's own error body verbatim:

{
  "success": false,
  "error": {
    "type": "provider_error",
    "provider": "openai",
    "status": 400,
    "message": "<best short message>",
    "provider_error": { /* the provider's raw JSON body, verbatim (or raw text) */ },
    "request_id": "req-..."
  }
}

On the native route the provider's response is passed through untouched (status, content-type, body). Mid-stream provider errors are piped through unchanged. Gateway-side problems use standard 4xx types — invalid_request_error, authentication_error, rate_limit_error.

7. Machine-readable registry & notes for AI agents

GET /v1/providers returns the full registry as JSON (secrets excluded): for every provider its protocol, baseUrl, nativeBaseUrl, authStyle, tokenParam, temperature range, supports flags, dropParams, quirks, models (default/cheap/fallback/list), and docs. This is the same data that generates this page.

Recommended agent flow for choosing a model dynamically:

1. Fetch GET /v1/providers once to learn which providers exist, their capabilities, and their default/cheap ids.
2. Filter providers by the capabilities your task needs — e.g. require supports.tools for function calling, supports.response_format for JSON mode, supports.reasoning_effort for reasoning control.
3. Fetch GET /v1/models?provider=<id> for the chosen provider to get live model ids (falls back to the registry's fallback list if the provider has no live list or is unreachable); each response also carries default and cheap for that provider.
4. Call POST /v1/chat/completions with the selected provider + model. Read metadata.dropped_params to confirm which of your params the provider actually honored.
5. On a provider error, inspect error.provider_error (verbatim) and either retry with a fallback model or switch providers.

Prefer each provider's default for quality and cheap for cost/latency. Do not hardcode model ids long-term — resolve them from /v1/models so you follow provider deprecations automatically.