synapsai 0.3.0

Official Python SDK for the SynapsAI Truth-as-a-Service API

synapsai

Official Python SDK for the SynapsAI Truth-as-a-Service (TaaS) API.

Install

pip install synapsai

Requires Python 3.9+. Runtime dependency: httpx only.

Quickstart

from synapsai import SynapsAI

client = SynapsAI(api_key="taas_your_key")
# or set SYNAPSAI_API_KEY env var and call SynapsAI() with no arguments

Get your API key at synapsai.org/api-access.

---

Verification

Image verification

Detects AI-generated images, deepfakes, and edits using Hive AI, ELA, EXIF, and Claude Vision. Result committed on-chain.

from pathlib import Path
from synapsai import SynapsAI

client = SynapsAI(api_key="taas_your_key")

result = client.verify.image(
    image=Path("photo.jpg"),
    claim="Product photo from supplier",
)

print(result.verdict)            # 'AUTHENTIC'
print(result.authenticity_score) # 91  (0-100 integer)
print(result.raw_scores.hive_ai_generated)  # 0.02
print(result.tx_hash)            # on-chain proof

raw_scores exposes every signal so you can apply your own thresholds:

# Insurance (conservative)
if result.raw_scores.hive_ai_generated > 0.99:
    flag_for_review()

# News (liberal)
if result.raw_scores.hive_ai_generated > 0.70:
    flag_for_review()

Claim verification (text)

# Submit (returns immediately — verification is async)
claim = client.verify.claim("Company X reduced CO2 by 500 tons in 2025.")
print(claim.claim_id)  # 94
print(claim.poll)      # '/v1/verify/94'

# Poll until verified
import time

def wait_for_verification(claim_id, max_wait=60):
    start = time.time()
    while time.time() - start < max_wait:
        status = client.verify.get(claim_id)
        if status.status != "pending":
            return status
        time.sleep(3)
    raise TimeoutError("Verification timed out")

status = wait_for_verification(claim.claim_id)
print(status.verified)  # True

Document verification

result = client.verify.document(document=Path("claim.pdf"))
print(result.verdict)
print(result.checks)                     # [DocumentCheck(name=..., passed=..., detail=...)]
print(result.ai_detection.is_ai_generated)  # False

Luxury goods authentication

result = client.verify.luxury(
    images=[Path("front.jpg"), Path("serial.jpg")],
    brand="Rolex",
    model="Submariner",
)

print(result.verdict)     # 'AUTHENTIC'
print(result.confidence)  # 92
print(result.indicators)  # VisualAuthIndicators(authentic=[...], suspicious=[])

Other visual authentication endpoints

All accept image: Path | bytes | BinaryIO or a list of those.

client.verify.rx(images=img, drug_name="Advil")
client.verify.credential(images=img, credential_type="degree")
client.verify.art(images=img, artist="Monet")
client.verify.sneakers(images=img, brand="Nike")
client.verify.cards(images=img, card_type="Pokemon")
client.verify.wine(images=img, producer="Château Pétrus")
client.verify.ticket(images=img, event="Super Bowl LX")
client.verify.jewelry(images=img, metal="gold")
client.verify.electronics(images=img, brand="Apple")

---

Trust Scores

trust = client.trust.get("0xWalletAddress")
print(trust.trust_score)      # 590  (neutral=500, range 0-1000)
print(trust.interpretation)   # 'trusted'

# Batch
scores = client.trust.batch(["0xAddr1", "0xAddr2"])

---

Webhooks

# Register
wh = client.webhooks.create(
    url="https://your-server.com/hooks/synapsai",
    events=["verification.completed"],
)
# Store wh.secret securely — shown once
print(wh.id)      # 'wh_abc123'
print(wh.secret)  # 'whsec_...'

# Verify incoming events (Flask example)
import os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/synapsai")
def handle_webhook():
    valid = client.webhooks.verify_signature(
        payload=request.get_data(),        # raw bytes — do NOT parse first
        signature=request.headers["X-SynapsAI-Signature"],
        secret=os.environ["SYNAPSAI_WEBHOOK_SECRET"],
    )
    if not valid:
        abort(401)
    event = request.get_json()
    # handle event...
    return "", 200

# List / manage
webhooks = client.webhooks.list()
client.webhooks.test("wh_abc123")
client.webhooks.delete("wh_abc123")

---

Account

info = client.account.key_info()
print(info.plan)     # 'growth'
print(info.company)  # 'Acme Insurance'

usage = client.account.usage()
print(usage.total_calls)  # 42

from datetime import datetime, timezone

page = client.account.history(
    type="image",
    limit=50,
    from_=datetime(2026, 5, 1, tzinfo=timezone.utc),
)
print(page.total)
print(page.verifications[0].verdict)

---

Async client

import asyncio
from synapsai import AsyncSynapsAI

async def main():
    async with AsyncSynapsAI(api_key="taas_your_key") as client:
        result = await client.verify.image(image=Path("photo.jpg"))
        print(result.verdict)

asyncio.run(main())

---

Error handling

from synapsai import (
    SynapsAIError,
    AuthError,
    RateLimitError,
    ValidationError,
    NotFoundError,
    ServerError,
)

try:
    result = client.verify.image(image=Path("photo.jpg"))
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after_ms}ms")
except ValidationError as e:
    print(f"Bad input: {e.message}")
except ServerError:
    print("Server error — retries exhausted")

5xx errors are retried automatically up to max_retries times (default 3) with exponential backoff. Set max_retries=0 to disable.

---

Environment variable

export SYNAPSAI_API_KEY=taas_your_key

client = SynapsAI()  # picks up SYNAPSAI_API_KEY automatically

---

Configuration

client = SynapsAI(
    api_key="taas_...",          # or SYNAPSAI_API_KEY env var
    base_url="https://api.synapsai.org",  # optional override
    max_retries=3,               # default 3
    timeout=30.0,                # seconds, default 30
)