Account & security
Account settings store your username and password. Supesonic does not use email for account recovery — store your credentials safely. Changing your password requires the current password and confirmation of the new one.
Supesonic / Developers
Build your next connection.
From the first key to every request after it.
Build with clarity.
Your request ID connects usage, cost and support.
Get started
Your first request.
Create a scoped API key, add credit and connect to the API origin. Choose a published model and set an explicit output limit.
- Create an API key
Select models, expiry and a spend limit.
- Fund the wallet
Available credit covers the maximum request reservation.
- Make a request
Keep the secret in your server environment.
Base
https://api.supesonic.com/v1REST + SSE. A published model is needed to generate live examples. These examples display raw SSE events. Your application must parse the protocol's completion and usage events before considering the request complete.
Playground & studio
Try it before you integrate.
Connect your Supesonic API key in Playground. Its existing model, provider, protocol, budget and network restrictions remain in force. The key stays in browser memory until disconnect or page reload. Requests go directly to the inference API.
GET /v1/playground/catalog lists permitted choices. POST /v1/playground/quote estimates the reservation without paid inference. Receipts are isolated to the exact API key. Interrupted requests are never automatically sent again.
Access control · Per key
One key. Your rules.
Create a separate key for each model, app or team. Pick allowed models, approved providers, protocols, IP/CIDR networks, expiry, budget and request limits. The same controls apply to project keys.
Check access sends no paid inference. /v1/models lists models currently available under that key's model, provider, protocol and price restrictions. Pause stops new calls; rotation replaces the secret immediately while keeping the same usage and budget. Update your application after rotating.
| Error | Meaning |
|---|---|
| 401 invalid_api_key | Invalid, paused, expired or revoked key. |
| 403 model_not_allowed / operation_not_allowed | Model or protocol is outside the key scope. |
| 403 key_ip_denied / key_price_limit | Egress IP or customer tariff violates the key rule. No source call is sent. |
| 503 no_selected_provider | No healthy stable source remains in the selected pool. Broaden it or wait; no charge. |
01 / API reference
The protocol stays familiar.
Access follows the current model catalog and the models allowed on your key. A compatible endpoint is available only when an enabled source supports it.
| Method | Endpoint | Output limit |
|---|---|---|
| GET | /v1/models | — |
| POST | /v1/chat/completions | max_tokens |
| POST | /v1/tasks | max_tokens |
| POST | /v1/messages | max_tokens |
| POST | /v1/responses | max_output_tokens |
| POST | /v1/images/generations | max_tokens |
| POST | {model}/v1beta/models/:generateContent | generationConfig.maxOutputTokens |
| POST | {model}/v1beta/models/:streamGenerateContent?alt=sse | generationConfig.maxOutputTokens |
This matrix lists configured protocol access, not proof that every advanced feature was tested. Text and client-executed function calls are accepted by the relay; tool behavior still depends on the selected source. Files, stored Responses, media inputs and provider-hosted tools are unavailable in the current text catalog.
02 / Streaming
From first content to the last event.
Send inference directly to the API origin. Response bytes are streamed over the same connection with backpressure. HTTP headers or SSE keepalive comments do not count as first content.
Each complete SSE frame is checked before forwarding. The first model label must match the explicit route contract. A mismatch stops delivery and quarantines the route. Labels alone do not prove model authenticity.
Admission→First content→Usage + completion
Handle text and function deltas, observe the protocol's final event, and close the connection to cancel. An interrupted or incomplete response can retain a review hold until its usage is resolved.
03 / Billing
A hold, then measured usage.
Before dispatch, the relay reserves a conservative maximum based on the model input cap and requested output cap. The request keeps an immutable price snapshot. Valid reported usage sets the final charge and releases unused credit.
- Completed responses with no useful output, reasoning-only responses and rejected model contracts incur no customer charge.
- Input, output, cache reads and cache writes keep separate units.
- Missing usage is marked for review; it is never silently priced as zero.
- Request logs retain usage and timing, not your prompt or response content.
04 / Capacity
Limits keep the queue short.
- RPM
- New requests per rolling minute.
- TPM
- A conservative token bucket, when configured: input cap plus requested output is admitted against a per-key and provider budget. Unused capacity is refilled over time, not refunded per response.
- Concurrency
- Active requests across all relay instances, per key and provider.
- Deadline
- The request budget includes admission and source processing. A separate first-content deadline detects silent streams.
Capacity is checked before a source call starts. Read the Retry-After header on admission rejections. Increasing a key limit cannot increase the upstream provider's real capacity.
05 / Recovery
Retry with context.
| Code | Guidance |
|---|---|
| 401 / 403 | Check the key, session or model permission. |
| 402 | The available credit or key budget is insufficient. |
| 409 | This idempotency key already identifies a request; no new source call was sent. |
| 502 · model contract | The source model label was missing or mismatched. The route is quarantined and the customer is not charged. If streaming already began, the connection ends before the offending frame. |
| 429 | Admission or rate limit. Inspect the scope and Retry-After header. |
| 503 / 504 | Source, capacity or deadline failure. Inspect the request record before retrying. |
A timeout after dispatch can still involve paid generation. There is no blind POST replay. Reusing the same idempotency key prevents a duplicate source call; it does not replay the original response.
Platform
Developer Library
Field articles live in the Developer Library. Below are console-oriented notes.
Wallet, packages & invoices
Every request reserves a maximum amount, then settles reported input, output and cache usage against an immutable price snapshot. Credit is added after a verified payment notification, never from a browser success message.
Suppliers & earnings
Supply accounts use API credentials or a provider-authorized OAuth application. Accounts are reviewed and initially disabled for routing. An operator verifies the model contract before activation. Pausing or revoking a source stops new routing.
Asynchronous media tasks
Available task models appear after an operator verifies a fixed-price source contract. POST /v1/tasks accepts model, prompt and published parameters. Send an Idempotency-Key for each logical task. A successful create returns HTTP 202 and a task ID.
Support
Need help?
Open a ticket from your workspace after sign in. Include a request ID for usage or connection issues. Never include your API secret.