Construis sur ta voix

Savoir ce que ça coûte avant de payer

GET /api/v1/estimate rend le tarif complet et, si tu passes ?operation=…, le prix de cette action confronté à ton solde (affordable). Le montant annoncé sort du même calculque le montant débité — pas d'une table tenue à part, qui finirait par mentir.

conditional: trueveut dire que l'opération est gratuite si elle ne produit rien: moteur qui s'abstient, texte qui n'a rien d'objectif à corriger, certificat refusé. C'est la règle des crédits à la valeur — un prix annoncé sec te ferait renoncer à une vérification qui ne t'aurait rien coûté. Estimation, pas réservation : seule l'exécution débite.

Lire une liste en entier

Chaque liste rend nextCursor. Tant qu'il n'est pas null, il reste des éléments : rappelle le même endpoint avec ?cursor=…. Nul = tu as tout vu — et cette fois c'est une information, pas une supposition. Le curseur est opaque : recopie-le, ne le fabrique pas. Un curseur illisible est refusé (400) plutôt qu'ignoré, sinon tu boucleras sur la première page en croyant avancer.

Rejouer un appel sans le payer deux fois

Ajoute Idempotency-Key: <ton identifiant> sur les écritures (/generate, /improve, /documents, /voices, /projects, /sources, /certify, /recipes/{id}/run). Si un appel reste sans réponse, retente avec la même clé : tu récupères la réponse du premier, marquée idempotentReplay, sans second débit ni second document. Clé valable 24 h.

La même clé sur une demande différenteest refusée (422) plutôt que rejouée : mieux vaut un refus lisible qu'une réponse qui ne correspond pas. Les mesures (/score, /verify, /compare) n'en prennent pas — une clé y masquerait une re-mesure volontaire.

Le Coffre — et pourquoi une preuve s'atteste

Trois endroits différents, à ne pas confondir : /sources/inbox est ta boîte de réception (gratuite, tu tries), /sourcesnourrit la mémoire d'un projet (ce dont tu parles), et /voice/assets est le Coffre d'une voix : ce avec quoi tu prouves.

kindest requis et fermé (preuve · cas_client · temoignage · resultat · histoire) — c'est lui qui distingue une preuve d'une note. Sur les quatre types de preuve, provenance:"human" est exigée : cette matière sera citée comme vérifiable, donc elle doit être réelle. Un agent n'invente pas un cas client à ta place.

Tes convictions et tes sous-voixse lisent, mais ne s'écrivent pas depuis l'API : une conviction posée par un agent n'est pas une conviction, et activer une sous-voix change tous tes textes sur ce canal. Ces deux gestes restent les tiens, dans l'app.

Créer une voix — et pourquoi la provenance compte

POST /api/v1/voices compile une nouvelle voix. Deux modes : mode:"interview" (une transcription questions/réponses) ou mode:"samples" (de vrais textes déjà écrits, qui deviennent la cadence de référence de la voix, réinjectée à chaque génération).

En interview, ton agent mène l’entretien lui-même— express (~5 questions) ou complet (~15) — puis passe la transcription à compiler. Côté MCP, le script des questions vit dans la description de l’outil create_voice : l’agent a de quoi poser les bonnes questions, une à la fois.

Le mode samples exige provenance:"human". Ce n’est pas une formalité : une voix ancrée sur de l’IA n’est plus ta voix, c’est une IA-en-voix qui se mesurerait elle-même. Un agent ne doit jamais y coller un texte qu’il vient de générer — s’il n’est pas de ta main, c’est le mode interview qui convient. Sans l’attestation, l’appel est refusé, pas dégradé en silence.

Deux nombres, deux questions

/score mesure une fidélité de style : ce texte sonne-t-il travaillé et personnel ? Il ne dit pas qui a écrit — un texte de quelqu’un d’autre peut obtenir 90. /verify répond à la question d’auteur, et rend une probabilité calibrée plutôt qu’un score :question="author" (toi vs un autre humain) ou question="human" (toi vs une IA qui t’imite). Un même score ne vaut pas la même probabilité selon la question.

probability peut valoir null avec un champ unavailable : c’est une abstention assumée quand la mesure ne peut pas trancher — à traiter comme « vérification impossible », jamais comme un score de zéro. Dans ce cas aucun crédit n’est débité. Et c’est un indice, jamais une preuve opposable : face à un texte machine retravaillé pour passer, le haut de l’échelle sur-promet (96 % annoncé, 88 % réel — mesuré, publié sur /methode).

Écrire, ou améliorer ce qui existe déjà

/generate PART d’un sujet et rédige dans ta voix. /improvePART d’un texte déjà écrit — celui que ton agent vient de produire — et le réécrit dans ta voix : « améliore ce contenu avec ma voix ». C’est une passe corrective bornée (elle corrige les défauts constatés, préserve le fond et la longueur) et renvoie le texte + le score avant/après. Rien à corriger ? Le texte revient inchangé, sans débit.

/comparerépond à « ce texte est-il de la même main que celui-ci ? » contre une référence que TU fournis — un autre auteur collé, ou une autre de tes voix. Même honnêteté que /verify : probabilité calibrée, abstention si la mesure ne tranche pas, plancher hors de ton genre.

Un projet, sa mémoire, sa preuve

/projects crée un projet relié à une voix ; /sources y verse ce que ton agent a trouvé (recherche web, notes) — le texte est vectorisé et récupéré ensuite par le RAG. Il suffit alors de passer projectId à /generatepour écrire en héritant de cette mémoire. La boucle « cherche, range, écris » s’enchaîne entièrement depuis ton agent.

/certify émet la page publiqued’un document — « ce texte signe ma voix ». Elle n’est délivrée que si la paternité est réellement mesurée et affirmée : sinon le certificat est refusé, sans débit. Le public ne voit qu’une bande (label + affirmation), jamaisde score. À n’appeler que sur ta demande : ça publie.