APIでTranseptを自動化する

設定 → 開発者で個人のAPIキーを作成します。APIキー、MCP、WebhookはStarterプランとProプランで利用できます。Freeプランでは、このページに作成ボタンの代わりにアップグレードの案内が表示されます。利用量の上限を決めるのはクレジット残高です。キーに名前を付け、必要に応じて有効期限を設定したら、表示されたシークレットをコピーしてください。シークレットが表示されるのは1回のみで、後から確認できません。キーは同じページからいつでも失効させられます。Freeプランに移行しても、失効させられるようにキーは一覧に残りますが、StarterプランかProプランに戻るまでは使えません。

リクエストは、Authorization: Bearer tsk_live_…ヘッダーにキーを入れて認証します。キーは必ずヘッダーに入れ、URLには含めないでください。

わずか6回のリクエストで、APIキーの取得から翻訳の出力まで完了します。クレジットが消費されるのは実行（翻訳、チェック、または用語集やスタイルガイドの作成）そのものだけで、見積もりは無料です。同じ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 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"

ドキュメントは、書式なしテキスト、HTML、Markdownから作成するか、ファイルをアップロードして作成します。対応形式はアプリと同じです。文字列テーブル（.tstrings.json）もインポートできます。UIテキストやゲーム内の文字列のための構造化フォーマットで、各文字列は固定のキーとそれぞれのコンテキスト（その文字列が何か、どこに表示されるか、文字数の上限、プレースホルダーの意味などのメモ）を持つ1つの単位（ユニット）です。これらの情報はすべてモデルに渡され、{name}のようなプレースホルダーが消えたり名前が変わったりしないよう保護されます。複数形は言語ごとに展開されます（英語の1つの形が、ドイツ語では2つ、ウクライナ語では4つになります）。ファイルにすでに含まれている訳文はそのまま無料でインポートされ、すぐに翻訳メモリに反映されます。

グループ実行を使うと、一度に複数の言語へ翻訳できます。ドキュメント、実行するワークフローまたはテンプレート、翻訳先の言語を指定すると、Transeptがまだない言語バージョンを作成し、それぞれでワークフローを実行します。全体は1つのIDで追跡できます。このIDをポーリングすれば、各言語の進み具合や、レビュー待ちかどうかを確認できます。

繰り返し実行する場合は、文字列テーブルの最新ファイルを再送信すると、Transeptが変更箇所を自動的に特定します。変更のない文字列は既存の訳文（および完了済みのレビュー）をそのまま保持し、実行の対象になるのは新しいユニットと実際に変更されたユニットだけです。これは変更箇所のみを実行のAPI版にあたります。初回のインポートから差分実行まで、キーを使った一連の流れ全体は、API経由で文字列カタログをローカライズするで説明しています。

ポーリングする代わりにURLを登録しておくと、実行の完了や失敗、レビューの準備完了、アップロードの処理完了、エクスポートの準備完了時に、Transeptからイベントがプッシュ送信されます。各配信にはHMAC-SHA256のX-Transept-Signature: t=…,v1=…ヘッダーが付くため、受信側でTranseptから送信された正規のリクエストであることを検証できます。配信に失敗するエンドポイントには間隔を空けながら再送を試み、それでも失敗が続く場合は無効化します。

# 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データベースのオートメーションから自動実行することもできます。オートメーションのWebhookの送信先にトリガーURLを指定すると、変更されたページに対してTranseptがワークフローを実行します。ただし、NotionのWebhookはページのコンテンツを送らず、どのページで発生したかだけを知らせます。Transeptはそのページをご自分のNotion連携を通して読み込むため、次の2つがどちらもそろっている必要があります。そろっていないと、トリガーのたびにアクセスエラーで処理が拒否され、トリガーカードに「Notionページを読み取れませんでした」というメモが表示されます。

• TranseptでNotionを連携する：設定 → 連携機能から連携します。Transeptが代わりにページを読み取れるようにする、一度だけのOAuth連携です。
• Notion側でインテグレーションに対象データベースを共有する：対象のデータベース（またはページ）を開き、•••メニューからコネクトを選んでTranseptを追加します。「設定」でNotionを連携しただけでは、特定のデータベースへのアクセス権は付与されません。この手順を省くと、連携自体は有効でもページを読み込めないままになります。
• 本文の編集だけでなく、プロパティの変更で実行する：Notionのオートメーションはプロパティの変更（およびページの追加）でトリガーされるため、ページの本文を編集しただけでは何も実行されない場合があります。確実なのは、オートメーションが監視するステータスプロパティを使う方法です。ステータスを（たとえば「翻訳準備完了」に）切り替えると、その変更がトリガーを呼び出します。

エンドポイントの全一覧は、n8n、Zapier、コードジェネレーターにインポートできるOpenAPI仕様として公開しています。インタラクティブなAPIリファレンスで確認するか、生のJSONを取得してください。手順に沿って知りたい場合は、コピーしてそのまま使えるサンプル付きのクイックスタートがtransept.ai/developersにあり、一連の流れ全体はローカライズAPIガイドで詳しく解説しています。API経由で開始した実行も、アプリ内のエディターとまったく同じようにクレジットを消費します。

はい、利用できます。TranseptにはAIアシスタントが接続できるMCPエンドポイント（https://app.transept.ai/api/public/v1/mcp）が用意されています。接続には標準のOAuthを使用します。Claude Code、Claude Desktop、Cursor、または任意のMCPクライアントにこのURLを追加すると、ブラウザーウィンドウが開いてアクセスの承認を求められます。キーを貼り付ける必要はありません（CIやヘッドレス環境では、BearerヘッダーでAPIキーを渡す方法も引き続き使えます）。接続すると、アシスタントは一連の作業全体に対応したツールを使えるようになります。ドキュメントのインポート、複数言語でのワークフロー実行、用語集とスタイルガイドの管理、翻訳メモリの検索、結果の取得などです。安全のための仕組みも2つ組み込まれています。すべてのツールは付与された権限の範囲内で動作し、クレジットを消費する処理は必ず先にクレジットの見積もりを返します。実行を始める前にアシスタントが明示的に確認する必要があるため、エージェントが意図せず課金することはありません。クライアントごとの設定スニペットは、アプリ内の連携機能ページに用意されています。承認画面から連携解除までの手順全体については、AIアシスタントの接続をご覧ください。