# Historique des versions

Chaque entrée correspond à une version de la documentation (`DOC_VERSION`), visible dans `/v1/health` et dans le contrat `openapi-v1.json`. Les versions `-preview` sont des préversions : les routes peuvent encore évoluer avant la `1.0.0`.

## 1.0.0-preview.12 — 2026-10-28

- **Fenêtre de conversation** (`Twimi.widget`, SDK 0.5.0) : la fenêtre complète d'un avatar dans votre site (visage qui parle, réponses en flux, micro, suggestions, choix, produits, boutons d'action, passage à l'écrit au-delà du forfait), en quelques lignes ou avec la balise `<twimi-widget>`. La conversation suit le visiteur d'une page à l'autre de votre site, sans nouveau décompte. Nouveau guide « Fenêtre de conversation » ; démonstration : `https://api-dev.atwimi.com/v1/sdk/demo/widget.html`.

## 1.0.0-preview.11 — 2026-10-28

- Clé publique : une page servie **à la même adresse que l'API** (la démonstration du SDK, le portail) est reconnue même sans en-tête `Origin`, que les navigateurs n'envoient pas pour une lecture vers leur propre adresse. Elle doit toujours être déclarée pour le déploiement. Rien ne change pour une page sur votre propre domaine.

## 1.0.0-preview.10 — 2026-10-28

- **SDK du visage en préversion** : `https://api-dev.atwimi.com/v1/sdk/twimi.js` (dernière 0.x) ou `/v1/sdk/0.3.0/twimi.js` (version figée) ; `Twimi.init`, `face.say` (voix Twimi), `face.play` (votre voix), `stop`, `mute`, `destroy`, événements, balise `<twimi-face>`. Tout est servi par Twimi, y compris ONNX Runtime. Nouveau guide « SDK du visage ».
- **Démonstration** : `https://api-dev.atwimi.com/v1/sdk/demo/` (Maude et Antoine, leur voix ou la vôtre).

## 1.0.0-preview.9 — 2026-10-28

- Fiche de l'avatar et voix : le **nom affiché** et les **voix par langue** déclarés par votre client ne s'appliquent plus qu'à l'avatar de ce client. Un déploiement qui utilise un autre avatar garde le nom et la voix propres à cet avatar.

## 1.0.0-preview.8 — 2026-10-28

- **Portail de la documentation en ligne : https://api-dev.atwimi.com/** (guides, référence interactive avec essai en direct, historique). C'est désormais la seule référence ; `API.md` n'est plus qu'un renvoi vers le portail.

## 1.0.0-preview.7 — 2026-10-28

- **Portail de documentation** (guides, référence interactive, historique), préparé dans le dépôt ; sa mise en ligne suivra.
- `/messages` : le champ `lang` est accepté mais **sans effet** en v1 : l'avatar répond dans la langue de la question, détectée à chaque message.
- `/transcriptions` : le refus d'un son de plus de 5 Mo (`413 audio_too_large`) est maintenant documenté.
- Adresse du support : **contact@twimi.ai**.

## 1.0.0-preview.6 — 2026-10-28

- `/speech` : une réponse parlée (un tour) compte 1 500 caractères de voix au plus, tous morceaux compris ; au-delà, `409 voice_limit_reached` avec `X-Twimi-Voice-Reason: reponse`. Un `turn` pas encore donné par `/messages` est refusé (`400`).
- Limites de débit : 60 morceaux de voix et 20 transcriptions par minute et par conversation (`429 rate_limited`).
- La révocation d'une clé arrête les conversations qu'elle a ouvertes (`401 invalid_key`, même avec un jeton renouvelé) ; une page retirée du déploiement aussi (`403 origin_not_allowed`).
- Une conversation dure 10 minutes au plus : nouveau code `410 conversation_expired`.
- Les jetons émis avant cette version ne sont plus acceptés : rouvrir avec `resume` (pas de nouveau décompte).

## 1.0.0-preview.5 — 2026-10-27

- Adresse d'essais publique : **`https://api-dev.atwimi.com/v1`** (la production sera `https://api.twimi.ai/v1`).
- Les fichiers du visage (`/v1/assets/…`) sont servis directement par le serveur web, avec le même contrôle des liens signés ; un lien invalide reçoit toujours `403 invalid_link`.

## 1.0.0-preview.4 — 2026-10-27

- **Décompte** : 5 réponses parlées = 1 conversation (réglable par déploiement) ; une réponse parlée = un tour, ses morceaux comptent une fois.
- `done` de `/messages` porte `turn` ; `/speech` accepte `turn` et renvoie `X-Twimi-Turn` et `X-Twimi-Units`.
- Plafond facultatif de réponses parlées par conversation (`voice.reason: "conversation"`).
- Au-delà du forfait, pas de nouvelle tranche de réponses parlées ; `409 voice_limit_reached` porte l'en-tête `X-Twimi-Voice-Reason`.
- Alertes par e-mail à 80 % et 100 % du forfait ; fusible en cas de trafic anormal (`voice.reason: "fusible"`).

## 1.0.0-preview.3 — 2026-10-27

- `POST /v1/conversations/{id}/messages` : question à l'IA de Twimi, réponse en flux (`token`, `done`, `error`) ; 20 questions par minute et par conversation.
- `POST /v1/conversations/{id}/speech` : texte → voix de l'avatar (MP3), voix de la langue demandée si le client en a déclaré une.
- `POST /v1/conversations/{id}/transcriptions` : question orale → texte ; le son n'est jamais conservé.
- Nouveau code d'erreur : `brain_unavailable`.

## 1.0.0-preview.2 — 2026-10-27

- `POST /v1/conversations` : ouvrir ou reprendre (moins de 30 min d'inactivité) une conversation ; jeton de conversation de 30 minutes ; forfait du mois et disponibilité de la voix (`voice`) dans la réponse. Au-delà du forfait, la conversation s'ouvre quand même, en écrit seul.
- `POST /v1/conversations/{id}/token` (renouveler le jeton) et `POST /v1/conversations/{id}/end` (terminer).
- `GET /v1/avatars/{avatar_id}` : fiche de l'avatar, liens signés vers les fichiers du visage, valables 1 heure.
- `GET /v1/assets/…` : fichiers du visage, par les liens de la fiche seulement.
- `GET /v1/usage` (clé secrète) : conversations ouvertes et décomptées du mois.
- Nouveaux codes d'erreur : `secret_key_required`, `invalid_link`.

## 1.0.0-preview.1 — 2026-10-27

Première préversion, en essai sur le serveur de développement (adresse publique à venir).

- Clés publiques (`pk_`) et secrètes (`sk_`), de test et de production ; clé publique limitée aux pages déclarées.
- `GET /v1/health` : état du service et version de la documentation.
- `GET /v1/me` : le déploiement auquel une clé donne accès.
- Format unique des erreurs, avec `request_id` (aussi dans l'en-tête `X-Request-Id`).
- Documentation interactive `/v1/docs` et contrat `/v1/openapi.json`.

À venir dans les préversions suivantes : ouverture et reprise de conversation, fiche de l'avatar, voix, transcription, questions.