文本翻译 API

此 API 通过排队作业翻译文本，每个作业对应一种目标语言。提交文本后，请保存返回的作业 ID，并持续获取作业信息，直到处理完成。所有请求均须通过 HTTPS 发送，并使用您的账户凭据：可使用示例中的 HTTP Basic 凭据，也可使用 API 令牌，详见身份验证。请将凭据保存在您的服务器上。

端点

两个 API 主机https://api.multi.tel和兼容主机https://api.multitel.net共享同一账户范围内的作业、幂等键、限制和计费。它们的响应封装格式不同，因此请始终使用同一主机及与其匹配的解析器。

在api.multi.tel上，所有路径还可以使用前缀/v1/translate替换/v3/translate。在api.multitel.net上，请使用/v3/translate路径。

服务信息响应报告以下字段：enabled, paidEnabled, mode（batch）、realtime（false）、maxSourceCharacters（20000）、cpuLanguages和ratesNanosPerCharacter。cpuLanguages列出标准翻译接受的基础语言代码。ratesNanosPerCharacter提供各引擎配置的每个源文本码点的价格，以十亿分之一美元为单位：值为 5000 表示每百万码点 $5。该响应不报告增强翻译当前是否可用；不可用时，增强翻译的费用估算返回 503。读取此信息免费。

翻译文本

使用Content-Type: application/json将 JSON 发送至POST https://api.multi.tel/v3/translate。每个作业对应一种目标语言，因此请为每种目标语言单独提交一个作业。

语言区域代码为 BCP 47 标签，由 2 到 63 个字母、数字和连字符组成。它们会被规范化，因此en-us记录为en-US。无效标签以及und, mul或zxx会返回 400 invalid_translation_language。标准翻译的可用性按基础语言检查，nb和nn均视为no。区域目标标签（例如fr-CA）会被接受并记录，但标准输出遵循基础语言，不保证体现区域用语。

此主机的请求体应保持在 128 KiB 以内。请以 UTF-8 发送文本，不要将每个非 ASCII 字符都转义为\u序列，否则可能使 20,000 字符的请求超出限制。

请求体只接受这四个字段。其他任何属性都会被拒绝，返回 400 invalid_translation_request，包括idempotency_key、所有者 ID、免费处理标记和分段数组。

幂等性与复用

每次提交都需要一个Idempotency-Key请求头，其长度为 1 到 190 个字符。请使用 ASCII 字母、数字、-, _, .和:，且不要带有前导或尾随空格；缺少键或键长度为 191 个字符及以上时，将被拒绝并返回 400。键的作用范围为您的账户和翻译服务，涵盖两个主机及该账户的所有凭据。

• 使用相同键及相同文本、规范化后的语言和引擎时，会返回现有作业、HTTP 200 和duplicate: true，不会再次收费。
• 使用相同键但文本、语言或引擎不同时，会返回 409 idempotency_conflict。如果处理版本在作业创建后发生变化，使用同一键也会返回 409。此时，请按 ID 读取原作业，不要重新提交。
• 使用新键及相同文本、规范化后的语言和引擎时，如果具有相同内容及当前处理版本的作业处于排队、运行、已完成或等待付款状态，则会返回现有作业、HTTP 200 和duplicate: true，不会新增处理费用。复用的待付款作业仍需结算。失败作业不会被复用：系统会创建新作业，并在其完成时收费。

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

新作业返回 HTTP 202。示例文本有 57 个码点，按每百万码点 $5 计算，费用为 $0.000285。简略响应如下（标识符为示例）：

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

提交还可能返回：402 insufficient_balance，表示预付余额不足以支付该作业及其他尚未结清作业的费用；以及 429 translation_queue_full，表示您的账户或服务有过多未完成作业。以下情况返回 503：

• paid_translation_not_enabled：付费翻译已停用。
• translation_unavailable：请求增强翻译时，增强翻译不可用。
• translation_pricing_unavailable：所选引擎未配置费率。

收到 429 和 503 响应时，请稍后使用相同键重试。

选择质量

