Suprsonic is a unified API for AI agents. Instead of integrating dozens of providers for search, scraping, enrichment, image generation, transcription, messaging, and more, you add one API key and get all of them.
Every capability uses the same authentication, the same response format, and the same credit system. If a provider fails, Suprsonic automatically falls back to the next one. You don't manage retries, credentials, or individual provider accounts.
Available as a REST API, Python SDK, TypeScript SDK, and MCP server. Use whichever fits your stack.
Step 1: Get your API key
Create a key in the API Keys tab. It starts with omk_ and works across every capability.
Step 2: Make your first call
pip install suprsonic
from suprsonic import Suprsonic
client = Suprsonic("omk_your_key")
result = client.search("latest AI funding rounds")
print(result.data)npm install suprsonic
import { Suprsonic } from "suprsonic";
const client = new Suprsonic("omk_your_key");
const result = await client.search("latest AI funding rounds");
console.log(result.data);{
"suprsonic": {
"command": "npx",
"args": ["-y", "suprsonic-mcp"],
"env": { "SUPRSONIC_API_KEY": "omk_your_key" }
}
}curl -X POST https://suprsonic.ai/v1/search \
-H "Authorization: Bearer omk_your_key" \
-H "Content-Type: application/json" \
-d '{"query": "latest AI funding rounds", "mode": "ai"}'All four methods hit the same API, use the same key, and deduct from the same credit balance.
All unified agent APIs use Bearer token authentication. Include your API key in the Authorization header of every request.
Authorization: Bearer omk_your_key_hereAPI keys are created in the API Keys section. Each key works across all capabilities and is tied to your account and credit balance. Keys can be revoked at any time.
Rate limits
Default: 60 requests per minute per key. Rate limit headers are included in every response:
X-RateLimit-Remaining: 58
X-RateLimit-Limit: 60
X-RateLimit-Reset: 1713400060
X-Credits-Used: 2Each capability costs a fixed number of credits per successful call. Failed requests are free. Capabilities with modes let you choose the cost/quality tradeoff.
/v1/search
AI: 2SERP: 1Deep: 3Search the web with SERP, AI synthesis, or both
/v1/scrape
Fast: 1Standard: 2Thorough: 5Extract content from any URL as Markdown or HTML
/v1/profiles/find
3 creditsFind and enrich professional profiles
/v1/emails/find
2 creditsFind professional email addresses
/v1/emails/verify
1 creditCheck if an email is deliverable, catch-all, or disposable
/v1/companies/find
3 creditsEnrich company data by domain
/v1/images/generate
3 creditsGenerate images from text prompts
/v1/images/remove-background
2 creditsRemove background from any image
/v1/screenshots/capture
1 creditCapture a rendered screenshot of any webpage
/v1/speech/synthesize
2 creditsConvert text to speech audio
/v1/speech/transcribe
2 creditsTranscribe audio to text with timestamps
/v1/audio/transcribe
3 creditsTranscribe audio with speaker diarization and timestamps
/v1/subtitles/generate
2 creditsGenerate SRT/VTT subtitles from audio or video
/v1/documents/extract
3 creditsExtract structured data from URLs or content
/v1/invoices/parse
3 creditsExtract structured data from invoices and receipts
/v1/files/convert
2 creditsConvert files between 200+ formats
/v1/messages/send
1 creditSend SMS or WhatsApp messages
The Agent API (/v1/agent) costs the same as whichever capability it routes to. Credits are returned in the credits_used field and the X-Credits-Used response header.
All errors follow RFC 7807 (Problem Details for HTTP APIs) with additional fields for agent consumption.
{
"success": false,
"error": {
"type": "https://api.o-mega.ai/errors/rate-limited",
"title": "Rate limit exceeded",
"status": 429,
"detail": "You have exceeded 60 requests per minute",
"is_retriable": true,
"retry_after_seconds": 42,
"alternative_action": "Reduce request frequency or contact support",
"error_category": "transient"
},
"credits_used": 0
}Error categories
Temporary issue. Safe to retry after retry_after_seconds.
Request is invalid. Do not retry with the same parameters.
API key is missing, invalid, or revoked.
Insufficient credits. Upgrade plan or enable overage.
The target content could not be accessed (blocked, CAPTCHA, etc).
HTTP status codes
Success. The request completed and data is in the response.
Bad request. Missing or invalid parameters.
Unauthorized. API key is missing or invalid.
Insufficient credits. Upgrade or enable overage.
Unprocessable. The request was valid but the operation failed (e.g. scrape blocked).
Rate limited. Retry after the specified interval.
Provider error. All upstream providers failed.
Every response uses the same format, regardless of which capability or provider handled the request. This makes it easy for agents to parse responses uniformly.
{
"success": boolean,
"data": { ... } | null,
"error": { ... } | null,
"metadata": {
"provider_used": "string | null",
"providers_tried": ["string"],
"mode_used": "string | null",
"response_time_ms": number,
"request_id": "string"
},
"credits_used": number
}Metadata fields
provider_used
string
Which provider's data was used in the final response. 'merged' if data came from multiple providers.
providers_tried
string[]
All providers that were attempted in the waterfall, in order.
mode_used
string
The mode that was applied (e.g. 'ai', 'standard').
response_time_ms
number
Total wall-clock time for the request in milliseconds.
request_id
string
Unique request identifier for debugging and support.
Every package uses the same API key and hits the same backend. Pick whichever fits your stack.
MCP Server
Npx suprsonic-mcpWorks with Claude Desktop, Cursor, VS Code, ChatGPT. Your agent gets every capability as MCP tools.
Python SDK
Pip install suprsonicFor LangChain, CrewAI, OpenAI Agents SDK, Claude API, or any Python agent.
TypeScript SDK
Npm install suprsonicFor Vercel AI SDK, LangChain.js, Node.js agents, or any TypeScript project.
REST API
Curl with Bearer tokenWorks with any language or framework. The SDKs are thin wrappers around this.
Machine-readable formats
For auto-generating clients or configuring agent frameworks:
OpenAPI spec
/v1/openapi.jsonFiltered OpenAPI 3.1 spec with only Suprsonic capabilities.
Tool definitions
/v1/tools?format=openaiPre-built tool schemas for OpenAI, Claude, and MCP. Formats: openai, claude, mcp, raw.
llms.txt
/llms.txtAI-readable documentation index for agent discovery.
Suprsonic provides machine-readable tool definitions that any AI agent framework can consume directly. One tool definition gives your agent access to all capabilities. No manual configuration needed.
Tool definition endpoint
Fetch a ready-to-use tool definition, auto-generated from the API schema. No auth required. Choose the format that matches your agent framework.
OpenAI-compatible function calling schema
Anthropic-compatible tool use schema
Model Context Protocol schema (for MCP clients)
Full JSON with per-capability parameter schemas, types, defaults, and descriptions
How it works
Your agent or AI coder fetches the tool definition once, registers it, and routes tool calls to POST /v1/agent. The tool definition contains all parameter names, types, required/optional markers, defaults, and descriptions. No hardcoding needed.
# 1. Fetch the tool definition (pick your format)
GET https://suprsonic.ai/v1/tools?format=openai
# 2. Register it as a tool in your agent framework
# The response is a complete tool schema. Pass it directly.
# 3. When the agent calls the tool, forward to /v1/agent
POST https://suprsonic.ai/v1/agent
Authorization: Bearer omk_your_key_here
Content-Type: application/json
{"capability": "search", "params": {"query": "..."}}The tool definition updates automatically when capabilities are added or parameters change. Fetch it at startup or cache it.
Other discovery endpoints
OpenAPI spec
/v1/openapi.jsonFiltered OpenAPI 3.1 spec for auto-generating typed clients in any language.
llms.txt
/llms.txtAI-readable documentation index for coding agents and RAG pipelines.
One endpoint for every capability.
Instead of registering dozens of separate tools, your agent registers one: POST /v1/agent. Specify the capability and parameters, and the system routes internally. Same response format regardless of which capability you call.
POST /v1/agent
{
"capability": "emails",
"params": {
"first_name": "Yuma",
"last_name": "Heymans",
"domain": "o-mega.ai"
}
}Available capabilities
/v1/search
Search the web and get AI-synthesized answers, raw Google SERP results, or both combined, with automatic provider routing.
/v1/scrape
Extract content from any URL with automatic escalation from fast HTTP fetch to JS rendering to stealth browser with CAPTCHA solving.
/v1/profiles/find
Find and enrich professional profiles by LinkedIn URL or name, with waterfall across multiple data providers and merged results.
/v1/emails/find
Find verified professional email addresses by name and company domain, with waterfall across enrichment providers for maximum coverage.
/v1/emails/verify
Check if an email is deliverable, catch-all, or disposable.
/v1/companies/find
Enrich company data by domain with firmographics from Apollo, brand identity from BrandFetch, and qualitative analysis via LLM.
/v1/images/generate
Generate images from text prompts using Google GenAI with automatic fallback to DALL-E, supporting style references and resolution control.
/v1/images/remove-background
Remove background from any image. GPU-powered segmentation.
/v1/screenshots/capture
Capture a rendered screenshot of any webpage.
/v1/speech/synthesize
Convert text to natural speech using Deepgram Aura (105+ voices, 7 languages) as primary provider and ElevenLabs as fallback.
/v1/speech/transcribe
Transcribe pre-recorded audio to text via Deepgram with confidence scores, word-level timing, and multi-language support.
/v1/audio/transcribe
Transcribe audio/video with speaker diarization and timestamps.
/v1/subtitles/generate
Generate SRT/VTT subtitles from audio or video files.
/v1/documents/extract
Extract structured data from any URL or content using LLM-powered analysis with a user-defined schema.
/v1/invoices/parse
Extract structured line items, totals, dates from invoices and receipts.
/v1/files/convert
Convert files between 200+ formats (PDF, DOCX, XLSX, images).
/v1/messages/send
Send SMS or WhatsApp messages to any phone number with automatic channel selection and delivery status tracking.
Python SDK
from suprsonic import Suprsonic
client = Suprsonic("omk_your_key")
# Convenience methods
result = client.search("latest AI news")
result = client.scrape("https://example.com")
result = client.verify_email("john@example.com")
result = client.emails.find(first_name="John", last_name="Doe", domain="example.com")
# Or use .run() for any capability
result = client.run("screenshot", url="https://example.com")TypeScript SDK
import { Suprsonic } from "suprsonic";
const client = new Suprsonic("omk_your_key");
const result = await client.search("latest AI news");
const result = await client.scrape("https://example.com");
const result = await client.verifyEmail("john@example.com");
// Or use .run() for any capability
const result = await client.run("screenshot", { url: "https://example.com" });Search the web and get AI-synthesized answers, raw Google SERP results, or both combined, with automatic provider routing.
Search the web with SERP, AI synthesis, or both
Parameters
query
Requiredstring
The search query. Natural language works best for AI mode, keywords work best for SERP mode.
num_results
number (default: 10)
Maximum number of organic results to return. Only applies to serp and deep modes.
country
string (default: us)
ISO country code for localized results. Affects SERP ranking and content language.
freshness
select (default: any)
Time filter for result recency. Use 'day' for breaking news, 'any' for evergreen research.
Modes
The mode parameter is a preset that configures optimal provider routing for common use cases. You can also set individual parameters directly for fine-grained control.
AI-synthesized answers with inline citations via Perplexity.
Best for research queries that need a coherent answer. Returns a synthesized response with source citations. Response time: 2-4s.
Raw Google SERP results via SerperDev.
Returns links, snippets, knowledge graph, and featured snippets. No AI synthesis. Fastest option at under 1s response time.
SERP results combined with AI synthesis for full coverage.
Gets raw sources plus a synthesized answer. Most comprehensive option, combining both providers. Response time: 3-6s.
Example response
{
"success": true,
"data": {
"answer": "In Q1 2026, AI funding reached $4.2B across 320 deals...",
"citations": [
{ "url": "https://techcrunch.com/...", "title": "AI Funding Report Q1 2026" }
],
"organic_results": [
{ "url": "https://...", "title": "...", "snippet": "...", "position": 1 }
],
"knowledge_graph": null,
"featured_snippet": null
},
"metadata": {
"provider_used": "perplexity",
"providers_tried": ["perplexity"],
"mode_used": "ai",
"response_time_ms": 2340,
"request_id": "req_abc123"
},
"credits_used": 2
}Extract content from any URL with automatic escalation from fast HTTP fetch to JS rendering to stealth browser with CAPTCHA solving.
Extract content from any URL as Markdown or HTML
Parameters
url
Requiredstring
The URL to scrape. Must be a valid HTTP/HTTPS URL. Redirects are followed automatically.
output
select (default: markdown)
Content format for the scraped page. Markdown is optimized for LLM consumption (67% fewer tokens than HTML).
Clean Markdown, optimized for LLMs
Cleaned HTML without head/scripts
Full HTML including head section
wait_for
string
CSS selector to wait for before extracting content. Useful for SPAs that load data dynamically. Only used in standard and thorough modes.
timeout
number (default: 30)
Maximum seconds to wait for the page. Fast mode default: 10s. Standard: 30s. Thorough: 60s.
Modes
The mode parameter is a preset that configures optimal provider routing for common use cases. You can also set individual parameters directly for fine-grained control.
Raw HTTP fetch, no JS rendering. Under 1s.
No JavaScript rendering or proxy. Works for static HTML pages, blogs, and docs. Will fail on SPAs and JS-heavy sites.
Full JS rendering via Firecrawl. Works for 90%+ of sites.
Handles SPAs, dynamic content, and lazy loading. Response time: 2-5s. The recommended default for most use cases.
Stealth browser with proxy and CAPTCHA solving.
Firecrawl with Anchor stealth browser fallback, residential proxy, and CAPTCHA solving. For anti-bot protected sites, login-gated pages, and Cloudflare-defended sites. Response time: 10-30s.
Example response
{
"success": true,
"data": {
"content": "# Pricing\n\n## Starter Plan\n$29/mo\n- 1,000 API calls...",
"title": "Pricing - Example Corp",
"description": "Simple, transparent pricing for teams of all sizes.",
"links": ["https://example.com/signup", "https://example.com/docs"],
"screenshot_url": null
},
"metadata": {
"provider_used": "firecrawl",
"providers_tried": ["firecrawl"],
"mode_used": "standard",
"response_time_ms": 3100,
"request_id": "req_def456"
},
"credits_used": 2
}Find and enrich professional profiles by LinkedIn URL or name, with waterfall across multiple data providers and merged results.
Find and enrich professional profiles
Parameters
linkedin_url
string
Direct LinkedIn profile URL. If provided, skips the search step and goes directly to enrichment. This is the fastest and most accurate path.
first_name
string
Person's first name. Required if linkedin_url is not provided. Used with last_name (and optionally company) to search for the profile.
last_name
string
Person's last name. Required if linkedin_url is not provided.
company
string
Company name to narrow the search. Highly recommended when using name-based lookup to improve match accuracy.
include_image
boolean (default: true)
Whether to fetch and re-host the profile image. Adds an Exa provider call to the waterfall. Images are re-hosted to avoid LinkedIn hotlinking blocks.
Example response
{
"success": true,
"data": {
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"headline": "CTO at Acme Corp",
"company": "Acme Corp",
"title": "CTO",
"location": "San Francisco, CA",
"summary": "Experienced technology leader with 15+ years...",
"experience": [
{ "title": "CTO", "company": "Acme Corp", "period": "2023 - Present" }
],
"education": [],
"skills": ["Python", "Machine Learning", "System Design"],
"profile_image_url": "https://cdn.o-mega.ai/profiles/abc.jpg",
"linkedin_url": "https://linkedin.com/in/johndoe"
},
"metadata": {
"provider_used": "merged",
"providers_tried": ["icypeas", "leadmagic", "exa_image"],
"response_time_ms": 4200,
"request_id": "req_ghi789"
},
"credits_used": 3
}Find verified professional email addresses by name and company domain, with waterfall across enrichment providers for maximum coverage.
Find professional email addresses
Parameters
first_name
Requiredstring
Person's first name.
last_name
Requiredstring
Person's last name.
domain
Requiredstring
Company domain to search.
company
string
Company name (optional). Can improve match accuracy.
Example response
{
"success": true,
"data": {
"email": "john.doe@acme.com",
"email_type": "professional",
"confidence": 0.9,
"verification_status": "verified",
"first_name": "John",
"last_name": "Doe",
"domain": "acme.com"
},
"metadata": {
"provider_used": "icypeas",
"providers_tried": ["icypeas"],
"response_time_ms": 3200,
"request_id": "req_jkl012"
},
"credits_used": 2
}Check if an email is deliverable, catch-all, or disposable.
Check if an email is deliverable, catch-all, or disposable
Parameters
string
Email address to verify.
Example response
{"success":true,"data":{"email":"john@example.com","status":"valid","sub_status":"","is_free_email":false,"smtp_provider":"google","mx_found":"true"},"credits_used":1}Enrich company data by domain with firmographics from Apollo, brand identity from BrandFetch, and qualitative analysis via LLM.
Enrich company data by domain
Parameters
domain
Requiredstring
Company domain to enrich.
company_name
string
Optional company name hint for better matching.
Example response
{
"success": true,
"data": {
"company_name": "Stripe",
"domain": "stripe.com",
"industry": "Financial Technology",
"description": "Stripe is a financial infrastructure platform for businesses...",
"company_size": "5000+",
"headquarters": "San Francisco, CA",
"founded_year": 2010,
"primary_brand_color": "#635BFF",
"secondary_brand_color": "#00D4AA",
"logo_url": "https://asset.brandfetch.io/idxAg10C0L/id3MVUjFuR.png",
"twitter_handle": "@stripe",
"linkedin_handle": "company/stripe",
"website": "https://stripe.com"
},
"metadata": {
"provider_used": "merged",
"providers_tried": ["website_analysis", "brandfetch"],
"response_time_ms": 8400,
"request_id": "req_co_001"
},
"credits_used": 3
}Generate images from text prompts using Google GenAI with automatic fallback to DALL-E, supporting style references and resolution control.
Generate images from text prompts
Parameters
prompt
Requiredstring
Text description of the image to generate.
aspect_ratio
select (default: 1:1)
Aspect ratio for the generated image.
image_size
select (default: 512px)
Resolution. Higher costs more.
reference_image_url
string
URL of a reference image for style transfer.
skip_default_style
boolean (default: false)
Skip default style instructions.
Example response
{
"success": true,
"data": {
"file_id": "68a1b2c3d4e5f6g7h8i9j0k1",
"download_url": "/download_file/68a1b2c3d4e5f6g7h8i9j0k1",
"prompt": "A modern tech company logo with blue gradients",
"aspect_ratio": "1:1",
"image_size": "512px"
},
"metadata": {
"provider_used": "google_genai",
"providers_tried": ["google_genai"],
"response_time_ms": 8500,
"request_id": "req_mno345"
},
"credits_used": 3
}Remove background from any image. GPU-powered segmentation.
Remove background from any image
Parameters
image_url
Requiredstring
URL to the image.
size
select (default: auto)
Output resolution.
Example response
{"success":true,"data":{"image_base64":"iVBORw0KGgo...","format":"png","credits_charged":"1"},"credits_used":2}Capture a rendered screenshot of any webpage.
Capture a rendered screenshot of any webpage
Parameters
url
Requiredstring
URL to capture.
width
number (default: 1280)
Viewport width in pixels.
height
number (default: 720)
Viewport height in pixels.
format
select (default: png)
Output format.
full_page
boolean (default: false)
Capture entire scrollable page.
Example response
{"success":true,"data":{"screenshot_url":"https://renders.urlbox.com/...","render_time_ms":3200,"size_bytes":145023,"format":"png"},"credits_used":1}Convert text to natural speech using Deepgram Aura (105+ voices, 7 languages) as primary provider and ElevenLabs as fallback.
Convert text to speech audio
Parameters
text
Requiredstring
The text to convert to speech (max 2000 characters).
voice_model
string
Deepgram Aura voice model ID. See docs for 105+ options across English, Spanish, French, German, Italian, Dutch, Japanese.
voice_id
string
ElevenLabs voice ID. Use with provider=elevenlabs.
provider
select (default: auto)
Force a specific TTS provider. Default: auto (Deepgram first, ElevenLabs fallback).
Example response
{
"success": true,
"data": {
"audio_base64": "//uQx...(base64 audio data)...",
"format": "mp3",
"sample_rate": 48000,
"text": "Hello, I am your AI assistant.",
"voice_model": "aura-2-thalia-en"
},
"metadata": {
"provider_used": "deepgram",
"providers_tried": ["deepgram"],
"response_time_ms": 850,
"request_id": "req_tts_001"
},
"credits_used": 2
}Transcribe pre-recorded audio to text via Deepgram with confidence scores, word-level timing, and multi-language support.
Transcribe audio to text with timestamps
Parameters
audio_url
string
URL to audio file. Deepgram fetches it directly.
audio_base64
string
Base64-encoded audio data. Use this for local files.
language
string (default: en)
Language code for transcription.
Example response
{
"success": true,
"data": {
"transcript": "Hello, this is a test recording.",
"confidence": 0.98,
"language": "en",
"words": [
{"word": "Hello", "start": 0.0, "end": 0.5, "confidence": 0.99}
],
"duration_seconds": 3.2
},
"metadata": {
"provider_used": "deepgram",
"providers_tried": ["deepgram"],
"response_time_ms": 1200,
"request_id": "req_stt_001"
},
"credits_used": 2
}Transcribe audio/video with speaker diarization and timestamps.
Transcribe audio with speaker diarization and timestamps
Parameters
audio_url
Requiredstring
URL to audio or video file.
language
string (default: en_us)
Language code.
speaker_labels
boolean (default: true)
Enable speaker diarization.
Example response
{"success":true,"data":{"transcript":"Hello, welcome to the meeting...","confidence":0.95,"speaker_count":2,"duration_seconds":120.5},"credits_used":3}Generate SRT/VTT subtitles from audio or video files.
Generate SRT/VTT subtitles from audio or video
Parameters
audio_url
Requiredstring
URL to audio or video file.
language
string (default: en)
Language code.
format
select (default: srt)
Subtitle format.
Example response
{"success":true,"data":{"subtitle_content":"1\n00:00:00,000 --> 00:00:03,500\nHello, welcome.\n","format":"srt","duration_seconds":120.5,"utterance_count":15},"credits_used":2}Extract structured data from any URL or content using LLM-powered analysis with a user-defined schema.
Extract structured data from URLs or content
Parameters
url
string
URL to scrape and extract from. Either url or content is required.
content
string
Pre-scraped text content to extract from. Use this if you already have the content.
extraction_prompt
string
Natural language instructions for what to extract. Either this or schema is required.
schema
string
JSON schema defining the structure to extract. Either this or extraction_prompt is required.
Example response
{
"success": true,
"data": {
"extracted": {
"products": [
{ "name": "Starter", "price": "$29/mo", "features": ["1K API calls", "Email support"] },
{ "name": "Pro", "price": "$99/mo", "features": ["10K API calls", "Priority support"] }
]
},
"source_url": "https://example.com/pricing",
"content_length": 4523,
"truncated": false
},
"metadata": {
"provider_used": "llm_extraction",
"providers_tried": ["llm_extraction"],
"response_time_ms": 5200,
"request_id": "req_doc_001"
},
"credits_used": 3
}Extract structured line items, totals, dates from invoices and receipts.
Extract structured data from invoices and receipts
Parameters
document_url
Requiredstring
URL to invoice/receipt PDF or image.
Example response
{"success":true,"data":{"invoice_number":"INV-001","supplier_name":"Acme Corp","total_amount":299.99,"line_items":[{"description":"Widget","quantity":3,"unit_price":99.99}]},"credits_used":3}Convert files between 200+ formats (PDF, DOCX, XLSX, images).
Convert files between 200+ formats
Parameters
file_url
Requiredstring
URL to the source file.
source_format
Requiredstring
Source file format (e.g. docx, xlsx, html, web).
target_format
string (default: pdf)
Target format.
Example response
{"success":true,"data":{"file_name":"document.pdf","file_size":523672,"file_url":"https://v2.convertapi.com/d/FILEID/document.pdf","conversion_time":2},"credits_used":2}Send SMS or WhatsApp messages to any phone number with automatic channel selection and delivery status tracking.
Send SMS or WhatsApp messages
Parameters
to
Requiredstring
Recipient phone number in E.164 format.
message
Requiredstring
Message text. SMS max 1600 chars, WhatsApp max 4096 chars.
channel
select (default: auto)
Delivery channel. Auto tries WhatsApp first, falls back to SMS.
Example response
{
"success": true,
"data": {
"message_id": "wamid.abc123",
"channel": "whatsapp",
"to": "+1234567890",
"status": "sent"
},
"metadata": {
"provider_used": "whatsapp",
"providers_tried": ["whatsapp"],
"response_time_ms": 890,
"request_id": "req_msg_001"
},
"credits_used": 1
}