Automatiser Transept avec l'API

Créez une clé API personnelle dans Paramètres → Développeur. Elle est disponible pour tous les forfaits, y compris l'offre gratuite — il n'y a pas de restriction d'accès particulière, seul votre solde de mots limite l'utilisation. Nommez votre clé, définissez éventuellement une date d'expiration et copiez le secret lorsqu'il s'affiche : il n'apparaît qu'une seule fois et ne pourra plus être récupéré par la suite. Vous pouvez révoquer une clé à tout moment depuis cette même page.

L'authentification des requêtes s'effectue via la clé dans un en-tête Authorization: Bearer tsk_live_… — exclusivement dans l'en-tête, jamais dans l'URL.

Six appels rapides suffisent pour passer d'une clé API au résultat traduit. Seule l'exécution de la traduction elle-même consomme des mots ; les estimations sont gratuites, et une requête relancée avec la même Idempotency-Key renvoie le résultat d'origine au lieu d'être facturée deux fois.

Retrouvez ces mêmes appels avec plus d'explications sur transept.ai/developers. Le guide de l'API de localisation détaille le reste : catalogues de chaînes, modèles d'e-mails, glossaires, équipes et étapes de révision.

export KEY="tsk_live_…"                          # minted under Settings → Developer
BASE="https://app.transept.ai/api/public/v1"

# 1. Check the key: your account, its permissions, your word balance
curl -s $BASE/me -H "Authorization: Bearer $KEY"

# 2. Create a document; Transept creates one language version per target
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Welcome email", "content": "# Welcome…", "content_type": "markdown",
       "source_language": "en", "target_languages": ["de", "fr", "uk"]}'

# 3. Estimate: the word cost, free, with no side effects
curl -s -X POST $BASE/group-runs/estimate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'

# 4. Run: the same body starts it
curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-1" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'

# 5. Wait: poll for per-language progress (or get pushed an event; see below)
curl -s $BASE/group-runs/<group-run-id> -H "Authorization: Bearer $KEY"

# 6. Read each language back in the format you need (the table below lists them)
curl -s "$BASE/documents/<version-id>/content?format=markdown" \
  -H "Authorization: Bearer $KEY"

Créez un document à partir de texte brut, HTML ou markdown, ou importez un fichier — les formats sont les mêmes que ceux acceptés par l'application. Vous pouvez aussi importer une table de chaînes (.tstrings.json) : un format structuré pour les textes d'interface ou de jeux, où chaque chaîne est une unité dotée d'une clé stable et de son propre contexte — une note sur sa nature, son emplacement, une limite de caractères et le sens de ses placeholders. Toutes ces informations sont transmises au modèle ; les placeholders comme {name} sont protégés contre la suppression ou le renommage, et les pluriels sont développés par langue (une forme en anglais devient deux en allemand, quatre en ukrainien). Les traductions déjà présentes dans le fichier sont importées telles quelles, sans frais, et alimentent immédiatement la mémoire de traduction.

Une exécution groupée traduit vers plusieurs langues à la fois. Indiquez le document, le workflow ou le modèle à lancer, ainsi que les langues cibles ; Transept crée les versions linguistiques manquantes et exécute le workflow pour chacune d'elles. Un ID unique permet de suivre l'ensemble — interrogez-le pour connaître la progression par langue et savoir si une révision est en attente.

Pour les exécutions répétées, soumettez à nouveau le fichier actuel d'une table de chaînes et Transept identifie les changements : les chaînes inchangées conservent leur traduction (et les révisions déjà effectuées), et l'exécution ne traite que les unités nouvelles ou réellement modifiées — le versant API de Ne lancer que ce qui a changé. Toute la boucle indexée, du premier import aux exécutions delta, est détaillée dans Localiser un catalogue de chaînes via l'API.

