Aethex Python SDK
Build voice agents on Aethex — from Python.
Speech models, infrastructure, and orchestration, on us. Create governed voice agents,
place calls, synthesize speech, transcribe recordings, and run realtime voice workflows.
Documentation · Dashboard · API Reference · Discord · Support
| 🎙️ Voice agents | 🗣️ Text-to-speech | ✍️ Transcription | ⚡ Realtime |
|---|---|---|---|
| Governed agents & outbound calls | Stream or batch to WAV / PCM | Async jobs & presigned uploads | Full-duplex WebRTC conversations |
Install
pip install aethexai
Optional extras:
pip install "aethexai[realtime]" # WebRTC conversations (Conversation class)
pip install "aethexai[audio]" # audio format conversion for transcription (PyAV)
The [audio] extra installs av (PyAV) for client-side audio conversion in the
sync transcription paths: with it, any input (mp3, m4a, stereo or 48kHz WAV, etc.)
is normalized to canonical 24kHz mono 16-bit WAV before being split into ≤30s
chunks; without it those paths handle WAV only and send non-canonical input as-is.
The [realtime] extra installs aiortc and av (PyAV). PyAV ships prebuilt
binary wheels (with FFmpeg bundled) for manylinux (glibc) Linux, macOS, and
Windows on Python 3.10–3.13, so a normal install needs no system FFmpeg. You
only need system FFmpeg if PyAV has to build from source (e.g. an unusual
platform/arch, or Alpine/musl — the pinned PyAV 14.x has no musllinux wheel):
on Debian/Ubuntu apt install libavformat-dev libavfilter-dev libavdevice-dev;
on macOS the pinned PyAV (14.x) targets FFmpeg 7, so install brew install ffmpeg@7 (plain brew install ffmpeg now gives FFmpeg 8, which this PyAV
release does not compile against).
Requires Python 3.10+.
Quickstart
Create an agent for a customer operations workflow and place an outbound call.
from aethexai import AethexAI
client = AethexAI(api_key="ae_live_...") # or set AETHEX_API_KEY
voices = client.list_voices(language="french", limit=5)
voice = voices[0]
agent = client.create_agent(
name="Customer Operations Assistant",
system_prompt=(
"You are a professional customer operations assistant. "
"Help callers confirm appointments, answer policy questions, "
"and escalate to a human when required."
),
first_message="Bonjour, comment puis-je vous aider?",
voice_id=voice.id,
language="french",
dialect_style="local",
)
call = client.trigger_call(
agent_id=agent.id,
to_number="+221700000000",
from_number="+221700000000",
)
print(call.id, call.status)
Clients
The SDK exposes two main clients.
| Client | Use it for |
|---|---|
AethexAI |
API-key authenticated platform operations: agents, calls, TTS, transcription jobs, conversations, phone numbers, SIP trunks, Twilio accounts, usage, uploads, and API keys. |
Kora |
Focused voice-agent workflows: agents, outbound calls, voices, TTS, transcription, and conversation history. |
DeveloperClient |
JWT-authenticated developer account and billing operations. |
Async code uses AsyncAethexAI, which mirrors the sync client method-for-method.
import asyncio
from aethexai import AsyncAethexAI
async def main() -> None:
async with AsyncAethexAI(api_key="ae_live_...") as client:
voices = await client.list_voices(language="english")
print([voice.id for voice in voices])
asyncio.run(main())
Core Workflows
Text to speech
Generate a complete audio asset for IVR, onboarding, or customer support:
audio = client.synthesize_speech(
text="Your appointment has been confirmed for tomorrow at 10 AM.",
voice_id="fatima",
language="english",
)
with open("appointment-confirmation.wav", "wb") as f:
f.write(audio)
Stream audio chunks for low-latency playback:
for chunk in client.stream_speech(
text="I am checking your account now. Please hold for a moment.",
voice_id="fatima",
language="english",
):
speaker.write(chunk) # PCM16 audio chunks
Transcription
For file transcription workflows, use Kora.
from aethexai import Kora
kora = Kora("https://api.aethexai.com", "ae_live_...")
with open("call.wav", "rb") as f:
result = kora.transcribe(
f,
language="french",
file_name="call.wav",
mime_type="audio/wav",
)
print(result.text)
Submit longer recordings as asynchronous transcription jobs:
import time
from aethexai import Kora
kora = Kora("https://api.aethexai.com", "ae_live_...")
with open("long-call.wav", "rb") as f:
job = kora.transcribe_async(
f,
language="french",
file_name="long-call.wav",
mime_type="audio/wav",
)
while True:
job = kora.get_transcribe_job(job.id)
if job.status in ("completed", "failed"):
break
time.sleep(2)
print(job.text)
Realtime conversations
Install the realtime extra for full-duplex WebRTC conversations.
pip install "aethexai[realtime]"
import asyncio
from aethexai import AsyncAethexAI
from aethexai.realtime import Conversation, ConversationCallbacks
async def main() -> None:
client = AsyncAethexAI(api_key="ae_live_...")
conversation = Conversation(
client,
agent_id="agent-uuid",
callbacks=ConversationCallbacks(
on_agent_text=lambda text: print("agent:", text),
on_user_transcript=lambda text: print("user:", text),
),
)
await conversation.start()
# Audio flows over WebRTC until you end the session.
await conversation.end()
await client.close()
asyncio.run(main())
Platform Coverage
AethexAI uses a flat method surface: one method per endpoint, no nested
namespaces. This keeps platform automation explicit and easy to audit.
| Area | Methods |
|---|---|
| Agents | create_agent, list_agents, get_agent, update_agent, delete_agent, duplicate_agent |
| Tools | add_agent_tool, list_agent_tools, update_agent_tool, delete_agent_tool |
| Knowledge base | upload_knowledge_doc, upload_knowledge_doc_by_upload, list_knowledge_docs, query_knowledge_base |
| Calls | trigger_call, batch_calls, list_calls, get_call, get_call_status |
| TTS | synthesize_speech, stream_speech, batch_synthesize, get_tts_batch |
| Transcription | transcribe_audio, transcribe_audio_async, get_transcription_job, cancel_transcription_job |
| Conversations | list_conversations, get_conversation, get_transcript, stream_audio, submit_feedback |
| Phone and SIP | list_phone_numbers, register_twilio_phone_number, register_sip_phone_number, list_sip_trunks |
| Twilio accounts | register_twilio_account, list_twilio_accounts, get_twilio_account, release_twilio_account |
| Usage | get_usage, get_usage_summary |
| API keys | list_api_keys, create_api_key, rotate_api_key, revoke_api_key |
See the API reference for request and response fields.
Developer Account and Billing
Billing and account endpoints require a developer JWT from the dashboard auth
flow, not an API key. Use DeveloperClient for those calls.
from aethexai import DeveloperClient
developer = DeveloperClient(
access_token="eyJhbGciOi...",
refresh_token="eyJhbGciOi...", # optional; enables one retry after refresh
)
balance = developer.get_balance()
plans = developer.list_plans()
DeveloperClient reads AETHEX_DEVELOPER_ACCESS_TOKEN and
AETHEX_DEVELOPER_REFRESH_TOKEN when tokens are not passed explicitly.
Configuration
from aethexai import AethexAI
client = AethexAI(
api_key="ae_live_...",
base_url="https://api.aethexai.com",
timeout=30.0,
max_retries=2,
)
| Parameter | Default | Description |
|---|---|---|
api_key |
$AETHEX_API_KEY |
API key sent as X-API-Key. |
base_url |
https://api.aethexai.com |
AethexAI API base URL. |
timeout |
30.0 |
Per-request timeout in seconds. |
max_retries |
2 |
HTTP transport retries for retryable failures. |
httpx_client |
None |
Optional custom httpx.Client or httpx.AsyncClient. |
Environment variables
The SDK reads configuration from environment variables — export them in your shell (or pass the values directly to the client):
export AETHEX_API_KEY=ae_live_... # or ae_test_...
| Variable | Used by | Notes |
|---|---|---|
AETHEX_API_KEY |
AethexAI, Kora |
Required unless you pass api_key=. |
AETHEX_BASE_URL |
example scripts | Optional base-URL override. |
AETHEX_DEVELOPER_ACCESS_TOKEN |
DeveloperClient |
JWT for account/billing. |
AETHEX_DEVELOPER_REFRESH_TOKEN |
DeveloperClient |
Optional; enables token refresh. |
See examples/README.md for the variables used by the
example scripts.
Errors
Non-2xx responses raise typed exceptions. Transport failures are mapped to SDK errors, so production callers can centralize retry, alerting, and escalation logic.
from aethexai import (
AethexAI,
AethexError,
AuthenticationError,
NotFoundError,
RateLimitError,
ValidationError,
)
client = AethexAI(api_key="ae_live_...")
try:
agent = client.get_agent("00000000-0000-0000-0000-000000000000")
except NotFoundError:
print("Agent not found")
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after}s")
except AuthenticationError:
print("Invalid API key")
except ValidationError as e:
print(f"Request rejected: {e.response}")
except AethexError as e:
print(f"SDK error: {e}")
| Status | Exception |
|---|---|
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 422 | ValidationError |
| 429 | RateLimitError |
| 5xx | InternalServerError |
| Network failure | APIConnectionError |
| Timeout | APITimeoutError |
Development
The generated REST client lives under src/aethexai/_generated/ and is built
from openapi.json. The maintained SDK surface lives in:
src/aethexai/client.pysrc/aethexai/_async_client.pysrc/aethexai/kora.pysrc/aethexai/realtime/
Run the local checks:
uv run pytest
uv run ruff check .
uv run ruff format --check src/ tests/ examples/
uv run mypy src/aethexai
See CONTRIBUTING.md for the full development workflow.
Questions about the SDK can be sent to developers@aethexai.com.
Community
- GitHub: github.com/aethexai
- X: @aethexailabs
- LinkedIn: AethexAI
- Discord: discord.gg/ccyuJNZm7x
License
Released under the MIT License.
Metadata
Release files for aethexai 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aethexai-1.0.2.tar.gz | 169.5 kB | With provenance | Details for aethexai-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aethexai-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for aethexai-1.0.2-py3-none-any.whl |
Total release size: 514.9 kB
Release files / aethexai-1.0.2.tar.gz
| Download URL | aethexai-1.0.2.tar.gz |
|---|---|
| Size | 169.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4c967daa8aa97cc733f04d98c8b04dadf06bd8bce0ac272b66294f666a401e57
|
|
BLAKE2b-256 checksum How to use checksums |
02ce2f8d28989f10b1f9b4a76b73f511f4dfcfcbc4b0642ad7654360e5cbe3d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 25, 2026.
Transparency logRelease files / aethexai-1.0.2-py3-none-any.whl
| Download URL | aethexai-1.0.2-py3-none-any.whl |
|---|---|
| Size | 345.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2214109c226e43f3fefb9506431be5d8260b3d2c7c0c5b9c0c930c10cfd459d2
|
|
BLAKE2b-256 checksum How to use checksums |
e657c480ec05c2567b1ca3a27f4b335b7fbc26d64f8f6020268794e785b3c2ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 25, 2026.
Transparency logSecurity for aethexai 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for aethexai-1.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.