使用 API 自动化 Transept

在设置 → 开发者中创建个人 API 密钥。所有方案（包括免费版）均可使用——没有单独的门槛，使用限制仅取决于你的字数余额。为密钥命名，可选择设置有效期，并在显示时复制密钥：它仅会出现一次，且无法再次找回。你可以随时在同一页面撤销密钥。

请求通过 Authorization: Bearer tsk_live_… 请求头中的密钥进行身份验证——仅限请求头，切勿包含在 URL 中。

只需六次简短的调用，即可完成从 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 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 创建文档，也可以上传文件 —— 支持格式与 App 一致。您还可以导入字符串表 (.tstrings.json)：这是一种用于 UI 文本或游戏字符串的结构化格式，其中每个字符串都是一个拥有固定键和独立上下文的单元 —— 即关于该字符串用途、出现位置、字符限制以及占位符含义的说明。所有这些信息都会提供给模型，像 {name} 这样的占位符会受到保护，防止被遗漏或重命名，复数形式也会根据语言规则进行扩展（英语的一种形式在德语中对应两种，在乌克兰语中对应四种）。文件中已有的任何翻译都会被原样导入，不计入费用，并立即填充到翻译记忆库中。

批量运行可一次性翻译成多种语言。只需指定文档、要运行的工作流或模板以及目标语言，Transept 就会创建所有缺失的语言版本，并对各版本分别运行工作流。通过一个 ID 即可跟踪全程——您可以轮询该 ID 以获取每种语言的进度，并确认其是否正在等待审核。

对于重复运行，只需重新提交字符串表的当前文件，Transept 就会自动识别变化：未更改的字符串将保留其翻译（以及已完成的审核），运行仅处理新增或确实发生变化的单元——这就是 仅运行已更新内容 在 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 数据库自动化自动运行：将自动化的 Webhook 指向触发器 URL，Transept 就会对发生更改的页面运行工作流。但问题在于，Notion 的 Webhook 从不携带页面内容，它只告知是哪个页面触发了操作。Transept 需要通过您的 Notion 连接来读取该页面，因此必须满足以下两个条件，否则每次触发都会因访问错误而被拒绝，且触发器卡片会显示“无法读取 Notion 页面”的提示：

• 在 Transept 中连接 Notion —— 位于设置 → 集成。这是一次性 OAuth 链接，允许 Transept 代表您读取内容。
• 在 Notion 中将源数据库共享给该集成 —— 打开数据库（或页面），点击其 ••• 菜单，选择 Connections，然后添加 Transept。仅在“设置”中连接 Notion 本身并不会自动授予对特定数据库的访问权限；如果不执行此步骤，虽然连接已激活，但页面依然无法读取。
• 通过属性更改触发，而非仅修改正文。 Notion 自动化会在属性更改（以及新增页面）时触发，因此仅编辑页面正文可能不会触发任何操作。比较稳妥的做法是设置一个供自动化监控的 Status 属性——只需切换该属性（例如切换为“Ready to translate”），即可通过这一更改来触发调用。

完整的端点列表以 OpenAPI 规范的形式发布，您可以将其导入 n8n、Zapier 或代码生成器：请浏览交互式参考文档，或获取原始 JSON。想要查看分步指南？transept.ai/developers 提供了包含可直接复制示例的快速入门，而本地化 API 指南则深入讲解了整个流程。通过 API 启动的运行将与应用内编辑器一样，严格按字数计费。

是的 —— Transept 提供了一个供 AI 助手连接的 MCP 端点：https://app.transept.ai/api/public/v1/mcp。连接过程采用标准的 OAuth 协议：将该 URL 添加到 Claude Code、Claude Desktop、Cursor 或任何 MCP 客户端，随后浏览器窗口会请求您授权访问 —— 无需手动粘贴密钥（对于 CI 和无头设置，使用 API 密钥作为 Bearer 请求头依然有效）。之后，助手将拥有一套涵盖完整流程的工具：导入文档、跨语言运行工作流、管理术语表和风格指南、查询翻译记忆库以及读取结果。系统内置了两项防护机制：所有工具都会遵循您授予的权限；此外，任何涉及字数消耗的操作都会先返回预估字数 —— 助手必须在运行开始前进行明确确认，因此智能体绝不会在无意中产生费用。应用内的集成页面提供了针对各客户端的现成配置代码片段；从授权页面到断开连接的完整步骤详见连接您的 AI 助手。