Transept mit der API automatisieren

Erstellen Sie unter Einstellungen → Entwickler einen persönlichen API-Key. API-Keys, MCP und Webhooks sind in jedem kostenpflichtigen Tarif enthalten (Lite, Starter und Pro); im Free-Tarif wird auf dieser Seite anstelle einer Erstellen-Schaltfläche ein Upgrade-Hinweis angezeigt. Die Nutzung wird allein durch Ihr Guthaben begrenzt. Geben Sie dem Key einen Namen, legen Sie optional ein Ablaufdatum fest und kopieren Sie das Secret, sobald es angezeigt wird: Es erscheint nur einmal und kann später nicht mehr abgerufen werden. Auf derselben Seite können Sie einen Key jederzeit widerrufen. Wenn Sie zum Free-Tarif wechseln, bleiben Ihre Keys aufgeführt, damit Sie sie widerrufen können, sie funktionieren jedoch erst wieder, sobald Sie zu einem kostenpflichtigen Tarif zurückkehren.

Anfragen werden über den Key im Authorization: Bearer tsk_live_…-Header authentifiziert – ausschließlich im Header, niemals in einer URL.

Sechs kurze Aufrufe bringen Sie vom API-Key zum übersetzten Ergebnis. Nur die Runs selbst kosten Credits (Übersetzen, Überprüfen oder Erstellen eines Glossars oder Styleguides); Schätzungen sind kostenlos, und ein wiederholter Aufruf mit demselben Idempotency-Key gibt das ursprüngliche Ergebnis zurück, statt doppelt abzurechnen.

Dieselben Aufrufe mit ausführlicheren Erläuterungen finden Sie unter transept.ai/developers. Der Leitfaden zur Lokalisierungs-API führt Sie durch den Rest: String-Kataloge, E-Mail-Vorlagen, Glossare, Teams und Review-Gates.

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 credit 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 credit 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"

Erstellen Sie Dokumente aus Rohtext, HTML oder Markdown oder laden Sie eine Datei hoch – unterstützt werden dieselben Formate wie in der App. Sie können auch eine String-Tabelle (.tstrings.json) importieren: ein strukturiertes Format für UI-Texte oder Game-Strings, bei dem jeder String eine Einheit mit festem Key und eigenem Kontext darstellt – einer Notiz dazu, worum es sich handelt, wo der Text erscheint, einer Zeichenbegrenzung und der Bedeutung seiner Platzhalter. All das erreicht das Modell; Platzhalter wie {name} sind vor Löschung oder Umbenennung geschützt, und Pluralformen werden sprachspezifisch erweitert (aus einer englischen Form werden zwei im Deutschen und vier im Ukrainischen). Bereits im Dokument enthaltene Übersetzungen werden kostenlos und unverändert übernommen und fließen direkt in das Translation Memory ein.

Ein Gruppenlauf übersetzt gleichzeitig in mehrere Sprachen. Geben Sie das Dokument, den auszuführenden Workflow oder die Vorlage sowie die Zielsprachen an; Transept erstellt alle fehlenden Sprachversionen und führt den Workflow für jede einzelne aus. Eine einzige ID dient zur Nachverfolgung des gesamten Vorgangs – rufen Sie darüber den Fortschritt der jeweiligen Sprachen ab und prüfen Sie, ob ein Review aussteht.

Bei wiederholten Läufen übermitteln Sie die aktuelle Datei einer String-Tabelle erneut, und Transept analysiert die Änderungen: Unveränderte Strings behalten ihre Übersetzungen (einschließlich bereits abgeschlossener Reviews), und der Lauf verarbeitet nur neue oder tatsächlich geänderte Einheiten – die API-Entsprechung zu Nur Geändertes ausführen. Der gesamte schlüsselbasierte Prozess, vom ersten Import bis hin zu Delta-Läufen, wird in Lokalisierung eines String-Katalogs über die API ausführlich beschrieben.

Anstatt Polling zu nutzen, registrieren Sie eine URL, und Transept sendet ein Event per Push, sobald ein Lauf abgeschlossen wurde oder fehlgeschlagen ist, ein Review zur Ansicht bereitsteht, die Verarbeitung eines Uploads beendet ist oder ein Export bereitliegt. Jede Zustellung enthält einen HMAC-SHA256-Header X-Transept-Signature: t=…,v1=…, damit Ihr Empfänger verifizieren kann, dass die Nachricht tatsächlich von uns stammt. Schlägt der Aufruf eines Endpunkts fehl, wird er mit einem Backoff-Verfahren wiederholt, bevor er deaktiviert wird.