长文本会被分成小段处理后重新拼接。换行和间距可能变化，句子跨越处理分界处时可能失去上下文。请保留原文并复核拼接后的结果。标准翻译使用区域标签的基础语言；接受并记录标签不保证使用区域用语。

标准翻译在 CPU 工作进程上运行。增强翻译将文本发送至已配置的外部 AI 服务。输出仍需复核；服务不保证某个引擎对所有语言对或文本类型都更准确。

标准翻译提供草稿，其质量和处理时间因语言对而异。增强翻译适合注重上下文的文本，但仍需核对重要姓名、数字、否定表述和承诺。两种选项都不会修复原始转录文本中已有的错误，因此请保留原文以便对照。

使用GET /v3/translate在同一 API 主机上检查当前可用性、标准翻译支持的语言和已配置费率。标准请求的源语言或目标语言的基础语言不在cpuLanguages中时，会返回 422 translation_language_pair_unavailable。如果提供了source_language且其基础语言与目标语言相同，请求会返回 409 translation_same_language，而不会创建作业。增强翻译单独启用：不可用时，增强翻译的提交和费用估算均返回 503。

先估算费用

在api.multi.tel上，将相同的 JSON 请求体发送至POST /v3/translate/estimate。不需要幂等键。费用估算执行相同的验证，包括 422 和 409 检查，但不会创建作业、翻译文本、预留资金、检查余额或向账户收费。成功时返回 HTTP 200，字段包括estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd和costUsd，均位于data下。对于上文示例，costUsd按标准费率为0.000285000。增强翻译不可用时，增强翻译的费用估算返回 503 service_unavailable。估算使用当前配置的费率。作业创建时费率即固定，作业费用按该费率计算。

获取翻译结果

新提交返回 HTTP 202，现有或复用作业返回 HTTP 200。请保存data.id并使用共用的作业流程。作业对象包含以下字段：

• id, status, engine, sourceLocale和targetLocale。
• sourceCharacters, costUsd, costIsEstimate和pricePerMillionCharactersUsd。
• progress和createdAt。
• modelVersion，不透明的处理版本字符串。
• duplicate用于返回复用作业的响应。
• failureCode用于失败作业：translation_failed, translation_timeout, input_failed或worker_lease_lost。

失败作业的costUsd显示为零。

已完成作业包含data.result，其中有sourceLocale（未提供源语言时为空）、targetLocale、翻译后的text（以换行连接的分段文本）以及segments。对于通过此 API 提交的文本，segments包含一个条目，其中有翻译后的text和目标language。待付款作业的结果在结算前不会提供。

使用 api.multitel.net

兼容端点POST https://api.multitel.net/v3/translate接受相同的 JSON 字段和相同的Idempotency-Key请求头。若请求头不存在，也接受 JSON 请求体中的idempotency_key字符串。其他额外字段均被拒绝，返回 400 unsupported_translation_option。此主机的原始请求体最大为 256,000 字节，超过 20,000 码点的文本返回 413 translation_too_large，而非 400。空的source_language视为省略。429 响应包含Retry-After: 15。此主机还会返回以下错误：

• 400 json_body_required：请求体缺失、JSON 无效或为 JSON 标量。请发送 JSON 对象。
• 400 invalid_translation_options：当text, target_language或engine缺失、为空或不是字符串，或者source_language不是字符串时。
• 400 invalid_translation_text：文本全为空白。
• 400 invalid_translation_engine：未知引擎。
• 400 idempotency_key_required：缺少键、键为空或过长，或者idempotency_key不是字符串。
• 400 invalid_job：作业 ID 格式错误。

此主机的翻译服务响应采用封装格式{"status":{"code":HTTP_STATUS},"response":{...}}，其中status是对象。请从response.id中读取作业 ID，从response.result中读取已完成的结果。出错时，代码位于response.code中，不附带消息或请求 ID。身份验证失败（401）由此主机的通用登录检查返回，响应体可能不同，因此请在解析前检查 HTTP 状态。作业与主主机共享，但轮询、结算和用量查询应使用同一主机，使解析器与封装格式匹配。此主机也在/v3/translate/estimate接受相同的 JSON 字段，无需幂等键，估算结果位于response中。