SDK Python

SDK Python officiel pour l'API Vocale AI d'AethexAI. Créez et gérez des agents vocaux en production, déclenchez de vrais appels téléphoniques, synthétisez la parole, transcrivez l'audio et lancez des conversations en temps réel depuis Python.

Installation

Le SDK est distribué sous le package aethexai sur PyPI et nécessite Python 3.10+. Installez-le avec pip ou uv en utilisant les commandes ci-dessous. L'extra realtime télécharge également aiortc et PyAV ; PyAV fournit des wheels précompilés pour les plateformes courantes, mais les plateformes moins courantes peuvent nécessiter les headers de développement FFmpeg si PyAV doit être compilé depuis les sources.

bash

pip install aethexai

Configuration rapide

Importez AethexAI et initialisez-le avec votre clé API. Le SDK utilise l'authentification par clé API pour les appels à l'API vocale ; la connexion JWT développeur est uniquement pour l'auth du tableau de bord. Passez api_key explicitement ou définissez AETHEX_API_KEY.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

# Verify the connection by listing available voices.
voices = client.list_voices(limit=5)
for voice in voices:
    print(voice.id, voice.name)

Gestionnaire de contexte

AethexAI et AsyncAethexAI supportent les gestionnaires de contexte pour que les connexions HTTP soient fermées à la sortie du bloc.

python

from aethexai import AethexAI

with AethexAI(api_key="ae_live_...") as client:
    page = client.list_agents(limit=20)
    print(page.data)

Kora

Kora est le client orienté voix : agents, appels sortants, voix, TTS, transcription et historique des conversations sans la surface de gestion de compte. trigger_call nécessite un from_number enregistré sur votre tenant pour les appels sortants — la passerelle rejette un from_number omis avec HTTP 422 (sauf si le serveur définit TWILIO_PHONE_NUMBER comme fallback).

python

from aethexai import Kora

kora = Kora(base_url="https://api.aethexai.com", api_key="ae_live_...")

voices = kora.list_voices(limit=1)
agent = kora.create_agent(
    name="Support Agent",
    system_prompt="You are a helpful customer support agent.",
    first_message="Hi there! How can I help you today?",
    voice_id=voices[0].id,
    language="english",
)

with open("recording.wav", "rb") as f:
    result = kora.transcribe(f.read(), language="english")
print(result.text)

Agents

Créez, listez, récupérez, mettez à jour, dupliquez et supprimez des agents vocaux. Toutes les méthodes create/update acceptent des arguments nommés qui correspondent au corps de la requête API. Les endpoints paginés retournent des objets avec .data, .total, .offset et .limit ; calculez la fin des résultats avec page.offset + len(page.data) >= page.total. Les méthodes d'écriture list_/create_/update_/duplicate_/trigger_call exposent le dictionnaire JSON brut, donc utilisez l'accès par crochets (ex. agent["id"]) ; les lectures de ressource unique comme get_agent et les éléments de list_voices retournent des modèles attrs typés, donc l'accès par attribut fonctionne (agent.id, voice.id).

Lister les agents

Lister tous les agents de votre tenant. Retourne un résultat paginé avec .data, .total, .offset et .limit.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

page = client.list_agents(limit=20, offset=0)
for agent in page.data:
    print(agent.id, agent.name)

Créer un agent

Créer un nouvel agent vocal. Les méthodes d'écriture retournent le dictionnaire JSON sous-jacent — accédez aux champs avec ["id"].

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")
voices = client.list_voices(language="english", limit=1)

agent = client.create_agent(
    name="Support Bot",
    system_prompt="You are a helpful customer support agent.",
    first_message="Hi there! How can I help you today?",
    voice_id=voices[0].id,
    language="english",
)
print(agent.id)

Obtenir un agent

Récupérer un agent par son ID. Retourne un AgentResponse typé — utilisez l'accès par attribut (agent.id, agent.name).

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

agent = client.get_agent("8a1b2c3d-4e5f-6789-abcd-ef0123456789")
print(agent.id, agent.name, agent.voice_id)

Mettre à jour un agent

Mettre à jour un agent existant. Ne passez que les champs que vous souhaitez modifier.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.update_agent(
    "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    name="Updated Support Bot",
    first_message="Welcome back!",
)

