API reference

SuperbAPI API reference

Connect to supported AI models through one OpenAI-compatible base URL and a prepaid wallet. Start with read-only model discovery, then send a chat request using a model available to your key.

Reference reviewed 25 October 2026 against the gateway implementation.

• Authentication
• Quickstart
• Endpoints
• Streaming
• Response headers
• Errors
• Limits & budgets

Authentication

Base URL: https://www.superbapi.com/v1

Every request carries a key in the Authorization header. Generate keys in the workspace — each one can be scoped to a model allowlist, given a monthly budget, and given an expiry date.

Authorization: Bearer sk-sbapi-…

Quickstart

1. Create a key in the workspace and set SUPERBAPI_KEY in your local environment. Keep it server-side.
2. Run read-only discovery below. Choose a text/chat model id for SUPERBAPI_MODEL; do not choose a video model for chat.
3. Run one of the chat examples. A successful generation spends prepaid credit; discovery does not generate content.

1 · Discover models (no generation)

curl https://www.superbapi.com/v1/models \
  -H "Authorization: Bearer $SUPERBAPI_KEY"

Response shape illustration; MODEL_ID_FROM_V1_MODELS is a placeholder, not a callable model or a live availability claim:

{
  "object": "list",
  "data": [
    {
      "id": "MODEL_ID_FROM_V1_MODELS",
      "object": "model",
      "owned_by": "superbapi"
    }
  ]
}

Set SUPERBAPI_MODEL to your chosen id for the SDK examples. In curl, replace MODEL_ID_FROM_V1_MODELS with that exact id.

2 · Send a chat request (billable on success)

curl

curl https://www.superbapi.com/v1/chat/completions \
  -H "Authorization: Bearer $SUPERBAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_V1_MODELS",
    "messages": [{"role": "user", "content": "Say hello in one short sentence."}]
  }'

Python — pip install openai

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SUPERBAPI_KEY"],
    base_url="https://www.superbapi.com/v1",
)

completion = client.chat.completions.create(
    model=os.environ["SUPERBAPI_MODEL"],
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
)
print(completion.choices[0].message.content)

Node — npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SUPERBAPI_KEY,
  baseURL: "https://www.superbapi.com/v1",
});

const completion = await client.chat.completions.create({
  model: process.env.SUPERBAPI_MODEL,
  messages: [{ role: "user", content: "Say hello in one short sentence." }],
});
console.log(completion.choices[0].message.content);

Check advertised prices and capabilities on the models page. Its public catalogue includes comparison-only models that may be unavailable; it is not the same list as authenticated GET /v1/models. Editor and desktop-client setup is covered in the setup guides.

A successful non-streaming response has an assistant message under choices[0].message.content. This is an illustrative shape; ids, text and token counts vary:

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "model": "MODEL_ID_FROM_V1_MODELS",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 3,
    "total_tokens": 15
  }
}

Endpoints

On narrow screens, scroll tables sideways. Keyboard: focus a table or code example and use the arrow keys.

{ "data": { "total_credits": 57.5, "total_usage": 12.34 } }

{ "data": { "label": "production", "usage": 12.34, "limit": 25, "limit_remaining": 12.66, "is_free_tier": false } }

Key provisioning

Minting keys from your own backend — for per-customer keys, or a fresh key per deploy. These are authenticated with a provisioning token (created in the workspace), not with an API key.

{ "name": "customer-4182", "budgetLimit": 25, "allowedModels": ["MODEL_ID_FROM_V1_MODELS"], "routeScope": "text-code" }

Machine-readable: openapi.json · llms.txt · catalog/models.json.

Streaming

Send stream: true and read a standard text/event-stream of chat.completion.chunk objects, terminated by data: [DONE]. The gateway defaults stream_options.include_usage to true, unless the caller overrides it. Upstream usage is optional even when requested. If absent, billing uses a length-based estimate; the gateway does not inject a final usage chunk. SSE responses do not have the completed-cost headers listed below.

# client is the OpenAI() instance from the quickstart above.
stream = client.chat.completions.create(
    model=os.environ["SUPERBAPI_MODEL"],
    messages=[{"role": "user", "content": "Write a haiku about prepaid credit."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    # Some upstreams omit usage; handle it only when present.
    if chunk.usage:
        print("\ntokens:", chunk.usage.total_tokens)

Response headers

These headers have different coverage for JSON chat, video submission and SSE streaming. Account totals are available through GET /v1/credits.

Errors

Gateway-generated /v1 validation and routing errors use the envelope below. Forwarded upstream failures, video-poll responses and provisioning errors can have different shapes; inspect the HTTP status and body before classifying the failure:

{ "error": { "message": "Unknown model 'gpt-9'. Call GET /v1/models for the ids this key can use.", "type": "api_error", "code": null } }

Limits & budgets

Cost calculation illustration, not a quote: if a model cost $1 per million input tokens and $3 per million output tokens, a 1,000-input / 500-output request would cost (1,000 ÷ 1,000,000 × $1) + (500 ÷ 1,000,000 × $3) = $0.0025. These hypothetical rates are not SuperbAPI prices. Check the models page for the selected model; cache, reasoning and video pricing can differ.

• Prepaid, not postpaid. Calls draw down a balance you topped up; there is no invoice to be surprised by. Credit is valid for 12 months.
• Per-key budget. Requests are checked against the configured cap and can return 402. Read reported remaining budget from GET /v1/key and review actual usage in the workspace. Do not assume a budget is an atomic reservation for concurrent requests.
• Per-key model allowlist. A key outside its allowlist is refused with 403 before any upstream is called, so it cannot spend.
• Failover. When an upstream errors the gateway retries another that serves the same model. You see one request; the retry is not billed twice.

FAQ

Which SDK do I use with SuperbAPI?

The official OpenAI SDK for your language. SuperbAPI is OpenAI-compatible, so you only change the base URL to https://www.superbapi.com/v1 and pass a SuperbAPI key — no SuperbAPI-specific SDK to install.

How do I know what a call cost?

Successful non-streaming chat responses include x-superbapi-cost-usd, x-superbapi-total-tokens and x-superbapi-served-model. Video submits include cost and served-model headers, not token totals. SSE streams do not include these completed-cost headers. GET /v1/credits returns account totals; the workspace shows request usage.

Am I charged when a request fails?

A chat request rejected before any upstream succeeds is not charged. An interrupted SSE stream can still be billed for reported or estimated partial usage. A video render that fails after a successful submit is refunded when a poll observes the failed status; inspect the refund field and workspace usage.

Does SuperbAPI support streaming?

Yes. Send stream: true to POST /v1/chat/completions for a standard SSE stream. The gateway requests upstream usage by default, but a caller can override stream_options.include_usage. Some upstreams omit usage even when requested. When usage is absent, billing uses a length-based estimate; no final usage chunk is synthesized.

SuperbAPI is an independent aggregator and is not affiliated with, endorsed by, or partnered with any model owner. Third-party product names are used nominatively to describe compatibility and routing. Model availability and pricing change over time; use authenticated discovery for configured ids and the models page for advertised rates and capability details. Neither is an uptime guarantee.