Automatizza Transept con l'API

Crea una chiave API personale in Impostazioni → Sviluppatore. È disponibile per ogni piano, incluso quello gratuito — non ci sono restrizioni d'accesso, l'unico limite all'utilizzo è il saldo parole. Assegna un nome alla chiave, imposta un'eventuale scadenza e copia il segreto quando viene visualizzato: compare una sola volta e non potrà essere recuperato in seguito. Puoi revocare una chiave in qualsiasi momento dalla stessa pagina.

Le richieste vengono autenticate tramite la chiave inserita in un header Authorization: Bearer tsk_live_… — solo nell'header, mai nell'URL.

Bastano sei brevi chiamate per passare dalla chiave API all'output tradotto. Solo l'effettiva esecuzione della traduzione consuma parole; i preventivi sono gratuiti e una chiamata ripetuta con la stessa Idempotency-Key restituisce il risultato originale anziché effettuare un doppio addebito.

Trovi le stesse chiamate con spiegazioni più dettagliate su transept.ai/developers. La guida all'API di localizzazione illustra tutto il resto: cataloghi di stringhe, template email, glossari, team e gate di revisione.

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"

Crea un documento a partire da testo semplice, HTML o markdown, oppure carica un file: i formati sono gli stessi accettati dall'app. Puoi anche importare una tabella di stringhe (.tstrings.json): un formato strutturato per testi di interfacce o stringhe di gioco, in cui ogni stringa è un'unità con una chiave fissa e il proprio contesto — una nota che ne descrive la natura, la posizione, il limite di caratteri e il significato dei segnaposto. Tutte queste informazioni vengono trasmesse al modello; i segnaposto come {name} sono protetti per evitare che vengano rimossi o rinominati, e i plurali vengono espansi in base alla lingua (una forma inglese ne genera due in tedesco o quattro in ucraino). Le traduzioni già presenti nel file vengono importate così come sono, gratuitamente, e alimentano immediatamente la memoria di traduzione.

Un'esecuzione di gruppo permette di tradurre in diverse lingue contemporaneamente. Specifica il documento, il workflow o il template da avviare e le lingue di destinazione; Transept crea le versioni linguistiche mancanti ed esegue il workflow su ciascuna. Un unico ID tiene traccia dell'intero processo: interrogalo per monitorare lo stato di avanzamento di ogni lingua e verificare se è in attesa di revisione.

Per le esecuzioni successive, invia nuovamente il file corrente di una tabella di stringhe e Transept identificherà le modifiche: le stringhe invariate manterranno le traduzioni (e le eventuali revisioni già effettuate) e l'esecuzione interesserà solo le unità nuove o effettivamente modificate — la versione API di Traduci solo ciò che è cambiato. L'intero ciclo basato su chiavi, dall'importazione iniziale alle esecuzioni incrementali, è descritto in Localizzare un catalogo di stringhe tramite API.

Anziché ricorrere al polling, registra un URL e Transept invierà una notifica quando un'esecuzione termina o fallisce, una revisione è pronta per essere esaminata, l'elaborazione di un caricamento è completata o un'esportazione è disponibile. Ogni invio include un'intestazione HMAC-SHA256 X-Transept-Signature: t=…,v1=… affinché il destinatario possa verificare che la richiesta provenga effettivamente da noi; in caso di errore dell'endpoint, vengono effettuati nuovi tentativi con backoff prima della disattivazione.

# 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 può anche avviarsi automaticamente tramite un'automazione del database di Notion: punta il webhook dell'automazione verso l'URL del trigger e Transept eseguirà il workflow sulla pagina modificata. L'unico inconveniente è che i webhook di Notion non trasmettono mai il contenuto della pagina, ma indicano solo quale pagina ha attivato l'evento. Transept legge quella pagina tramite la tua connessione a Notion; pertanto, è necessario che siano soddisfatte due condizioni, altrimenti ogni attivazione verrà respinta con un errore di accesso e la scheda del trigger mostrerà il messaggio “impossibile leggere la pagina Notion”:

• Connetti Notion in Transept — in Impostazioni → Integrazioni. Si tratta del collegamento OAuth una tantum che permette a Transept di leggere i dati per tuo conto.
• Condividi il database di origine con l'integrazione all'interno di Notion — apri il database (o la pagina), clicca sul menu •••, scegli Connessioni e aggiungi Transept. Collegare Notion nelle Impostazioni non garantisce di per sé l'accesso a un database specifico; senza questo passaggio, la connessione è attiva ma la pagina rimane illeggibile.
• Attiva l'esecuzione al cambio di una proprietà, non solo alla modifica del corpo della pagina. Le automazioni di Notion si attivano in base alle modifiche delle proprietà (e all'aggiunta di pagine), quindi la sola modifica del corpo di una pagina potrebbe non avviare nulla. Il metodo più affidabile consiste nell'utilizzare una proprietà Stato monitorata dall'automazione: basta cambiarne lo stato (ad esempio in “Pronto per la traduzione”) e sarà proprio quel cambiamento a richiamare il trigger.

L'elenco completo degli endpoint è pubblicato come specifica OpenAPI che puoi importare in n8n, Zapier o in un generatore di codice: consulta il riferimento interattivo o scarica il JSON non elaborato. Preferisci una guida passo passo? Su transept.ai/developers trovi la guida rapida con esempi pronti da copiare, mentre la guida alle API di localizzazione illustra l'intero ciclo nel dettaglio. Le esecuzioni avviate tramite API vengono fatturate in base alle parole esattamente come nell'editor dell'app.

Sì — Transept dispone di un endpoint MCP a cui gli assistenti IA possono connettersi: https://app.transept.ai/api/public/v1/mcp. La connessione avviene tramite lo standard OAuth: aggiungi l'URL a Claude Code, Claude Desktop, Cursor o a qualsiasi client MCP e una finestra del browser ti chiederà di autorizzare l'accesso — senza alcuna chiave da incollare (l'uso di una chiave API come intestazione Bearer resta comunque valido per configurazioni CI e headless). L'assistente avrà quindi a disposizione gli strumenti per gestire l'intero ciclo: importare documenti, eseguire workflow in più lingue, gestire glossari e guide di stile, interrogare la memoria di traduzione e leggere i risultati. Sono integrate due misure di sicurezza: ogni strumento rispetta i permessi concessi e qualsiasi operazione che comporti un consumo di parole restituisce prima una stima del conteggio delle parole — l'assistente deve confermare esplicitamente prima di avviare l'esecuzione, così l'agente non potrà mai generare addebiti per errore. Gli snippet di configurazione pronti all'uso per ogni client sono disponibili nella pagina Integrazioni dell'app; la guida completa, dalla schermata di consenso alla disconnessione, è consultabile in Connetti il tuo assistente IA.