Supprimer un agent

Supprimer définitivement un agent par son ID.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.delete_agent("8a1b2c3d-4e5f-6789-abcd-ef0123456789")

Dupliquer un agent

Créer une copie exacte d'un agent existant. Retourne le nouveau dictionnaire agent.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

clone = client.duplicate_agent("8a1b2c3d-4e5f-6789-abcd-ef0123456789")
print(clone.id)

Ajouter un outil d'agent

Attacher un outil de fonction à un agent. parameters est un objet JSON Schema complet envoyé au LLM. endpoint_url est appelé par le pipeline vocal lorsque le LLM invoque l'outil.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

tool = client.add_agent_tool(
    "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    name="lookup_order",
    description="Look up an order by ID",
    parameters={
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
    },
    endpoint_url="https://api.example.com/orders",
)
print(tool["id"])

Lister les outils d'agent

Lister tous les outils attachés à un agent.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

tools = client.list_agent_tools("8a1b2c3d-4e5f-6789-abcd-ef0123456789")
for tool in tools:
    print(tool["id"], tool["name"])

Mettre à jour un outil d'agent

Mettre à jour un outil attaché à un agent. Ne passez que les champs que vous souhaitez modifier.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.update_agent_tool(
    "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "3c2d1e0f-9a8b-7c6d-5e4f-3a2b1c0d9e8f",
    description="Look up an order by its internal ID",
)

Supprimer un outil d'agent

Supprimer un outil d'un agent.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.delete_agent_tool(
    "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "3c2d1e0f-9a8b-7c6d-5e4f-3a2b1c0d9e8f",
)

Téléverser un document de base de connaissances

Téléverser un document directement dans la base de connaissances de l'agent en multipart/form-data.

python

from aethexai import AethexAI
from aethexai._generated.types import File
from aethexai._generated.models import (
    BodyUploadKnowledgeDocApiV1AgentsAgentIdKnowledgeBasePost as UploadBody,
)

client = AethexAI(api_key="ae_live_...")

with open("faq.pdf", "rb") as f:
    body = UploadBody(
        file=File(payload=f, file_name="faq.pdf", mime_type="application/pdf"),
        filename="faq.pdf",
    )
    doc = client.upload_knowledge_doc(
        "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
        body=body,
    )
print(doc["id"])

Téléverser un document via URL présignée

Téléverser un document de base de connaissances via une URL présignée. Appelez presign_upload pour obtenir une URL PUT signée, envoyez les octets du fichier, puis enregistrez l'upload avec cette méthode.

python

from aethexai import AethexAI
import httpx

client = AethexAI(api_key="ae_live_...")

upload = client.presign_upload(kind="doc/knowledge-base", filename="faq.pdf", content_type="application/pdf")
with open("faq.pdf", "rb") as f:
    httpx.request(upload.method, upload.upload_url, content=f.read(),
                  headers=dict(upload.headers.additional_properties)).raise_for_status()

doc = client.upload_knowledge_doc_by_upload(
    "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    upload_id=upload.upload_id,
    filename="faq.pdf",
)
print(doc["id"])

Lister les documents de base de connaissances

Lister tous les documents dans la base de connaissances de l'agent.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

docs = client.list_knowledge_docs("8a1b2c3d-4e5f-6789-abcd-ef0123456789")
for doc in docs:
    print(doc["id"], doc["filename"], doc["status"])

Traiter un document de base de connaissances

Déclencher l'embedding et l'indexation d'un document précédemment téléversé. L'ingestion est asynchrone — query_knowledge_base peut retourner des résultats vides jusqu'à la fin du traitement.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.process_knowledge_doc(
    "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "b3c4d5e6-7f8a-9b0c-1d2e-3f4a5b6c7d8e",
)

Interroger la base de connaissances

Exécuter une requête de récupération hybride sur la base de connaissances de l'agent. Retourne des chunks classés par RRF ; score est la valeur de pertinence utilisée pour le filtrage, pas le score RRF.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

results = client.query_knowledge_base(
    "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    query="What is the refund policy?",
)
for r in results.results:
    print(r.score, r.text)

