Python SDK: suede-ai

suede-ai is the Python client for Suede's x402 endpoints. It reads the 402 challenge, signs the EIP-3009 USDC authorization on Base with your key, and replays the request, so your code sends prompts and gets back a job to collect. Version 0.4.0 was released on PyPI on 2026-08-29 under the MIT license.

Install

pip install suede-ai

Requires Python 3.10 or later. It installs httpx (0.27 or later), eth-account (0.10 or later) and pydantic (2.6 or later).

Generate an image and collect it

import os
import time

import httpx
from suede_ai import SuedeClient

with SuedeClient(wallet_private_key=os.environ["SUEDE_WALLET_KEY"]) as suede:
    job = suede.agent_image(
        prompt="Album cover, neon city at night, rain on glass",
        aspect_ratio="1:1",
        output_format="png",
    )

# A paid call is queued, so the SDK returns the 202 body with a pollUrl.
while True:
    state = httpx.get(job["pollUrl"]).json()
    if state["status"] in ("completed", "failed"):
        break
    time.sleep(5)

print(state.get("imageUrl"))

The key signs real USDC transfers on Base mainnet. Keep it in an environment variable or a secret store, and use a wallet funded with what you plan to spend. The SDK sends PAYMENT-SIGNATURE on the retry, which makes the call asynchronous by default, so every typed method returns a job to poll. Polling is free; the endpoint reference lists each poll route and its finished state.

Client options

ArgumentDefaultUse
wallet_private_keyRequiredHex private key, with or without 0x. Signs the EIP-3009 authorizations.
base_urlhttps://app.suedeai.aiAPI host.
http_clientNoneYour own httpx.Client.
timeout60 s read, 10 s connectPer-request timeout.
max_payment_attempts1Paid retries after a 402: one challenge, one paid retry.

Methods for the live endpoints

MethodCallsBody it sends
create_music(prompt, duration_seconds=30, style=None)POST /create-musicprompt, durationSeconds, style
agent_video(prompt, duration_seconds=8, aspect_ratio=None, resolution=None)POST /agent/videoprompt, durationSeconds, aspectRatio, resolution
agent_image(prompt, aspect_ratio=None, output_format=None)POST /agent/imageprompt, aspectRatio, outputFormat
manifest()GET /.well-known/x402.jsonNone. Free; read prices before you sign.
request(method, path, json=None, params=None)Any pathYour JSON. Handles the 402 the same way.

The typed methods take keyword arguments only. For /create-music fields the typed method does not expose, such as lyrics, custom_mode, make_instrumental, vocal_gender or tags, call request():

job = suede.request("POST", "/create-music", json={
    "prompt": "A melancholic acoustic guitar ballad about rain",
    "make_instrumental": True,
})
# Poll job["pollUrl"] until model_version is no longer "pending".

How the SDK pays

  1. It sends your request with no payment.
  2. On a 402 it reads the PAYMENT-REQUIRED header, falling back to the JSON body.
  3. It picks the accepts entry with scheme exact, network eip155:8453 and the USDC contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.
  4. It signs TransferWithAuthorization for amount to payTo, with a random 32-byte nonce, validAfter 60 seconds in the past and validBefore at now plus the larger of 600 seconds and maxTimeoutSeconds plus 60.
  5. It base64-encodes an x402 version 2 PaymentPayload (x402Version, resource, accepted, extensions, payload) and replays the request with PAYMENT-SIGNATURE.
  6. It returns the JSON of the first response that is not a 402.

The quickstart shows the same exchange with curl, field by field.

Exceptions

ExceptionRaised when
suede_ai.PaymentRequiredThe 402 offers no exact USDC-on-Base entry to sign.
suede_ai.X402ErrorThe response is still 402 after max_payment_attempts paid retries. PaymentRequired is a subclass.
httpx.HTTPStatusErrorAny other non-2xx response, such as a 422 or 429. See the errors page.

Releases

VersionReleased
0.4.02026-08-29
0.3.12026-07-09
0.3.02026-06-17
0.2.02026-06-17
0.1.02026-06-05

The package also ships helpers for older /v1/* routes, such as extend, cover and stems_pro. Those routes are not in the live x402 manifest; the three typed methods above cover the current catalog.

Sources