Автоматизація Transept за допомогою API

Створіть персональний API-ключ у розділі Налаштування → Розробникам. Він доступний на всіх тарифних планах, включно з безкоштовним — жодних додаткових перешкод немає, а використання обмежується лише вашим балансом слів. Дайте ключу назву, за потреби встановіть термін дії та скопіюйте секретний ключ, коли він з'явиться: він відображається лише один раз, і пізніше його неможливо буде отримати знову. Відкликати ключ можна будь-коли на цій же сторінці.

Запити автентифікуються за допомогою ключа в заголовку Authorization: Bearer tsk_live_… — лише в заголовку, ніколи в URL-адресі.

Усього шість коротких запитів — і ви отримаєте готовий переклад. Списання слів відбувається лише за сам запуск перекладу; попередня оцінка безкоштовна, а повторний запит із тим самим Idempotency-Key повертає початковий результат замість повторного списання.

Ці ж запити з детальнішими поясненнями доступні на transept.ai/developers. Посібник з API для локалізації розповідає про решту можливостей: каталоги рядків, шаблони листів, глосарії, команди та етапи перевірки.

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"

Створюйте документи зі звичайного тексту, HTML чи markdown або завантажуйте файли — підтримуються ті самі формати, що й у додатку. Також можна імпортувати таблицю рядків (.tstrings.json) — структурований формат для тексту інтерфейсу чи ігрових рядків, де кожен рядок є окремим елементом зі стабільним ключем і власним контекстом: приміткою про призначення, місце відображення, ліміт символів та значення плейсхолдерів. Уся ця інформація надходить до моделі; плейсхолдери на кшталт {name} захищені від видалення чи перейменування, а форми множини розгортаються залежно від мови (одна англійська форма стає двома в німецькій та чотирма в українській). Будь-які наявні у файлі переклади імпортуються «як є» безкоштовно й одразу наповнюють пам'ять перекладів.

Груповий запуск дозволяє перекладати кількома мовами одночасно. Вкажіть документ, воркфлоу або шаблон для запуску та цільові мови; Transept створить відсутні мовні версії та запустить воркфлоу для кожної з них. Увесь процес відстежується за одним ID — опитуйте його, щоб дізнатися про прогрес кожної мови та чи очікує вона на перевірку.

Для повторних запусків надішліть поточний файл таблиці рядків ще раз, і Transept сам визначить, що змінилося: незмінені рядки збережуть свої переклади (і вже пройдені перевірки), а запуск торкнеться лише нових або дійсно змінених елементів — це API-версія функції Запускати лише для зміненого контенту. Весь цикл роботи з ключами, від першого імпорту до дельта-запусків, описано в розділі Локалізація каталогу рядків через API.

Замість того, щоб постійно опитувати API, зареєструйте URL-адресу, і Transept сам надсилатиме сповіщення, коли запуск завершиться чи перерветься через помилку, коли переклад буде готовий до рецензування, коли завершиться обробка завантаженого файлу або коли буде готовий експорт. Кожне повідомлення містить заголовок HMAC-SHA256 X-Transept-Signature: t=…,v1=…, щоб ваш сервер міг підтвердити, що запит справді надійшов від нас. Якщо кінцева точка не відповідає, система повторюватиме спроби з поступовим збільшенням інтервалу, перш ніж її буде вимкнено.

# 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

Воркфлоу також може запускатися автоматично за допомогою автоматизації бази даних Notion: спрямуйте вебхук автоматизації на URL-адресу тригера, і Transept запустить воркфлоу для сторінки, у якій відбулися зміни. Нюанс у тому, що вебхук Notion ніколи не передає вміст сторінки — він лише повідомляє, яка саме сторінка спрацювала. Transept зчитує цю сторінку через ваше підключення до Notion, тому мають бути виконані обидві умови. Інакше кожен запуск буде відхилено через помилку доступу, а на картці тригера з’явиться примітка «не вдалося зчитати сторінку Notion»:

• Підключіть Notion у Transept — у розділі Settings → Integrations. Це одноразове OAuth-підключення, яке дозволяє Transept зчитувати дані від вашого імені.
• Надайте інтеграції доступ до бази даних у Notion — відкрийте базу даних (або сторінку), натисніть на її меню •••, виберіть Connections і додайте Transept. Підключення Notion у налаштуваннях саме по собі не надає доступу до конкретної бази даних; без цього кроку з’єднання буде активним, але сторінка залишиться недоступною для читання.
• Налаштуйте запуск на зміну властивості, а не лише тексту. Автоматизації Notion спрацьовують при зміні властивостей (та додаванні сторінок), тому саме лише редагування тексту сторінки може не активувати тригер. Надійний метод — властивість Status, за якою стежить автоматизація: змініть її значення (наприклад, на «Ready to translate»), і саме ця зміна активує тригер.

Повний список кінцевих точок опубліковано у форматі специфікації OpenAPI, яку можна імпортувати в n8n, Zapier або генератор коду: перегляньте інтерактивну документацію або завантажте необроблений JSON. Бажаєте покрокову інструкцію? На сторінці transept.ai/developers є посібник із швидкого старту з прикладами для копіювання, а посібник із API для локалізації детально описує весь цикл роботи. Запуски через API тарифікуються за кількістю слів так само, як і в редакторі додатка.

Так, Transept має кінцеву точку MCP, до якої підключаються ШІ-асистенти: https://app.transept.ai/api/public/v1/mcp. Для підключення використовується стандартний OAuth: додайте URL-адресу до Claude Code, Claude Desktop, Cursor або будь-якого MCP-клієнта, і у вікні браузера з’явиться запит на підтвердження доступу — вам не потрібно копіювати жодних ключів (хоча API-ключ у заголовку Bearer усе ще підтримується для CI та headless-систем). Після цього асистент отримає інструменти для повного циклу роботи: імпорт документів, запуск воркфлоу різними мовами, керування глосаріями та посібниками зі стилю, пошук у пам’яті перекладів та зчитування результатів. У системі передбачено два запобіжники: кожен інструмент діє відповідно до наданих вами дозволів, а будь-яка дія, що передбачає витрату слів, спочатку повертає оцінку їхньої кількості — асистент має отримати ваше явне підтвердження перед початком запуску, тож агент ніколи не спише кошти випадково. Готові фрагменти коду для налаштування кожного клієнта доступні на сторінці Integrations у додатку; повну інструкцію — від екрана надання доступу до відключення — наведено в розділі Підключіть свого ШІ-асистента.