你的内容只有一种语言，用户却用多种语言阅读。这个 API 的意义，就在于以编程方式补上这道鸿沟：你发送文本，它返回译文，而且每次翻译都会经过一个只需配置一次的 本地化引擎。这个引擎会在每次调用中应用你的 术语表、品牌语气、指令 和 按语言区域选择模型——因此输出会遵循你团队设定的标准，而不是交给一个通用模型去猜。
这样一来，剩下的就只有一个问题：你一次要翻译多少内容。你可以在一次请求中翻译单个语言区域，并直接从响应中读取结果；也可以把多个语言区域交给平台，让它将每个语言区域作为独立的后台任务完成翻译，同时让你的应用始终保持响应。本页会介绍基础 URL、这个核心选择，以及接下来该看什么。
本 API 的前提
这是面向程序化翻译的参考文档。它默认你已经决定通过自己的代码或流程来完成本地化——而不是通过控制台——并且你已经拥有 API 密钥。第一次接触这个平台？最先需要理解的是 本地化引擎 这个概念；这里的所有能力都围绕它展开。
本页内容
基础 URL#
本参考文档中的所有 REST 端点都位于同一个主机下：
https://api.lingo.dev每个请求还需要携带一个请求头：X-API-Key。该密钥属于组织级作用域，并且只会在创建时显示一次；关于如何发送它的完整规则，请参阅 身份验证，关于请求被拒绝时会返回什么，请参阅 错误与状态码。
两种翻译方式#
两种模式背后都是同一个引擎，同一套术语表和品牌语气。区别只在于：等待由谁承担。
同步调用会翻译一组语言区域对，并在响应中返回译后数据。这是更简单的方式——一次请求，一次响应，无需你在自己这边运行任何端点——当你只需要一个语言区域，且可以接受一次往返等待时，它就是最合适的选择。
但内容很少只发布到一个语言区域。一个培训模块可能覆盖 14 种语言；一条 CMS 内容可能要分发到你销售覆盖的每个市场。如果你为每个语言区域分别发起一次同步调用，那你就得承担 14 次往返，以及其中某次失败时的重试逻辑；如果用一次同步调用等待全部结果，你又会被最慢的那一个拖住。因此，API 也提供异步模式：你只需连同目标语言区域一起 POST 一次内容，立即获得一个 202，然后平台会将每个语言区域作为独立的后台任务来翻译——由平台负责重试与故障隔离，而你的应用始终保持响应。
当任务规模太大、耗时太长，或者目标语言区域太多，不适合阻塞等待时，就选择异步。若你只需要一个语言区域对，并在一次响应中拿到结果，就选择同步。下方会先介绍异步相关页面，因为它承载的信息更多；但两者都不是所谓“真正的”API——它们只是同一个引擎的两种调用形态。
异步：多语言区域任务#
一次请求，覆盖所有语言区域；结果一完成就立即送达。异步 API 接收一次提交，为每个目标语言区域创建一个任务，并在各自完成的那一刻——通过 webhook 或 WebSocket——把结果交付给你，而无需让你的应用为此阻塞。
同步：一次请求，一次响应#
当你只需要一个语言区域对，并且可以等待这次往返时，调用同步端点并直接从响应中读取结果——无需 webhook 端点，也无需轮询。
后续步骤#
无论你选择哪种模式，背后的引擎都由你掌控。先创建一个密钥，然后定义这个引擎在每次调用中的行为——它为各语言区域选择的模型，以及那些必须精确翻译的术语。