Obtenir les textes de la base de connaissances

Récupérer le texte extrait pour chaque document de la base de connaissances.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

texts = client.get_knowledge_texts("8a1b2c3d-4e5f-6789-abcd-ef0123456789")
for t in texts["documents"]:
    print(t['text'][:100], t['filename'])

Supprimer un document de base de connaissances

Supprimer un document de la base de connaissances de l'agent.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.delete_knowledge_doc(
    "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "b3c4d5e6-7f8a-9b0c-1d2e-3f4a5b6c7d8e",
)

Appels

Déclenchez des appels sortants et interrogez l'historique des appels. trigger_call passe un vrai appel téléphonique ; le system_prompt et le first_message de l'agent pilotent la conversation à travers le pipeline STT, LLM et TTS. Le from_number doit être enregistré sur votre tenant pour les appels sortants — la passerelle rejette un from_number omis avec HTTP 422 (sauf si le serveur définit TWILIO_PHONE_NUMBER comme fallback). trigger_call et les éléments de list_calls retournent des dictionnaires ; get_call_status retourne un CallStatusResponse typé.

Lister les appels

Lister tous les enregistrements d'appels de votre tenant avec pagination optionnelle.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

page = client.list_calls(limit=10, offset=0)
for call in page.data:
    print(call.id, call.status, call.direction)

Créer un enregistrement d'appel

Créer manuellement un enregistrement d'appel sans déclencher un vrai appel. Utile pour journaliser des appels externes.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

call = client.create_call_record(
    agent_id="8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    direction="inbound",
    from_number="+14155551234",
    to_number="+18005550000",
    metadata={"source": "ivr-callback"},
)
print(call["id"])

Déclencher un appel

Passer un appel téléphonique sortant avec l'agent spécifié. Le from_number doit être enregistré sur votre tenant.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

call = client.trigger_call(
    agent_id="8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    to_number="+14155551234",
    from_number="+18005550000",
    metadata={"customer_id": "cu_42"},
)
print(call["id"], call["status"])

Appels en lot

Déclencher plusieurs appels sortants en une seule requête. Chaque destinataire peut avoir des variables individuelles pour l'interpolation des prompts.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

batch = client.batch_calls(
    agent_id="8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    recipients=[
        {
            "to_number": "+14155551234",
            "from_number": "+18005550000",
            "variables": {"customer_name": "Alice"},
        },
        {
            "to_number": "+14155555678",
            "from_number": "+18005550000",
            "variables": {"customer_name": "Bob"},
        },
    ],
    name="Spring launch",
)
print(batch.batch_id, batch.status, batch.total)

Obtenir un lot d'appels

Récupérer le statut et la progression d'un job d'appels en lot.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

batch = client.get_call_batch("5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b")
print(batch.status, batch.completed, batch.failed, batch.total)

Obtenir un appel

Récupérer un enregistrement d'appel par son ID. Retourne un CallResponse typé.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

call = client.get_call("c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f")
print(call.status, call.duration_seconds)

Obtenir le statut d'un appel

Interroger le statut en direct d'un appel par son ID. Retourne un CallStatusResponse typé.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

status = client.get_call_status("c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f")
print(status.status)

Conversation (WebRTC)

Signalisation WebRTC bas niveau pour les conversations vocales navigateur-agent. Utilisez le SDK Realtime pour une interface de plus haut niveau.

Connexion

Créer une nouvelle session WebRTC. Retourne session_id et la configuration ICE.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

session = client.conversation_connect(agent_id="8a1b2c3d-4e5f-6789-abcd-ef0123456789")
print(session["session_id"], session["ice_config"])

Envoyer une offre

Soumettre le SDP d'offre WebRTC. Retourne le SDP de réponse du serveur.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

answer = client.send_offer(
    "3f2a7b1c-8d4e-4a5b-9c2d-1e0f3a4b5c6d",
    sdp="v=0\r\no=- ...\r\n",
    type="offer",
)
print(answer["sdp"])

Envoyer un candidat ICE

