Integrate Suprsonic in five minutes.

1. Quick start

Install the SDK in your language of choice.

npm install suprsonic
# or
pnpm add suprsonic

pip install suprsonic

Then make your first call.

import { Suprsonic } from "suprsonic";

const sonic = new Suprsonic({ apiKey: process.env.SUPRSONIC_API_KEY! });

const result = await sonic.web.search({ query: "agent infrastructure" });
console.log(result.results);

from suprsonic import Suprsonic

sonic = Suprsonic(api_key="sk_live_...")

result = sonic.web.search(query="agent infrastructure")
print(result.results)

2. Authentication

Every request uses the same Bearer token. Issue keys per environment in the Suprsonic dashboard at /app/keys. Keys are 36 characters, prefixed with sk_live_ or sk_test_.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Request shape

Every Suprsonic capability speaks JSON in and JSON out, on the same envelope.

{
  "request_id": "req_01HXAB...",
  "credits_used": 2,
  "data": { "...capability specific..." }
}

4. Errors

Errors return a 4xx or 5xx with a typed body. The SDK throws a SuprsonicError you can catch.

{
  "error": {
    "type": "rate_limited",
    "message": "Too many requests for this key. Retry in 1.4s.",
    "request_id": "req_01HXAB12...",
    "retry_after_ms": 1400
  }
}

• invalid_request validation issue
• unauthenticated missing or invalid API key
• rate_limited too many requests for this key
• capability_unavailable upstream temporarily unavailable
• insufficient_credits not enough credits in the billing period

5. Webhooks

For long-running capabilities (video generation, browser automation, slide decks), Suprsonic delivers an event when the work is finished.

POST https://your-app.com/webhooks/suprsonic
Content-Type: application/json
Suprsonic-Signature: t=1715000000,v1=4f...

{
  "id": "evt_01HXAB...",
  "type": "video.generate.completed",
  "data": {
    "request_id": "req_01HXAA...",
    "url": "https://cdn.suprsonic.ai/video/...mp4",
    "credits_used": 80
  }
}

6. Capability reference

The full catalog lives in /capabilities. Below is a compact index, grouped by category.

7. Limits and credits

One credit pool covers every capability. Credits reset on the first of each billing period. Rate limits scale with plan: Free is 60 requests / minute, Developer is 600, Scale is 6,000, and Enterprise is custom.