实时翻译

同步翻译一小批文本，秒级返回译文。不产生任务、不入项目库、不进发布版本、不下发到 SDK。

这是开放平台唯一的同步翻译接口。它和 创建翻译任务 是两件不同的事：

	实时翻译	创建翻译任务
返回方式	同步，秒级拿到译文	异步，返回 task_id 后轮询 / 等回调
结果去向	只在响应里，不留任何痕迹	入项目库，可审校、可发布、可导出、SDK 可拉取
规模	一次 ≤ 50 条	单任务可数万条
质量流程	术语注入 + 确定性结构校验	完整流程：术语扫描 → 翻译 → QA 打分 → 智能优化
重复内容	7 天译文缓存，命中免费秒回	每次都是新任务

要把译文正式纳入项目，必须用 /tasks/create，本接口做不到。

使用时机

• 用户想马上看某几句的翻译效果，不值得为此建一个任务
• 客服 / 运营后台需要即时给出一个译文
• 接入 AI Agent（MCP 工具 loxily_translate），让它在对话里直接回答"这句话英文怎么说"

请求地址

POST {BASE_URL}/api/open/v1/translate

鉴权 Header

和 创建翻译任务 完全一样。

请求参数（Body）

参数	类型	必填	说明
texts	string[]	是	待翻译源文，最多 50 条，每条 ≤ 2000 字符。空白项会被忽略
source_language	string	否	源语言。留空 = 项目语言树的根语言
target_language	string	二选一	目标语言，常规用法就是它 —— 一次翻一种
target_languages	string[]	二选一	进阶：一次翻多种，最多 10 种。与 target_language 不能同传
mode	string	否	standard（默认）或 fast，见下
glossary	object[]	否	自带术语，最多 200 条，见下
no_cache	boolean	否	跳过译文缓存、强制重译，默认 false

mode：两档的取舍

	standard（默认）	fast
术语库	匹配后注入提示词，术语译法与项目一致	不注入
额外开销	一轮并发的术语查询	无，直接调模型

术语是这条接口的默认能力，standard 档只比 fast 多一轮并发的术语查询。除非你确定这批文案里没有任何专有名词，否则不必切到 fast。

目标语言：默认一次一种

target_language（单数）是常规用法，一次翻一种语言：

{ "texts": ["确定要退出战斗吗？"], "target_language": "en" }

一次翻多种是进阶用法，用 target_languages（最多 10 种）：

{ "texts": ["确定要退出战斗吗？"], "target_languages": ["en", "ja", "ko"] }

两者不能同传，也不能都不传 —— 本接口没有"留空 = 翻成项目全部语言"这种默认行为。

多语言在速度上几乎不吃亏（各语言并发，12 种与 1 种的服务端耗时接近），但费用按语言数倍增：翻 3 种语言就是 3 倍字数。所以只在确实需要时才传数组。

glossary：自带术语

接实时翻译的系统（客服后台、运营工具）往往有自己的术语约定，不必先录进平台：

"glossary": [
  { "source": "战斗", "target": "バトル", "language": "ja" },
  { "source": "金币", "target": "Coin" }
]

• 叠加在项目术语库之上，同一个源词以自带的为准
• 不带 language 的条目对所有目标语言生效
• mode: "fast" 下项目术语库不查，但自带术语仍然生效（它不需要查库）

译文缓存

相同的（项目 + 源文 + 语言对 + mode + 术语）在 7 天内重复请求，直接返回既有译文：秒回，且不计费（响应里 source: "cache"）。

术语一改，缓存立刻失效 —— 缓存键里含这条文本实际命中的术语集合，术语的新增 / 修改 / 删除都会让键变化，不会拿旧术语的译文回答你。同理，换一套 glossary、换 mode 也都是不同的缓存条目。

要强制重新翻译（比如想换个说法），传 no_cache: true。

缓存与平台的翻译记忆库（TM）无关：它不读、不写 TM，纯粹是性能层。

响应

成功（HTTP 200）：