Relayer les candidats ICE au serveur pour compléter la configuration de la connexion pair-à-pair.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.send_ice_candidate(
    "3f2a7b1c-8d4e-4a5b-9c2d-1e0f3a4b5c6d",
    pc_id="3f2a7b1c-8d4e-4a5b-9c2d-1e0f3a4b5c6d",
    candidates=[
        {
            "candidate": "candidate:842163049 1 udp 1677729535 ...",
            "sdp_mid": "0",
            "sdp_mline_index": 0,
        },
    ],
)

Obtenir le statut de la session

Interroger le statut et les métriques d'une session WebRTC active.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

status = client.get_conversation_session_status("3f2a7b1c-8d4e-4a5b-9c2d-1e0f3a4b5c6d")
print(status["status"], status["duration_s"], status["turn_count"])

Terminer la session

Terminer une session de conversation WebRTC active.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.end_conversation_session("3f2a7b1c-8d4e-4a5b-9c2d-1e0f3a4b5c6d")

Envoyer le résultat d'un outil

Retourner le résultat d'un appel d'outil à l'agent pendant une session active.

python

import json
from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.send_tool_result(
    "3f2a7b1c-8d4e-4a5b-9c2d-1e0f3a4b5c6d",
    tool_call_id="call_abc123",
    result=json.dumps({"order_status": "shipped"}),
)

Conversations

Récupérez les enregistrements de conversations, les transcriptions et les enregistrements audio des appels terminés. get_conversation retourne un ConversationResponse typé et get_transcript retourne une liste d'éléments ConversationTurnResponse typés, donc l'accès par attribut fonctionne sur les deux. L'enregistrement téléchargeable se trouve sur Kora sous get_conversation_audio (retourne les octets bruts) ; les méthodes AethexAI équivalentes retournent des URLs signées ou des métadonnées de flux à la place, donc utilisez Kora quand vous voulez les octets du fichier directement.

Lister les conversations

Lister les enregistrements de conversations terminées avec pagination optionnelle.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

page = client.list_conversations(limit=10, offset=0)
for conv in page.data:
    print(conv.id, conv.status, conv.total_duration_ms)

Rechercher des conversations

Recherche plein texte dans les transcriptions de conversations.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

response = client.search_conversations("refund policy", limit=10)
for hit in response["results"]:
    print(hit["conversation_id"], hit["text"])

Obtenir une conversation

Récupérer un enregistrement de conversation. Retourne un ConversationResponse typé.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

conv = client.get_conversation("c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f")
print(conv.id, conv.status, conv.total_duration_ms)

Obtenir la transcription

Récupérer la transcription tour par tour d'une conversation. Retourne une liste d'éléments ConversationTurnResponse typés.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

turns = client.get_transcript("c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f")
for turn in turns:
    print(f"{turn.role}: {turn.text}")

Obtenir l'URL audio

Obtenir une URL signée de courte durée vers l'enregistrement audio de la conversation.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

audio = client.get_audio("c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f")
print(audio["url"], audio["format"], audio["expires_in"])

Obtenir les octets audio

Télécharger l'enregistrement audio de la conversation en octets bruts via le client Kora.

python

from aethexai import Kora

kora = Kora(base_url="https://api.aethexai.com", api_key="ae_live_...")

audio = kora.get_conversation_audio("c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f")
with open("conversation.wav", "wb") as f:
    f.write(audio)

Révoquer le token audio

Révoquer un token de lecture audio précédemment émis pour empêcher tout accès ultérieur.

python

from urllib.parse import urlparse, parse_qs
from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

# Mint a URL, then extract its token to revoke it.
audio = client.get_audio("c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f")
token = parse_qs(urlparse(audio["url"]).query)["token"][0]

client.revoke_audio_token(
    "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    token=token,
)

Soumettre un avis

Attacher une note de qualité et un commentaire optionnel à une conversation.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.submit_feedback(
    "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    rating=5,
    comment="Resolved my issue quickly.",
)

Transcription

Transcrivez des fichiers audio de manière synchrone ou soumettez-les pour un traitement asynchrone. La méthode synchrone bloque jusqu'à ce que le résultat soit prêt. La variante asynchrone retourne un job dont vous pouvez interroger le statut.

Transcrire (synchrone)

Transcrire l'audio de manière synchrone via le client Kora. Bloque jusqu'à ce que le résultat soit prêt.

python

