aethexDocs
Tableau de bord

Référence API

Discuter avec l'agent

Envoyez un message texte à un agent et recevez sa réponse, un appel vocal sans l'audio.

URL de base
https://api.aethexai.com/api/v1
Endpoints
1
Portées
agents:write
VOTRE APPserveur ou clientAETHEXvotre agentPOST /agents/:id/chatmessagereply · conversation_id · usageRenvoyez le conversation_id retourné à la requête suivante pour poursuivre la session.
POST/agents/:id/chat

Envoyez un message texte à un agent et recevez sa réponse, un appel vocal sans l'audio.

Discuter avec l'agent

Exécute un tour de conversation texte avec l'agent. La configuration de l'agent (rôle, langue, garde-fous, base de connaissances et variables dynamiques) façonne la réponse, comme un appel vocal sans l'audio. Vous n'envoyez qu'un seul message ; l'invite système et l'historique de conversation restent côté serveur, il est donc impossible d'injecter un rôle system. Indiquez conversation_id pour poursuivre une session (l'identifiant est renvoyé pour réutilisation) ; omettez-le pour en démarrer une nouvelle. Définissez stream: true pour recevoir la réponse en flux Server-Sent Events. L'usage est facturé au jeton.

Chemin & Requête

1
  • idstringrequis

    UUID de l'agent avec qui discuter.

Corps de la requête

4
  • messagestringrequis

    Le message de l'utilisateur : 1 à 8000 caractères et au plus 8000 octets une fois encodé en UTF-8, un message riche en emoji ou en caractères CJK peut donc atteindre la limite bien avant 8000 caractères. Les caractères de contrôle autres que la tabulation, le saut de ligne et le retour chariot sont rejetés.

  • conversation_idstringoptionnel

    Poursuivre une session de chat existante par identifiant ; omettez pour en démarrer une nouvelle.

  • streambooleanoptionnel

    Si true, la réponse est diffusée en text/event-stream (Server-Sent Events) au lieu d'un corps JSON unique. Le statut passe à 200 dès l'ouverture du flux ; une panne du fournisseur ou une complétion vide arrive donc sous forme d'événement SSE error terminal plutôt qu'un statut d'erreur. Gérez cette forme d'événement, pas seulement le code HTTP. L'événement terminal done porte le champ persisted. Lorsqu'il vaut false, la réponse vous est bien parvenue mais ses tours n'ont pas pu être enregistrés : ce tour n'est pas facturé et il est absent de l'historique rejoué au tour suivant. Considérez le conversation_id comme utilisable mais cet échange comme perdu, ou démarrez une nouvelle session.

  • dynamic_variablesobjectoptionnel

    Remplacements {{variable}} par requête, fusionnés avec les valeurs par défaut de l'agent.

Erreurs

8
401Non autorisé

Clé API manquante ou invalide.

Ajoutez X-API-Key: VOTRE_CLÉ à vos en-têtes de requête.

403Interdit

Le chat lance une génération facturée et ajoute des tours à la conversation : il exige donc la portée d'écriture. Une clé disposant uniquement de agents:read est rejetée. La reprise d'une session existante exige en outre conversations:read, car son historique stocké est rejoué au modèle.

Émettez une clé avec le scope agents:write, ainsi que conversations:read si vous transmettez conversation_id.

404Introuvable

Aucun agent de ce type sous ce tenant, ou le conversation_id n'existe pas, appartient à un autre agent, ou a été ouvert sur un canal différent (la transcription d'un appel vocal ne peut pas être reprise par texte). Tous ces cas renvoient intentionnellement le même 404, afin qu'un sondage ne puisse pas distinguer « existe mais ne vous appartient pas » de « n'existe pas ».

Vérifiez l'identifiant de l'agent, et omettez conversation_id pour démarrer une nouvelle session si l'identifiant provient d'un autre agent ou canal.

402Paiement requis

La facturation du compte est bloquée (crédits épuisés).

Ajoutez des crédits ou résolvez le problème de facturation, puis réessayez.

409Conflit

L'agent est encore en cours de provisionnement ou son provisionnement a échoué ; il n'a donc pas encore de configuration utilisable pour façonner une réponse.

Attendez que l'agent termine son provisionnement (interrogez GET /agents/{id} jusqu'à ce que son statut soit prêt), puis réessayez.

422Entité non traitable

Le message est vide, dépasse 8000 caractères ou 8000 octets UTF-8, contient des caractères de contrôle, l'invite de l'agent référence une variable dynamique sans valeur, ou l'invite assemblée dépasse la fenêtre de contexte du modèle.

Raccourcissez le message, fournissez les dynamic_variables manquantes, ou réduisez le max_tokens de l'agent.

429Trop de requêtes

Trop de requêtes sont en cours, le service est momentanément saturé et a limité celle-ci.

Réessayez après le délai indiqué dans l'en-tête de réponse Retry-After, avec un backoff exponentiel.

503Service indisponible

Le modèle est temporairement indisponible (fournisseur en panne ou disjoncteur ouvert).

Réessayez après un court délai.