Automatyzacja Transept za pomocą API

Utwórz osobisty klucz API w sekcji Ustawienia → Deweloper. Jest on dostępny w każdym planie, również darmowym – nie ma tu żadnych dodatkowych barier, a jedynym ograniczeniem jest dostępna liczba słów. Nadaj kluczowi nazwę, opcjonalnie ustaw datę wygaśnięcia i skopiuj sekret, gdy się pojawi: zostanie on wyświetlony tylko raz i nie będzie można go później odzyskać. Klucz możesz unieważnić w dowolnym momencie na tej samej stronie.

Żądania są uwierzytelniane za pomocą klucza przesyłanego w nagłówku Authorization: Bearer tsk_live_… – wyłącznie w nagłówku, nigdy w adresie URL.

Zaledwie sześć krótkich wywołań pozwala przejść od klucza API do gotowego tłumaczenia. Tylko sam proces tłumaczenia zużywa słowa; wyceny są darmowe, a ponowne wywołanie z tym samym Idempotency-Key zwraca pierwotny wynik, zamiast naliczać opłatę dwukrotnie.

Te same wywołania z obszerniejszym komentarzem znajdziesz na stronie transept.ai/developers. Przewodnik po API lokalizacji omawia pozostałe kwestie: katalogi ciągów znaków, szablony e-maili, glosariusze, zespoły oraz etapy weryfikacji.

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"

Utwórz dokument z czystego tekstu, HTML-a lub Markdowna albo prześlij plik – obsługujemy te same formaty, co aplikacja. Możesz również zaimportować tabelę ciągów znaków (.tstrings.json): to ustrukturyzowany format dla tekstów interfejsu lub gier, w którym każdy ciąg stanowi jednostkę ze stałym kluczem i własnym kontekstem – informacją o tym, czym jest dany element, gdzie się wyświetla, jaki ma limit znaków i co oznaczają jego symbole zastępcze. Wszystkie te dane trafiają do modelu, symbole zastępcze takie jak {name} są chronione przed usunięciem lub zmianą nazwy, a formy liczby mnogiej są rozwijane odpowiednio dla każdego języka (jedna forma angielska zmienia się w dwie w języku niemieckim i cztery w ukraińskim). Wszelkie tłumaczenia zawarte już w pliku są importowane bez zmian, bezpłatnie i od razu zasilają pamięć tłumaczeniową.

Uruchomienie grupowe pozwala na tłumaczenie na wiele języków jednocześnie. Wskaż dokument, workflow lub szablon do uruchomienia oraz języki docelowe; Transept utworzy brakujące wersje językowe i uruchomi workflow w każdej z nich. Całość śledzi jeden identyfikator – odpytuj go, aby sprawdzać postępy poszczególnych języków oraz to, czy oczekują one na weryfikację.

Przy kolejnych uruchomieniach prześlij ponownie aktualny plik tabeli ciągów, a Transept sam ustali, co się zmieniło: niezmienione ciągi zachowają swoje tłumaczenia (wraz z wykonaną już weryfikacją), a proces obejmie tylko nowe lub faktycznie zmodyfikowane jednostki — to odpowiednik funkcji Uruchom tylko dla zmian od strony API. Cały cykl oparty na kluczach, od pierwszego importu po uruchomienia przyrostowe, opisuje poradnik Lokalizacja katalogu ciągów przez API.

Zamiast odpytywać serwer, zarejestruj adres URL, a Transept prześle zdarzenie, gdy proces zakończy się lub wystąpi błąd, gdy weryfikacja będzie gotowa do sprawdzenia, gdy zakończy się przetwarzanie przesłanego pliku oraz gdy eksport będzie gotowy. Każde powiadomienie zawiera nagłówek HMAC-SHA256 X-Transept-Signature: t=…,v1=…, co pozwala Twojemu serwerowi zweryfikować, że wiadomość faktycznie pochodzi od nas. Jeśli endpoint zwraca błąd, próby są ponawiane z rosnącymi odstępami czasu (backoff), zanim zostanie on wyłączony.

# 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

Workflow może również uruchamiać się automatycznie dzięki automatyzacji bazy danych Notion: skieruj webhook automatyzacji na adres URL wyzwalacza, a Transept uruchomi workflow na zmienionej stronie. Haczyk polega na tym, że webhook Notion nigdy nie przesyła treści strony — informuje jedynie o tym, która strona wywołała akcję. Transept odczytuje tę stronę poprzez Twoje połączenie z Notion, więc muszą zostać spełnione dwa warunki. W przeciwnym razie każde wywołanie zostanie odrzucone z błędem dostępu, a na karcie wyzwalacza pojawi się komunikat „nie udało się odczytać strony Notion”:

• Połącz Notion z Transeptem — w sekcji Ustawienia → Integracje. To jednorazowe połączenie OAuth, które pozwala Transeptowi odczytywać dane w Twoim imieniu.
• Udostępnij źródłową bazę danych integracji wewnątrz Notion — otwórz bazę danych (lub stronę), kliknij menu •••, wybierz Połączenia i dodaj Transept. Samo połączenie Notion w Ustawieniach nie daje dostępu do konkretnej bazy danych; bez tego kroku połączenie jest aktywne, ale strona pozostaje nieczytelna.
• Wywołuj akcję przy zmianie właściwości, a nie tylko edycji treści. Automatyzacje Notion reagują na zmiany właściwości (oraz dodanie strony), więc sama edycja treści strony może niczego nie uruchomić. Niezawodnym sposobem jest wykorzystanie właściwości Status, którą obserwuje automatyzacja — zmień jej wartość (np. na „Gotowe do tłumaczenia”), a ta zmiana wywoła wyzwalacz.

Pełna lista endpointów jest publikowana jako specyfikacja OpenAPI, którą możesz zaimportować do n8n, Zapiera lub generatora kodu: przejrzyj interaktywną dokumentację lub pobierz surowy plik JSON. Wolisz instrukcję krok po kroku? Pod adresem transept.ai/developers znajdziesz przewodnik „Szybki start” z przykładami gotowymi do skopiowania, a przewodnik po API lokalizacji szczegółowo opisuje cały cykl. Zadania uruchamiane przez API są rozliczane za słowa dokładnie tak samo, jak w edytorze w aplikacji.

Tak – Transept posiada endpoint MCP, z którym łączą się asystenci AI: https://app.transept.ai/api/public/v1/mcp. Połączenie wykorzystuje standardowy protokół OAuth: dodaj ten adres URL do Claude Code, Claude Desktop, Cursor lub dowolnego klienta MCP, a w oknie przeglądarki pojawi się prośba o zatwierdzenie dostępu – nie musisz wklejać żadnego klucza (klucz API w nagłówku Bearer nadal działa w przypadku CI i konfiguracji typu headless). Asystent zyskuje wtedy narzędzia do obsługi całego cyklu: importowania dokumentów, uruchamiania workflowów w różnych językach, zarządzania glosariuszami i przewodnikami stylistycznymi, przeszukiwania pamięci tłumaczeniowej oraz odczytywania wyników. W system wbudowano dwa mechanizmy ochronne: każde narzędzie respektuje przyznane przez Ciebie uprawnienia, a każda operacja wiążąca się ze zużyciem słów najpierw zwraca ich szacunkową liczbę – asystent musi ją wyraźnie potwierdzić przed rozpoczęciem zadania, więc agent nigdy nie obciąży Cię kosztami przez przypadek. Gotowe fragmenty konfiguracji dla każdego klienta znajdziesz w aplikacji na stronie Integracje; pełny opis procesu, od ekranu zgody po odłączanie, znajduje się w artykule Połącz swojego asystenta AI.