from aethexai import Kora

kora = Kora(base_url="https://api.aethexai.com", api_key="ae_live_...")

with open("recording.wav", "rb") as f:
    result = kora.transcribe(f.read(), language="english")
print(result.text)

Transcrire (asynchrone)

Soumettre l'audio pour une transcription asynchrone. Retourne un ID de job à interroger.

python

from aethexai import Kora

kora = Kora(base_url="https://api.aethexai.com", api_key="ae_live_...")

with open("long_recording.wav", "rb") as f:
    job = kora.transcribe_async(
        f.read(),
        language="english",
        webhook_url="https://example.com/webhooks/transcription",
    )
print(job.id, job.status)

Transcrire via upload

Transcrire de l'audio précédemment téléversé via une URL présignée. Synchrone.

python

from aethexai import AethexAI
import httpx

client = AethexAI(api_key="ae_live_...")

upload = client.presign_upload(kind="audio/transcribe", filename="recording.wav", content_type="audio/wav")
with open("recording.wav", "rb") as f:
    httpx.request(upload.method, upload.upload_url, content=f.read(),
                  headers=dict(upload.headers.additional_properties)).raise_for_status()

result = client.transcribe_audio_by_upload(upload_id=upload.upload_id, language="english")
print(result.text)

Transcrire async via upload

Soumettre un audio téléversé via URL présignée pour une transcription asynchrone avec livraison par webhook.

python

from aethexai import AethexAI
import httpx

client = AethexAI(api_key="ae_live_...")

upload = client.presign_upload(kind="audio/transcribe", filename="long.wav", content_type="audio/wav")
with open("long_recording.wav", "rb") as f:
    httpx.request(upload.method, upload.upload_url, content=f.read(),
                  headers=dict(upload.headers.additional_properties)).raise_for_status()

job = client.transcribe_audio_async_by_upload(
    upload_id=upload.upload_id,
    language="english",
    webhook_url="https://example.com/webhooks/transcription",
)
print(job.id, job.status)

Obtenir un job de transcription

Interroger le statut d'un job de transcription asynchrone. Retourne le résultat quand le statut est completed.

python

from aethexai import Kora

kora = Kora(base_url="https://api.aethexai.com", api_key="ae_live_...")

job = kora.get_transcribe_job("a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16")
print(job.status, job.text if job.status == "completed" else job.error_message)

Annuler un job de transcription

Annuler un job de transcription asynchrone en attente ou en cours.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.cancel_transcription_job("a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16")

Synthèse vocale

Convertissez du texte en parole. synthesize_speech retourne l'audio complet sous forme de WAV complet (header inclus, donc le fichier est lisible tel quel). stream_speech produit des trames PCM mono 16 bits brutes à 24 kHz pour un temps jusqu'au premier octet plus court — enveloppez-les dans un header WAV vous-même, ou redirigez directement vers un lecteur qui consomme du PCM (par exemple, ffplay -f s16le -ar 24000). Gardez les entrées synthesize/stream temps réel à 650 caractères ou moins ; utilisez batch_synthesize pour les scripts longs jusqu'à 3000 caractères par élément.

Synthétiser la parole

Convertir jusqu'à 650 caractères de texte en fichier audio WAV complet. Le header est inclus, donc le fichier est lisible tel quel.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

audio = client.synthesize_speech(
    text="Hello, welcome to AethexAI!",
    language="english",
)
with open("output.wav", "wb") as f:
    f.write(audio)

Streamer la parole

Streamer jusqu'à 650 caractères de parole en chunks PCM mono 16 bits bruts à 24 kHz pour un temps jusqu'au premier octet réduit.

python

import wave
from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

with wave.open("output.wav", "wb") as wav:
    wav.setnchannels(1)
    wav.setsampwidth(2)
    wav.setframerate(24_000)
    for chunk in client.stream_speech(
        text="Streaming hello.",
        language="english",
    ):
        wav.writeframes(chunk)

Synthèse en lot

Soumettre une liste de textes pour une synthèse vocale asynchrone avec livraison par webhook. Chaque élément peut contenir jusqu'à 3000 caractères ; la plateforme découpe les éléments longs en chunks backend sûrs et retourne un WAV par élément.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