# 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

Ein Workflow kann auch über eine Notion-Datenbank-Automatisierung gestartet werden: Richten Sie den Webhook der Automatisierung auf die Trigger-URL, und Transept führt den Workflow auf der geänderten Seite aus. Der Haken dabei ist, dass ein Notion-Webhook niemals den Inhalt der Seite überträgt – er meldet nur, welche Seite die Aktion ausgelöst hat. Transept liest diese Seite über Ihre Notion-Verbindung ein. Daher müssen zwei Voraussetzungen erfüllt sein, sonst wird jeder Aufruf mit einem Zugriffsfehler abgelehnt und auf der Trigger-Karte erscheint der Hinweis „Notion-Seite konnte nicht gelesen werden“:

• Notion in Transept verbinden – unter Einstellungen → Integrationen. Das ist die einmalige OAuth-Verknüpfung, über die Transept in Ihrem Namen Lesezugriff erhält.
• Geben Sie die Quelldatenbank innerhalb von Notion für die Integration frei – öffnen Sie die Datenbank (oder Seite), klicken Sie auf das •••-Menü, wählen Sie Verbindungen und fügen Sie Transept hinzu. Die Verknüpfung von Notion in den Einstellungen allein gewährt noch keinen Zugriff auf eine bestimmte Datenbank; ohne diesen Schritt ist die Verbindung zwar aktiv, die Seite bleibt jedoch unlesbar.
• Auslösung bei Eigenschaftsänderungen, nicht nur bei Inhaltsbearbeitungen. Notion-Automatisierungen reagieren auf Änderungen von Eigenschaften (und das Hinzufügen von Seiten). Das reine Bearbeiten des Seiteninhalts allein löst daher unter Umständen nichts aus. Die zuverlässigste Methode ist eine Status-Eigenschaft, die von der Automatisierung überwacht wird – stellen Sie diese um (z. B. auf „Bereit zur Übersetzung“), und genau diese Änderung löst den Trigger aus.

Die vollständige Liste der Endpunkte wird als OpenAPI-Spezifikation bereitgestellt, die Sie in n8n, Zapier oder einen Code-Generator importieren können: Sehen Sie sich die interaktive Referenz an oder rufen Sie das JSON-Rohformat ab. Bevorzugen Sie eine Schritt-für-Schritt-Anleitung? Unter transept.ai/developers finden Sie den Schnellstart mit Beispielen zum Kopieren und Einfügen, und der Leitfaden zur Lokalisierungs-API deckt den gesamten Prozess ausführlich ab. Über die API gestartete Läufe rechnen Credits genauso ab wie der Editor in der App.

Ja – Transept verfügt über einen MCP-Endpunkt, mit dem sich KI-Assistenten verbinden können: https://app.transept.ai/api/public/v1/mcp. Die Verbindung nutzt standardmäßiges OAuth: Fügen Sie die URL zu Claude Code, Claude Desktop, Cursor oder einem beliebigen MCP-Client hinzu, und ein Browserfenster fordert Sie auf, den Zugriff zu bestätigen – ganz ohne API-Schlüssel, den Sie kopieren und einfügen müssten (ein API-Schlüssel als Bearer-Header funktioniert für CI- und Headless-Setups weiterhin). Der Assistent verfügt dann über Tools für den gesamten Ablauf: Dokumente importieren, Workflows sprachenübergreifend ausführen, Glossare und Styleguides verwalten, das Translation Memory abfragen und Ergebnisse zurücklesen. Zwei Sicherheitsmechanismen sind fest integriert: Jedes Tool berücksichtigt die von Ihnen erteilten Berechtigungen, und jede Aktion, die Credits verbrauchen würde, gibt zunächst die geschätzten Credits zurück – der Assistent muss den Vorgang explizit bestätigen, bevor ein Lauf startet, sodass ein Agent niemals versehentlich Kosten verursachen kann. Fertige Einrichtungs-Snippets für jeden Client finden Sie in der App auf der Seite Integrationen; die vollständige Anleitung vom Zustimmungsdialog bis zum Trennen der Verbindung finden Sie unter Ihren KI-Assistenten verbinden.