enterprise_ai.multimodal.realtime
Source : sdks/python/src/enterprise_ai/multimodal/realtime/__init__.py. Retour à l'index de la référence du SDK Python.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Classe RealtimeError
Un événement error reçu sur le socket temps réel.
EaiError
Modèle RealtimeEvent
Un événement serveur décodé.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
type | str | oui | Type de l'événement, par exemple transcript.delta ou response.done (unknown s'il est absent). |
data | dict[str, Any] | non | Champs décodés de l'événement serveur, en plus de son type. |
Attributs :
| Nom | Type | Requis | Description |
|---|---|---|---|
audio | bytes | oui | Audio décodé d'un événement response.audio.delta. |
text | str | oui | Texte d'un événement transcript.delta. |
Classe RealtimeConnection
Un WebSocket temps réel ouvert (gestionnaire de contexte asynchrone).
Attributs :
| Nom | Type | Requis | Description |
|---|---|---|---|
headers | oui | En-têtes HTTP envoyés à l'ouverture du socket. | |
raise_on_error | oui | Indique si un événement serveur error lève RealtimeError. | |
url | oui | URL WebSocket, avec ?token= une fois un jeton obtenu. | |
usage | dict[str, Any] | oui | Dernière consommation indiquée par un événement usage.update, {} avant. |
ws | Any | oui | Le socket ouvert, None avant l'ouverture et après close. |
Constructeur RealtimeConnection
RealtimeConnection(url: str, headers: dict[str, str], raise_on_error: bool = True, connector: Any = None, token_provider: Callable[[], Any] | None = None)
Prépare la connexion ; le socket s'ouvre avec async with.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
url | str | oui | URL WebSocket de la session. | |
headers | dict[str, str] | oui | En-têtes HTTP envoyés à l'ouverture du socket (authentification, tenant). | |
raise_on_error | bool | True | non | Lève RealtimeError sur un événement serveur error (True par défaut). |
connector | Any | None | non | Fonction coroutine qui ouvre le socket, par défaut websockets.asyncio.client.connect. |
token_provider | Callable[[], Any] | None | None | non | Appelé à l'ouverture de la connexion pour obtenir un nouveau ws_token, ajouté à url en ?token=. |
RealtimeConnection.append_audio
async append_audio(pcm: bytes) -> None
input_audio.append avec l'audio encodé en base64.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
pcm | bytes | oui | Octets audio bruts à envoyer. |
Retour : None.
RealtimeConnection.cancel_response
async cancel_response() -> None
response.cancel : arrête la réponse en cours (response.cancelled).
Cet élément ne prend aucun paramètre.
Retour : None.
RealtimeConnection.close
async close() -> None
Ferme le socket ; sans effet s'il n'est pas ouvert.
Cet élément ne prend aucun paramètre.
Retour : None.
RealtimeConnection.commit_audio
async commit_audio() -> None
input_audio.commit : termine l'énoncé (enregistre l'audio si config.record est défini).
Cet élément ne prend aucun paramètre.
Retour : None.
RealtimeConnection.create_response
async create_response(text: str, voice: str | None = None) -> None
response.create {text, voice?} : le serveur prononce text (response.created puis l'audio).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
text | str | oui | Texte que le serveur prononce. | |
voice | str | None | None | non | Voix à utiliser, facultative ; absente de l'événement si elle n'est pas fournie. |
Retour : None.
RealtimeConnection.events
async events() -> AsyncIterator[RealtimeEvent]
Fournit les événements du serveur jusqu'à la fermeture du socket ; error lève une erreur si raise_on_error.
Cet élément ne prend aucun paramètre.
Retour : AsyncIterator[RealtimeEvent]. Des RealtimeEvent : chacun un événement serveur décodé.
Erreurs levées : RealtimeError.
RealtimeConnection.send
async send(event: dict[str, Any]) -> None
Envoie un événement client.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
event | dict[str, Any] | oui | Événement client, envoyé en JSON (voir client_event). |
Retour : None.
RealtimeConnection.speech_started
async speech_started() -> None
input_audio.speech_started : interruption par l'utilisateur, le serveur annule la réponse en cours de diffusion.
Cet élément ne prend aucun paramètre.
Retour : None.
RealtimeConnection.update_session
async update_session(**settings: Any) -> None
session.update (voix, langue, détection des tours de parole, instructions...).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
**settings | Any | non | Réglages de session envoyés comme session, par exemple voice et language. |
Retour : None.
Classe RealtimeClient
Voix en temps réel. Sessions de voix en temps réel : un jeton de salle LiveKit et un protocole d'événements WebSocket pour diffuser de l'audio vers un agent, avec consentement des participants, tours de parole, transcriptions filtrées par la DLP, enregistrements facultatifs et comptage d'usage.
Resource
RealtimeClient.connect
connect(session_id: str | dict[str, Any], ws_token: str | None = None, raise_on_error: bool = True, connector: Any = None) -> RealtimeConnection
Ouvre le socket temps réel (à utiliser avec async with) ; le serveur exige un ws_token à usage unique.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
session_id | str | dict[str, Any] | oui | Identifiant de session, ou la réponse de create_session ou create_token (son ws_token est alors utilisé). | |
ws_token | str | None | None | non | Jeton à usage unique ; sans lui, un nouveau jeton est demandé à l'ouverture de la connexion. |
raise_on_error | bool | True | non | Lève RealtimeError sur un événement serveur error (True par défaut). |
connector | Any | None | non | Fonction coroutine qui ouvre le socket, par défaut websockets.asyncio.client.connect ; à remplacer dans les tests. |
Retour : RealtimeConnection. Une RealtimeConnection : un WebSocket temps réel ouvert (gestionnaire de contexte asynchrone).
RealtimeClient.create_session
create_session(pipeline: str = 'echo', room: str | None = None, ttl_seconds: int | None = None, config: dict[str, Any] | None = None) -> Any
Ouvrir une session temps réel. Ouvre une session (201) et la renvoie avec session_id, livekit (url, token, room, configured) et l'accès WebSocket (ws_url, ws_token, ws_token_expires_at). Demande tenant_admin, developer ou agent. Contrôles : pipeline vaut echo ou stt (400 invalid_request) ; config.vad et config.dlp_mode sont valides (422 parameter_invalid) ; un appelant agent agit pour on_behalf_of, un utilisateur ne peut ouvrir une session que pour lui-même (403 identity_mismatch) ; les identifiants LiveKit sont configurés ; la politique realtime.session.create est évaluée. La salle prend par défaut un nom dérivé du tenant et de la session. Audité sous realtime.session.create.
Route : /v1/realtime/sessions (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
pipeline | str | 'echo' | non | echo (par défaut) ou stt. |
room | str | None | None | non | Nom de la salle LiveKit (1 à 128 lettres, chiffres, ., _, -). Par défaut : dérivé du tenant et de la session. |
ttl_seconds | int | None | None | non | Durée de vie du jeton LiveKit, en secondes (60 à 86400, 3600 par défaut). |
config | dict[str, Any] | None | None | non | Configuration de la session : dlp_mode (mask par défaut, tokenize ou block), vad (enabled booléen, threshold dans (0, 1]), record et options du pipeline. |
Retour : Any. Réponse JSON décodée de l'opération « Ouvrir une session temps réel ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RealtimeClient.create_token
create_token(session_id: str) -> Any
Obtenir un nouveau jeton WebSocket. Nouveau jeton WebSocket à usage unique pour une session ouverte (reconnexion), lu sous RLS : ws_url, ws_token, ws_token_expires_at. 409 session_ended ; 404 not_found. Demande tenant_admin, developer ou agent. Audité sous realtime.session.token.
Route : /v1/realtime/sessions/{session_id}/token (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
session_id | str | oui | Identifiant (UUID) de la session temps réel. |
Retour : Any. Réponse JSON décodée de l'opération « Obtenir un nouveau jeton WebSocket ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RealtimeClient.end_session
end_session(session_id: str) -> Any
Terminer une session temps réel. Termine la session et enregistre son événement d'usage (voice_live : secondes d'audio, jetons d'entrée et de sortie, coût mesuré). Terminer une session déjà terminée la renvoie sans changement. Demande tenant_admin, developer ou agent. Audité sous realtime.session.end.
Route : /v1/realtime/sessions/{session_id}/end (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
session_id | str | oui | Identifiant (UUID) de la session temps réel. |
Retour : Any. Réponse JSON décodée de l'opération « Terminer une session temps réel ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RealtimeClient.get_session
get_session(session_id: str) -> Any
Lire une session temps réel. Renvoie la session : salle, identités, agent, pipeline, configuration, statut, secondes d'audio, jetons et usage. 404 not_found.
Route : /v1/realtime/sessions/{session_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
session_id | str | oui | Identifiant (UUID) de la session temps réel. |
Retour : Any. Réponse JSON décodée de l'opération « Lire une session temps réel ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RealtimeClient.list_consents
list_consents(session_id: str) -> Any
Lister les consentements d'une session. Consentements enregistrés pour la session, dans l'ordre de recueil, avec leur révocation le cas échéant. Une seule page.
Route : /v1/realtime/sessions/{session_id}/consents (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
session_id | str | oui | Identifiant (UUID) de la session temps réel. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les consentements d'une session ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RealtimeClient.record_consent
record_consent(session_id: str, purpose: str, retention_days: int, recording_allowed: bool | None = None, transcription_allowed: bool | None = None, method: str | None = None, participant_identity: str | None = None) -> Any
Enregistrer le consentement d'un participant. Consentement d'un participant (finalité, enregistrement, transcription, conservation, méthode), recueilli par l'appelant (201). Le participant est par défaut celui de la session. La méthode doit être verbal, click, written ou api (422 parameter_invalid) ; la session ne doit pas être terminée (409 session_ended) ; la politique realtime.consent.record est évaluée. Demande tenant_admin, developer ou agent. Audité sous realtime.consent.record.
Route : /v1/realtime/sessions/{session_id}/consents (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
session_id | str | oui | Identifiant (UUID) de la session temps réel. | |
purpose | str | oui | Finalité acceptée par le participant (1 à 500 caractères). | |
retention_days | int | oui | Durée de conservation des transcriptions et enregistrements, en jours (1 à 3650). | |
recording_allowed | bool | None | None | non | Si l'audio peut être enregistré. Faux par défaut. |
transcription_allowed | bool | None | None | non | Si la parole peut être transcrite et conservée. Faux par défaut. |
method | str | None | None | non | Méthode de recueil du consentement : verbal, click, written ou api (par défaut). |
participant_identity | str | None | None | non | Identité du participant (1 à 128 lettres, chiffres, ., _, :, @, -). Par défaut : le participant de la session. |
Retour : Any. Réponse JSON décodée de l'opération « Enregistrer le consentement d'un participant ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RealtimeClient.revoke_consent
revoke_consent(session_id: str, consent_id: str) -> Any
Révoquer un consentement. La révocation prend effet au prochain événement audio : transcription et enregistrement sont de nouveau refusés. Un consentement déjà révoqué ou inconnu répond 404 not_found. Demande tenant_admin, developer ou agent. Audité sous realtime.consent.revoke.
Route : /v1/realtime/sessions/{session_id}/consents/{consent_id}/revoke (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
session_id | str | oui | Identifiant (UUID) de la session temps réel. | |
consent_id | str | oui | Identifiant (UUID) du consentement. |
Retour : Any. Réponse JSON décodée de l'opération « Révoquer un consentement ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RealtimeClient.transcripts
transcripts(session_id: str) -> Any
Lister les transcriptions d'une session. Transcriptions conservées, déjà filtrées par la DLP (la transcription brute n'est jamais conservée), avec tour, consentement, participant, détections DLP et expiration. Demande tenant_admin, developer, auditor ou security_officer.
Route : /v1/realtime/sessions/{session_id}/transcripts (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
session_id | str | oui | Identifiant (UUID) de la session temps réel. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les transcriptions d'une session ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RealtimeClient.turns
turns(session_id: str) -> Any
Lister les tours d'une session. Tours avec le participant, l'utilisateur, l'agent, l'identifiant de trace, le statut (une interruption enregistre cancelled) et la latence mesurée, dans l'ordre. Une seule page.
Route : /v1/realtime/sessions/{session_id}/turns (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
session_id | str | oui | Identifiant (UUID) de la session temps réel. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les tours d'une session ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RealtimeClient.ws_url
ws_url(session_id: str | dict[str, Any], ws_token: str | None = None) -> str
URL du WebSocket /v1/realtime/ws/{session_id}?token=<ws_token>.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
session_id | str | dict[str, Any] | oui | Identifiant de session, ou la réponse de create_session (ses session_id et ws_token sont lus). | |
ws_token | str | None | None | non | Jeton à usage unique ajouté en ?token=, facultatif. |
Retour : str. URL wss:// (ws:// si l'URL de base n'est pas en HTTPS), avec le jeton s'il est connu.
Fonctions
client_event
client_event(event_type: str, **payload: Any) -> dict[str, Any]
Construit un événement client avec un event_id.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
event_type | str | oui | Un parmi session.update, input_audio.append, input_audio.commit, input_audio.speech_started, response.create, response.cancel ; tout autre lève ValueError. | |
**payload | Any | non | Champs de l'événement, fusionnés à côté de type et event_id. |
Retour : dict[str, Any]. Dict d'événement avec type, un nouvel event_id (préfixe evt_) et le contenu.
Erreurs levées : ValueError.
parse_event
parse_event(message: str | bytes) -> RealtimeEvent
Décode un message du serveur.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
message | str | bytes | oui | Message JSON reçu sur le socket, texte ou octets. |
Retour : RealtimeEvent. Un RealtimeEvent : un événement serveur décodé.