batch = client.batch_synthesize(
    language="english",
    items=[
        {"text": "First message."},
        {"text": "Second message."},
    ],
    webhook_url="https://example.com/webhooks/tts",
)
print(batch.batch_id, batch.status, batch.total)

Obtenir un lot TTS

Récupérer le statut et les résultats par élément d'un job de lot TTS.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

batch = client.get_tts_batch("8e7d6c5b-4a3b-2c1d-0e9f-8a7b6c5d4e3f")
print(batch.status, batch.completed, batch.failed, batch.total)
for item in batch.results:
    print(item.index, item.status, item.audio_url)

Voix

Lister et récupérer les voix disponibles. Retourne des objets VoiceResponse typés permettant l'accès par attribut.

Lister les voix

Lister toutes les voix disponibles pour votre tenant avec filtre de langue optionnel et pagination.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

voices = client.list_voices(language="english", limit=20)
for v in voices:
    print(v.id, v.name, v.language)

Obtenir une voix

Récupérer une voix par son ID ou son nom.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")
voices = client.list_voices(language="english", limit=1)

voice = client.get_voice(voices[0].id)
print(voice.id, voice.name, voice.supports_dialect_style)

Prévisualiser une voix

Générer un court clip audio pour prévisualiser une voix. Solution de contournement : utilisez synthesize_speech jusqu'à ce que le bug UTF-8 de preview_voice soit corrigé.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")
voices = client.list_voices(language="english", limit=1)

# Workaround: use synthesize_speech until preview_voice's UTF-8 bug is fixed.
preview = client.synthesize_speech(
    voice_id=voices[0].id,
    text="Welcome to Aethex AI.",
    language="english",
)
with open("preview.wav", "wb") as f:
    f.write(preview)

Numéros de téléphone

Enregistrez, listez et gérez les numéros de téléphone pour les appels entrants et sortants.

Lister les numéros de téléphone

Lister tous les numéros de téléphone enregistrés sur votre tenant.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

page = client.list_phone_numbers(limit=20, offset=0)
for number in page.data:
    print(number["id"], number["phone_number"], number["provider"])

Enregistrer un numéro Twilio

Lier un numéro de téléphone Twilio à un agent pour les appels entrants et sortants.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

number = client.register_twilio_phone_number(
    twilio_account_id="0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    phone_number="+18005550000",
    agent_id="8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    friendly_name="Sales line",
)
print(number["id"])

Enregistrer un numéro SIP

Lier un numéro de téléphone de trunk SIP à un agent.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

number = client.register_sip_phone_number(
    phone_number="+18005550000",
    trunk_id="2a4b6c8d-1e3f-5a7b-9c0d-2e4f6a8b0c1d",
    agent_id="8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    friendly_name="Inbound support",
)
print(number["id"])

Obtenir un numéro de téléphone

Récupérer un enregistrement de numéro de téléphone par son ID.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

number = client.get_phone_number("9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d")
print(number)

Mettre à jour un numéro de téléphone

Mettre à jour l'agent assigné ou la configuration d'un numéro de téléphone enregistré.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.update_phone_number(
    "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    agent_id="8a1b2c3d-4e5f-6789-abcd-ef0123456789",
)

Libérer un numéro de téléphone

Supprimer un numéro de téléphone enregistré de votre tenant.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.release_phone_number("9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d")

Définir le routage d'un numéro

Configurer le routage de secours pour un numéro de téléphone (ex. transfert en cas de non-réponse).

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.set_phone_number_routing(
    "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    fallback_action="forward",
    fallback_number="+18005550000",
    max_ring_seconds=30,
)

Comptes Twilio

Enregistrez et gérez les identifiants Twilio utilisés pour les appels sortants.

Enregistrer un compte Twilio

Connecter un compte Twilio à votre tenant AethexAI en utilisant un Account SID et un Auth Token.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

account = client.register_twilio_account(
    account_sid="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    auth_token="your_twilio_auth_token",
    friendly_name="Production Twilio",
)
print(account.id)

Lister les comptes Twilio

Lister tous les comptes Twilio enregistrés sur votre tenant.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

