Guides

SDK du visage

Préversion

Le SDK est en préversion (0.x) : son interface peut encore évoluer. Pour la fenêtre de conversation complète (visage, voix, micro, suggestions), voir Fenêtre de conversation.

Le SDK affiche le visage d'un avatar dans votre page et anime sa bouche sur la voix : sa voix Twimi (formules Avatar Widget et Avatar Agent), ou la vôtre (formule Avatar SDK : votre voicebot, votre synthèse vocale, un enregistrement). Il s'occupe de la conversation, du jeton et des fichiers du visage.

Voir la démonstration, avec Maude et Antoine.

Installer

Code
<script src="https://api-dev.atwimi.com/v1/sdk/twimi.js"></script>

/v1/sdk/twimi.js : la dernière version 0.x ;
/v1/sdk/0.5.0/twimi.js : une version figée, qui ne change jamais (conseillé en production).

Tout vient de Twimi, y compris le moteur du modèle de bouche (ONNX Runtime) : aucun CDN tiers à autoriser.

Afficher et faire parler

Code
<div id="zone"></div>
<button id="parler">Parler</button>
<script>
  const tw = await Twimi.init({ key: "pk_test_…", avatar: "maude" });
  const face = tw.face({ container: "#zone", size: 320 });

  document.getElementById("parler").onclick = () => face.say("Bonjour ! Je suis Maude.");
</script>

Twimi.init vérifie la clé et la page en lisant la fiche de l'avatar. Utilisez la clé publique (pk_…), depuis une page déclarée pour votre déploiement : le SDK refuse une clé secrète.
tw.face() affiche le visage tout de suite ; l'événement ready arrive quand la bouche est prête (quelques secondes au premier chargement).
La conversation s'ouvre au premier say() ou play() (voir Voix et décompte), et son jeton est renouvelé tout seul.

Sa voix ou la vôtre

	Méthode	Formules
La voix de l'avatar	`face.say(texte)` : découpé en phrases, la suivante se prépare pendant que la précédente est dite. Accepte aussi un flux de texte (un bot qui répond en streaming).	Avatar Widget, Avatar Agent
Votre voix	`face.play(son)` : `ArrayBuffer`, `Blob`, `AudioBuffer` ou adresse d'un fichier. Le son est analysé en entier avant d'être joué : envoyez une longue réponse phrase par phrase.	Avatar SDK (et les autres)

say() et play() se résolvent à la fin de la parole.

Contrôler


`face.stop()`	arrête tout de suite ; ce qui restait à dire est abandonné, `end` est émis
`face.mute(true)`	coupe le son ; la bouche continue de bouger
`face.unlock()`	débloque le son (à appeler dans un clic)
`face.destroy()`	libère le visage et termine la conversation
`face.state`	`loading`, `idle`, `speaking` ou `error`

Événements

Code
face.on("ready", () => {});                         // la bouche est prête
face.on("start", ({ duration }) => {});            // une phrase commence
face.on("end", () => {});                           // elle est finie (ou arrêtée)
face.on("status", ({ state }) => {});
face.on("error", ({ code, message, reason }) => {});

Une erreur dans votre gestionnaire n'arrête jamais le SDK.

Le son bloqué par le navigateur

Les navigateurs interdisent de jouer un son avant un geste du visiteur. Si say() ou play() part sans clic, le SDK émet error avec le code audio_locked, puis le son part au premier clic ou à la première touche. Pour l'éviter, déclenchez la parole depuis un clic, ou appelez face.unlock() dans un gestionnaire de clic.

Erreurs

Les promesses sont rejetées avec une Twimi.TwimiError : code (celui de l'API, voir Erreurs et limites, ou audio_locked, audio_unreadable, destroyed, network), message, status, requestId et, pour voice_limit_reached, reason.

Sans écrire d'initialisation

Code
<twimi-face key="pk_test_…" avatar="maude" size="320"></twimi-face>
<script>
  document.querySelector("twimi-face").say("Bonjour !");
</script>

Le style de la balise est isolé : celui de votre site ne casse pas le visage, et inversement. Ses événements sont twimi-ready, twimi-start, twimi-end, twimi-error et twimi-status (contenu dans event.detail).

Limites de la préversion

Un déploiement correspond à un avatar : une autre clé pour un autre avatar.
Pas de flux audio continu (voicebot en temps réel) : envoyez le son phrase par phrase.
Le visage s'affiche en carré ; sa taille se règle avec size (en pixels).

Last modified on October 28, 2026

Fenêtre de conversation Clés et jetons