{
  "success": true,
  "code": 0,
  "msg": "ok",
  "trace_id": "d3f98b2c...",
  "data": {
    "results": [
      {
        "index": 0,
        "text": "确定要退出战斗吗？",
        "translations": {
          "en": {
            "translation": "Leave the battle?",
            "source": "model",
            "structure_ok": true,
            "structure_issues": []
          },
          "ja": {
            "translation": "戦闘を終了しますか？",
            "source": "tm",
            "structure_ok": true,
            "structure_issues": []
          }
        }
      }
    ],
    "billed_credits": 10,
    "billed_words": 8,
    "elapsed_ms": 1840,
    "mode": "standard",
    "source_language": "zh-hans",
    "target_languages": ["en", "ja"]
  }
}

逐条判断，别只看 HTTP 状态码

results[].translations[语言] 里：

字段	说明
translation	译文
source	model = 模型翻译；cache = 命中译文缓存（不计费）
structure_ok	false 表示译文的占位符 / 富文本标签与源文对不上 —— 不要直接上屏，提示人工确认
structure_issues	structure_ok=false 时的具体差异
error	该目标语言这一条没出来。一种语言失败不影响其它语言，整体仍返回 200

顶层字段

• billed_credits：本次实际计费积分
• billed_words：送模型的字数（缓存命中的不计入）
• cache_hits：由缓存直接返回的（文本 × 语言）数
• elapsed_ms：服务端耗时

计费

与平台批量翻译同一条费率：按字数 × 目标语言数，实时不加价。

• 命中缓存的条目不计费（响应里 source: "cache"）
• 调用失败、超时不计费
• 每次调用有全平台统一的 10 积分（$0.01）最低计费，与其它品类一致

限流

按 App Key 限流，默认 60 次 / 分钟。超限返回 HTTP 429，响应头带 Retry-After（秒）。

单次请求的硬上限：≤ 50 条、每条 ≤ 2000 字符、≤ 10 种目标语言。超出请分批，或改用 /tasks/create。

错误码

HTTP	说明
400	参数不合法（条数 / 长度 / 语言码 / mode 超出范围）
401 / 404	鉴权失败（签名、时间戳、AppKey）
402	按量付费余额不足，请充值
422	项目没有配置语言树
429	触发限流，见 Retry-After
502 / 504	翻译服务异常或超时，可重试

调用示例

BODY='{
  "texts": ["确定要退出战斗吗？", "获得 {0} 金币"],
  "target_language": "en"
}'

curl -X POST "${BASE_URL}/api/open/v1/translate" \
  -H "Content-Type: application/json" \
  -H "X-Loxily-AppKey: ${APP_KEY}" \
  -H "X-Loxily-Timestamp: ${TIMESTAMP}" \
  -H "X-Loxily-Sign: ${SIGN}" \
  --data "${BODY}"

一次翻多种语言（进阶）

BODY='{
  "texts": ["确定要退出战斗吗？"],
  "target_languages": ["en", "ja", "ko"]
}'

追求最低延迟（放弃术语）

BODY='{ "texts": ["确定要退出战斗吗？"], "target_language": "en", "mode": "fast" }'

自带术语

BODY='{
  "texts": ["获得 {0} 金币"],
  "target_language": "en",
  "glossary": [{ "source": "金币", "target": "Gold Pieces" }]
}'

强制重新翻译

BODY='{ "texts": ["确定要退出战斗吗？"], "target_language": "en", "no_cache": true }'

常见问题

译文能在平台页面里看到吗？

不能。本接口不写任何数据，平台里搜不到这些译文，也不会出现在任务、版本或导出结果中。需要留存请改用 /tasks/create。

同一句话调两次，会收两次费吗？

不会。第二次会命中译文缓存（source: "cache"），秒回且不计费 —— 前提是源文、语言、mode 和命中的术语都没变，且在 7 天有效期内。

译文和项目里的不一样？

术语是一致的（standard 档注入项目术语），但整句措辞可能不同 —— 实时档用的是精简提示词和低延迟模型，为速度放弃了批量流程里的风格细则。需要整句与项目完全一致的场景，应该走 /tasks/create 把内容正式翻译进项目。

mode: "fast" 连项目术语库也不查，差异会更大（自带 glossary 仍生效）。