page = client.list_twilio_accounts(limit=20, offset=0)
for acct in page.data:
    print(acct["id"], acct["friendly_name"])

Obtenir un compte Twilio

Récupérer un enregistrement de compte Twilio par son ID.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

account = client.get_twilio_account("0a1b2c3d-4e5f-6789-abcd-ef0123456789")
print(account)

Libérer un compte Twilio

Déconnecter un compte Twilio de votre tenant.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.release_twilio_account("0a1b2c3d-4e5f-6789-abcd-ef0123456789")

Enregistrements

Lister et télécharger les enregistrements d'appels.

Lister les enregistrements

Lister tous les enregistrements de votre tenant avec pagination optionnelle.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

page = client.list_recordings(limit=10, offset=0)
for rec in page.data:
    print(rec["id"], rec["duration_seconds"])

Obtenir un enregistrement

Récupérer un enregistrement par son ID.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

rec = client.get_recording("5e4f3a2b-1c0d-9e8f-7a6b-5c4d3e2f1a0b")
print(rec)

Obtenir l'audio d'un enregistrement

Obtenir une URL signée vers l'audio de l'enregistrement et le télécharger.

python

import httpx
from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

result = client.get_recording_audio("5e4f3a2b-1c0d-9e8f-7a6b-5c4d3e2f1a0b")
audio = httpx.get(result["url"]).content
with open("recording.wav", "wb") as f:
    f.write(audio)

Supprimer un enregistrement

Supprimer définitivement un enregistrement.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.delete_recording("5e4f3a2b-1c0d-9e8f-7a6b-5c4d3e2f1a0b")

Modèles

Interroger les modèles LLM disponibles pour votre déploiement.

Lister les modèles

Lister tous les modèles avec l'option d'inclure les modèles non disponibles.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

models = client.list_models(include_unavailable=False)
for model in models:
    print(model.id, model.provider, model.available)

Téléversements

Obtenir des URLs présignées pour le téléversement direct de fichiers vers le stockage objet.

Présigner un upload

Demander une URL présignée pour téléverser un fichier. Envoyez les octets vers upload_url avec les headers fournis, puis passez upload_id au point de terminaison d'enregistrement.

python

from aethexai import AethexAI
import httpx

client = AethexAI(api_key="ae_live_...")

upload = client.presign_upload(
    kind="doc/knowledge-base",
    filename="faq.pdf",
    content_type="application/pdf",
)

with open("faq.pdf", "rb") as f:
    httpx.request(
        upload.method,
        upload.upload_url,
        content=f.read(),
        headers=dict(upload.headers.additional_properties),
    ).raise_for_status()
print(upload.upload_id)

Utilisation et facturation

Interrogez les métriques d'utilisation, configurez les déclencheurs de facturation et gérez les secrets webhook.

Obtenir l'utilisation

Récupérer les compteurs d'utilisation bruts de votre tenant.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

usage = client.get_usage()
print(usage)

Obtenir le résumé d'utilisation

Récupérer le résumé d'utilisation agrégé pour la période de facturation en cours.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

summary = client.get_usage_summary()
print(summary)

Obtenir l'utilisation quotidienne

Récupérer l'utilisation jour par jour pour les N derniers jours.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

for day in client.get_daily_usage(days=30):
    print(day.date, day.count, day.total_tokens, day.voice_seconds)

Obtenir l'utilisation mensuelle

Récupérer l'historique d'utilisation mois par mois.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

for month in client.get_monthly_usage():
    print(month.month, month.count, month.total_tokens, month.voice_seconds)

Créer un déclencheur

Configurer un déclencheur de seuil d'utilisation qui envoie un webhook quand le seuil est dépassé.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

trigger = client.create_trigger(
    resource_type="voice_call",
    threshold_value="180000",  # string preserves precision; server parses to Decimal
    threshold_type="count",
    period="monthly",
    event_callback_url="https://example.com/webhooks/usage",
)
print(trigger.id)

Lister les déclencheurs

Lister tous les déclencheurs de seuil d'utilisation de votre tenant.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

for trigger in client.list_triggers():
    print(trigger.id, trigger.resource_type, trigger.threshold_value, trigger.is_active)

Mettre à jour un déclencheur