Plutôt que d'interroger l'API en boucle, enregistrez une URL pour que Transept vous envoie un événement dès qu'une exécution se termine ou échoue, qu'une révision est prête à être examinée, qu'un import est traité ou qu'un export est prêt. Chaque envoi comporte un en-tête HMAC-SHA256 X-Transept-Signature: t=…,v1=… permettant à votre serveur de vérifier que l'appel provient bien de nous. Si un point de terminaison échoue, de nouvelles tentatives sont effectuées avec un délai progressif (backoff) avant qu'il ne soit désactivé.

# register once; every matching event is POSTed to your URL, signed
curl -s -X POST $BASE/webhooks \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/transept-events",
       "events": ["group_run.completed", "run.gate_ready", "run.failed"]}'
# → the endpoint, including its ONE-TIME secret; verify X-Transept-Signature with it

Un workflow peut aussi s'exécuter automatiquement depuis une automatisation de base de données Notion : pointez le webhook de l'automatisation vers l'URL de déclenchement et Transept lancera le workflow sur la page modifiée. Le problème est qu'un webhook Notion ne transmet jamais le contenu de la page — il indique seulement quelle page a déclenché l'événement. Transept lit cette page via votre connexion Notion. Deux conditions doivent donc être remplies, sans quoi chaque déclenchement sera rejeté par une erreur d'accès et la carte du déclencheur affichera la mention « impossible de lire la page Notion » :

• Connectez Notion dans Transept — sous Paramètres → Intégrations. Il s'agit du lien OAuth unique qui autorise Transept à lire en votre nom.
• Partagez la base de données source avec l'intégration dans Notion — ouvrez la base de données (ou la page), cliquez sur son menu •••, choisissez Connexions et ajoutez Transept. Connecter Notion dans les Paramètres ne donne pas accès automatiquement à une base de données spécifique ; sans cette étape, la connexion est active mais la page reste illisible.
• Déclenchez sur un changement de propriété, pas seulement sur une modification du corps. Les automatisations Notion se déclenchent lors de changements de propriétés (et d'ajouts de pages) ; modifier uniquement le corps d'une page peut donc ne rien déclencher. La méthode fiable consiste à utiliser une propriété de Statut surveillée par l'automatisation — changez-la (par exemple en « Prêt pour la traduction ») et c'est ce changement qui activera le déclencheur.

La liste complète des points de terminaison est publiée sous forme de spécification OpenAPI que vous pouvez importer dans n8n, Zapier ou un générateur de code : consultez la référence interactive ou récupérez le JSON brut. Vous préférez un guide pas à pas ? La page transept.ai/developers propose un démarrage rapide avec des exemples à copier-coller, et le guide de l'API de localisation détaille l'intégralité du processus. Les exécutions lancées via l'API sont facturées au mot, exactement comme dans l'éditeur de l'application.

Oui — Transept dispose d'un point de terminaison MCP auquel les assistants IA se connectent : https://app.transept.ai/api/public/v1/mcp. La connexion utilise le protocole standard OAuth : ajoutez l'URL à Claude Code, Claude Desktop, Cursor ou n'importe quel client MCP, et une fenêtre de navigation vous demandera d'approuver l'accès — aucune clé à coller (une clé API dans un en-tête Bearer fonctionne toujours pour la CI et les configurations sans interface). L'assistant dispose alors d'outils pour l'ensemble de la boucle : import de documents, exécution de workflows dans plusieurs langues, gestion des glossaires et des guides de style, interrogation de la mémoire de traduction et lecture des résultats. Deux garde-fous sont intégrés : chaque outil respecte les autorisations que vous avez accordées, et toute action susceptible de consommer des mots renvoie d'abord une estimation — l'assistant doit confirmer explicitement avant le début d'une exécution, afin qu'un agent ne puisse jamais vous facturer par accident. Des extraits de configuration prêts à l'emploi pour chaque client sont disponibles sur la page Intégrations de l'application ; le guide complet, de l'écran de consentement à la déconnexion, est détaillé dans Connecter votre assistant IA.