suprsonic

Python SDK for Suprsonic. One API key, dozens of capabilities for your AI agent.

Install

pip install suprsonic

Usage

from suprsonic import Suprsonic

client = Suprsonic("omk_your_key")

# Search the web
result = client.search("latest AI funding rounds")
print(result.data)

# Find a professional email
result = client.emails.find(first_name="Yuma", last_name="Heymans", domain="o-mega.ai")
print(result.data["email"])  # yuma@o-mega.ai

# Scrape a webpage
result = client.scrape("https://example.com")
print(result.data["content"])

# Any capability via .run()
result = client.run("screenshot", url="https://example.com")

Response Format

Every method returns a unified response object:

{
  "success": true,
  "data": {
    "results": [
      { "title": "OpenAI raises $6.6B", "url": "https://...", "snippet": "..." }
    ]
  },
  "error": null,
  "metadata": {
    "provider_used": "serperdev",
    "providers_tried": ["serperdev"],
    "response_time_ms": 1200,
    "request_id": "req_abc123"
  },
  "credits_used": 1
}

On failure, success is false and error contains the details (see below).

Error Handling

from suprsonic import Suprsonic, SuprsonicError

client = Suprsonic("omk_your_key")

try:
    result = client.search("latest AI funding rounds")
    if not result.success:
        # API returned an error response
        print(result.error["detail"])
        if result.error["is_retriable"]:
            # Safe to retry after the suggested delay
            time.sleep(result.error["retry_after_seconds"])
except SuprsonicError as e:
    print(e.status, e.detail)

Error object structure:

{
  "type": "billing_error",
  "title": "Insufficient credits",
  "status": 402,
  "detail": "Your account has 0 credits remaining. Add credits at suprsonic.ai/app/billing.",
  "is_retriable": false,
  "retry_after_seconds": null,
  "error_category": "billing"
}

Error categories: transient (retry safe), permanent (bad request), authentication (invalid key), billing (out of credits).

Agent Framework Examples

LangChain

from langchain.tools import StructuredTool
from suprsonic import Suprsonic

client = Suprsonic("omk_your_key")

search_tool = StructuredTool.from_function(
    func=lambda query: client.search(query).data,
    name="web_search",
    description="Search the web for current information",
)

# Use in any LangChain agent
agent = initialize_agent(tools=[search_tool], llm=llm)

CrewAI

from crewai import Agent, Task, Crew
from crewai.tools import tool
from suprsonic import Suprsonic

client = Suprsonic("omk_your_key")

@tool("Web Search")
def search(query: str) -> dict:
    """Search the web for current information."""
    return client.search(query).data

researcher = Agent(
    role="Research Analyst",
    goal="Find accurate, current information",
    tools=[search],
)

OpenAI Function Calling

Use the /v1/tools endpoint to get Suprsonic capabilities as OpenAI-compatible function definitions:

import requests, openai

tools = requests.get(
    "https://suprsonic.ai/v1/tools",
    headers={"Authorization": "Bearer omk_your_key"},
).json()

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Search for recent SpaceX launches"}],
    tools=tools,
)

All Capabilities

search, scrape, profiles, emails, images, tts, stt, sms, documents, companies, email-verify, transcribe, invoice-parse, subtitle, file-convert, bg-remove, screenshot

Full API reference with all parameters and example responses: suprsonic.ai/apis

Get your API key at suprsonic.ai.