suede-ai

A Suede Labs AI project · Built by Jason Colapietro

Python SDK for Suede Labs AI — x402 pay-per-call music, video, and image generation settled in USDC on Base. The three typed methods below mirror the current public discovery manifest. Legacy convenience helpers remain available for compatible deployments, but they are not current public inventory. No API keys. No subscriptions. Sign an EIP-3009 authorization and call the resource.

The SDK wraps the 402-challenge / sign / retry loop so your agent code spends its time writing creative prompts, not encoding typed data.

Install

pip install suede-ai

Requires Python 3.10+. Pulls in httpx, eth-account, and pydantic.

60-second quickstart

from suede_ai import SuedeClient

# Funded EOA on Base with USDC. Treat this like any other secret.
PRIVATE_KEY = "0x..."

with SuedeClient(wallet_private_key=PRIVATE_KEY) as suede:
    track = suede.create_music(
        prompt="lo-fi rainy afternoon, vinyl crackle, soft piano",
        duration_seconds=30,
    )
    print(track["assetUrl"])  # https://cdn.suedeai.ai/audio/trk_...mp3
    print(track["provenance"])  # {"fingerprint": "0x..."} — on-chain attestation

The first call returns 402 with the x402-v2 challenge. The SDK signs an EIP-3009 transferWithAuthorization for USDC on Base, replays with PAYMENT-SIGNATURE, and returns the JSON body. You never touch the typed data.

Current paid resources

In the public discovery manifest (/.well-known/x402.json) — deliberately scoped to media-generation offerings only:

Prices are enforced server-side and can change. Call suede.manifest() before signing a payment. Older /v1/* helpers remain in the package for clients using compatible deployments; do not treat them as current public Suede inventory.

How payment works

1. Client calls POST /create-music.
2. Server returns 402 Payment Required with a base64 PAYMENT-REQUIRED header and a JSON-body fallback. Its accepts entries declare scheme (exact), network (eip155:8453), asset (USDC on Base), payTo, and atomic amount.
3. SDK builds an EIP-3009 TransferWithAuthorization typed message and signs it with the configured wallet.
4. SDK base64-encodes the full x402-v2 payment payload and replays the original request with the PAYMENT-SIGNATURE header.
5. Suede's facilitator settles on-chain; the response body returns asset URL + on-chain provenance.

You can inspect the live manifest yourself:

curl https://app.suedeai.ai/.well-known/x402.json | jq

Advanced

Reuse an httpx.Client

import httpx
from suede_ai import SuedeClient

http = httpx.Client(http2=True, timeout=120.0)
suede = SuedeClient(wallet_private_key=PRIVATE_KEY, http_client=http)

Direct call to any current resource

result = suede.request("POST", "/agent/image", json={"prompt": "lo-fi rainy afternoon album art"})

Inspect the live manifest

manifest = suede.manifest()  # free — no payment required

Rights and on-chain tools

# Q&A about on-chain rights for a specific asset
answer = suede.chain_chat(
    question="Who owns this track and what licenses are active?",
    asset_hash="0xabc123...",
)

# Analyze what genre/mood a text prompt implies
analysis = suede.prompt_analyze(prompt="dark cinematic orchestral tension build")

Unconfirmed: guitar rig tools

rig_analyze, rig_oracle, and rig_roast are callable client methods, but rig_analyze returned a plain validation error (not a priced 402 challenge) in the last verification pass — these may not be wired to the payment gate on all deployments. Confirm live before relying on them.

# What signal chain is this guitar recording running?
chain = suede.rig_analyze(audio_url="https://cdn.example.com/riff.mp3")

# Recommend a rig for a target tone
rig = suede.rig_oracle(goal="warm blues crunch", genre="blues", budget_usd=1500)

# Roast your pedalboard
roast = suede.rig_roast(goal="tight metal", gear=["Boss DS-1", "Line 6 Spider"])

Roadmap

• Async client (AsyncSuedeClient)
• Pydantic response models per endpoint
• examples/ folder: LangChain tool wrappers, CrewAI tasks, agentcash adapter

License

MIT. See LICENSE.

Built by Jason Colapietro · Suede Labs AI · x402 manifest