Assisters Python SDK

Official Python SDK for the Assisters AI API.

Install

Not published yet. pip install assisters fails — this package is not on PyPI. Until it ships, use the OpenAI SDK against our base URL, which the API is compatible with:

pip install openai

from openai import OpenAI
client = OpenAI(api_key=os.environ["ASSISTERS_API_KEY"],
                base_url="https://api.assisters.dev/v1")

The rest of this README describes this package's own interface, for when it is released. See the SDK docs.

pip install assisters

Requires Python 3.9+. Depends on httpx.

Quickstart

from assisters import Assisters

client = Assisters(api_key="sk-...")  # base_url defaults to https://api.assisters.dev/v1

resp = client.chat.completions.create(
    model="assisters-chat-v1",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp["choices"][0]["message"]["content"])

Authentication uses Authorization: Bearer <api_key>.

API

# Chat (non-streaming)
client.chat.completions.create(model="assisters-chat-v1", messages=[...])

# Chat (streaming)
for chunk in client.chat.completions.create(
    model="assisters-chat-v1", messages=[...], stream=True
):
    print(chunk["choices"][0]["delta"].get("content", ""), end="")

# Embeddings
client.embeddings.create(model="assisters-embed-v1", input=["hello", "world"])

# Moderation
client.moderations.create(input="some text")

# Rerank
client.rerank(model="assisters-rerank-v1", query="q", documents=["a", "b"])

# Models
client.models.list()

# Image generation
client.images.generations.create(
    model="assisters-image-v1", prompt="a green robot", size="1024x1024"
)

# Audio transcription
with open("audio.webm", "rb") as f:
    client.audio.transcriptions.create(file=f, model="assisters-stt-v1")

# Text-to-speech -> raw audio bytes
audio = client.audio.speech.create(
    model="assisters-tts-v1", input="Hello there", voice="nova", response_format="mp3"
)

# Audio enhancement -> enhanced audio bytes
with open("noisy.wav", "rb") as f:
    enhanced = client.audio.enhance(file=f, model="assisters-voice-enhance")

# Translation
client.translate(text="Hello", target_language="Spanish")

# Agent (Max tier) — synchronous run
client.agent.run(query="Research the latest on X", mode="research")

# Agent — streaming events (SSE)
for event in client.agent.stream(query="Research X", mode="research"):
    print(event)

# Rate limit
client.get_rate_limit()

# One model, with its pricing and limits
client.models.retrieve("assisters-chat-v1")

Removed: client.keys.* and client.webhooks.* were here. Both call /api/keys and /api/webhooks, which authenticate with a signed-in browser session rather than a Bearer key — so every call returned 401 for a client built with an API key, as this one is. Manage keys and webhooks in the dashboard.

Errors

Every failure raises AssistersAPIError (.status, .message, .type), or one of its subclasses so you can branch on the cause:

from assisters import Assisters, AssistersAPIError, AuthError, NotFoundError, RateLimitError

try:
    client.chat.completions.create(model="assisters-chat-v1", messages=[...])
except RateLimitError as e:
    ...          # 429 — rate limited, or the wallet is empty
except AuthError as e:
    ...          # 401/403 — key missing, invalid or revoked
except NotFoundError as e:
    ...          # 404 — no such model
except AssistersAPIError as e:
    print(e.status, e.type, e.message)

Transport failures raise AssistersAPIError with status=0 and type="network_error".