Mettre à jour le seuil ou la configuration d'un déclencheur existant.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.update_trigger(
    "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
    threshold_value="250000",
)

Faire pivoter le secret webhook

Faire pivoter le secret webhook partagé pour la livraison des déclencheurs. L'appel SDK fait pivoter le secret mais ne retourne pas sa valeur ; si vous avez besoin de récupérer le nouveau secret, envoyez plutôt la requête HTTP brute, qui le retourne dans la réponse. Chaque appel fait pivoter et révoque le secret précédent, utilisez donc l'une ou l'autre approche.

Lister les déclenchements

Récupérer l'historique de livraison d'un déclencheur.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

firings = client.list_trigger_firings("4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a", limit=50)
for firing in firings:
    print(firing.id, firing.fired_at, firing.delivery_status, firing.attempt_count)

Relancer un déclenchement

Réessayer la livraison d'un déclenchement précédemment échoué.

python

from aethexai import AethexAI

client = AethexAI(api_key="ae_live_...")

client.redeliver_firing(
    "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
    "7c6d5e4f-3a2b-1c0d-9e8f-7a6b5c4d3e2f",
)

Support asynchrone

AsyncAethexAI reflète le client synchrone méthode par méthode. Utilisez-le avec asyncio, FastAPI, des workers ou tout framework async où vous voulez des appels HTTP non bloquants.

python

import asyncio
from aethexai import AsyncAethexAI

async def main():
    async with AsyncAethexAI(api_key="ae_live_...") as client:
        voices = await client.list_voices(language="english")
        agent = await client.create_agent(
            name="Async Bot",
            system_prompt="You are a helpful customer support agent.",
            voice_id=voices[0].id,
        )
        call = await client.trigger_call(
            agent_id=agent.id,
            to_number="+14155551234",
            from_number="+18005550000",
        )
        print(call["id"], call["status"])

asyncio.run(main())

Conversations en temps réel

Utilisez l'extra realtime pour des conversations WebRTC full-duplex avec le même pipeline vocal que vos utilisateurs finaux obtiennent depuis le tableau de bord. Nécessite l'extra realtime · installez avec pip install "aethexai[realtime]". L'extra realtime télécharge aiortc et PyAV ; PyAV nécessite les headers de développement FFmpeg sur l'hôte avant que le wheel puisse être compilé (apt install libavformat-dev libavfilter-dev libavdevice-dev sur Debian/Ubuntu, brew install ffmpeg sur macOS).

Remarque

Par défaut Conversation attache une piste d'entrée silencieuse, donc l'agent n'entendra que le silence jusqu'à ce que vous branchiez une vraie source audio. Passez n'importe quel MediaStreamTrack aiortc (par exemple un basé sur sounddevice) via le mot-clé audio_input= pour envoyer l'entrée micro. Le agent_id ci-dessous doit être l'UUID d'un agent que vous avez déjà créé · obtenez-le depuis list_agents() plutôt que de le coder en dur.

python

import asyncio
from aethexai import AsyncAethexAI
from aethexai.realtime import Conversation, ConversationCallbacks

async def main():
    async with AsyncAethexAI(api_key="ae_live_...") as client:
        page = await client.list_agents(limit=1)
        if not page.data:
            raise SystemExit("Create an agent before starting a realtime call")
        agent_id = page.data[0].id

        conversation = Conversation(
            client,
            agent_id=agent_id,
            callbacks=ConversationCallbacks(
                on_agent_text=lambda text: print("agent:", text),
                on_user_transcript=lambda text: print("user:", text),
            ),
            # audio_input=<your aiortc MediaStreamTrack from sounddevice>,
        )
        await conversation.start()
        await asyncio.sleep(30)
        await conversation.end()

asyncio.run(main())

Gestion des erreurs

Le SDK lève des exceptions typées pour les erreurs API et de transport. Toutes les exceptions héritent de AethexError. Les sous-classes d'APIStatusError portent le code de statut HTTP, le code d'erreur, les headers et le corps de réponse brut. RateLimitError inclut une propriété retry_after.

python

from aethexai import (
    AethexAI,
    AethexError,
    APIStatusError,
    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 AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")
except AethexError as e:
    print(f"SDK error: {e}")