Lingarr REST API使用教程：如何将字幕翻译能力快速集成到你的应用-Seo优化-塔城地区网站建设公司

Lingarr REST API使用教程：如何将字幕翻译能力快速集成到你的应用

【免费下载链接】lingarrLingarr is an application that supports both local and SaaS translation services to translate subtitle files into a specified target language. With automated translation options, Lingarr simplifies translating subtitles.项目地址: https://gitcode.com/gh_mirrors/li/lingarr

Lingarr REST API 是一套专为字幕翻译场景设计的开放接口，让开发者无需理解复杂的字幕解析与翻译服务适配逻辑，即可把多语言字幕翻译能力快速集成到自己的应用、脚本或自动化流程中。本教程将带你从零开始，完成服务部署、API Key 获取、核心翻译接口调用到任务状态管理的完整流程，适合刚接触 Lingarr 的开发者与普通用户。

一、什么是 Lingarr REST API？

Lingarr 是一款开源的字幕翻译应用，同时支持本地与 SaaS 两类翻译服务，可自动将 SRT、SSA 等字幕文件翻译为目标语言。它内置了 LibreTranslate、DeepL、OpenAI、Gemini、DeepSeek、Mistral 等十余种翻译服务适配，并通过统一接口对外输出能力。

换句话说：你不需要自己对接各个翻译厂商，只需调用 Lingarr 的 REST API，就能获得一致的翻译体验。所有接口都集中在服务端源码中，例如：

翻译入口：TranslateController.cs
任务管理：TranslationRequestController.cs
认证授权：AuthController.cs

二、快速开始：用 Docker 部署 Lingarr 服务

调用 REST API 之前，需要先让 Lingarr 服务跑起来。推荐使用 Docker 部署，一条命令即可完成。

docker run -d \ --name lingarr \ -p 9876:9876 \ -e ASPNETCORE_URLS=http://+:9876 \ -e DB_CONNECTION=sqlite \ -v /path/to/media:/media \ -v /path/to/config:/app/config \ lingarr/lingarr:latest

部署完成后，通过http://你的服务器地址:9876即可访问 Web 界面，首次访问会进入引导流程（Onboarding），完成账号创建后服务就绪。若需要源码方式部署，可先克隆仓库https://gitcode.com/gh_mirrors/li/lingarr，参考 installation.md 中的完整安装说明。

三、获取 API Key：调用接口的通行证

Lingarr 的 REST API 默认受保护，所有业务接口都经过 LingarrAuthorizeAttribute.cs 的鉴权检查，支持 Cookie 会话与 API Key 两种方式。对程序化调用而言，API Key 是首选，因为无需维护登录态。

获取 API Key 有两种途径：

方式一：Web 界面一键生成 ⚡

方式二：调用接口生成

如果已登录 Cookie 会话，也可直接调用生成接口：

curl -X POST http://localhost:9876/api/auth/apikey/generate

成功后返回 JSON：

{ "apiKey": "你的API密钥" }

后续所有请求，只需在 Header 中带上它即可：

-H "X-Api-Key: 你的API密钥"

四、核心接口详解：字幕翻译 API 调用指南

Lingarr REST API 提供了从「整文件翻译」到「单行翻译」的多种粒度接口，灵活适配不同集成场景。

1. 提交整文件翻译任务（异步任务模式）

这是最常用的接口，适合将字幕文件完整翻译成目标语言。翻译在后台异步执行，接口立即返回任务 ID。

POST /api/translate/file

请求体参考 TranslateAbleSubtitle.cs 定义：

{ "mediaId": 123, "subtitlePath": "movies/example.srt", "sourceLanguage": "en", "targetLanguage": "zh-CN", "mediaType": "Movie", "subtitleFormat": "srt" }

返回结果：

{ "jobId": "task-20260815-0001" }

拿到jobId后，可通过任务查询接口轮询翻译进度（见第五节）。

2. 单行实时翻译（同步模式）

如果你只想翻译一句字幕文本（例如聊天翻译、实时字幕场景），使用单行翻译接口，它同步返回译文，等待时间短：

POST /api/translate/line

请求体参考 TranslateAbleSubtitleLine.cs：

{ "subtitleLine": "Hello, welcome to Lingarr!", "sourceLanguage": "en", "targetLanguage": "zh-CN" }

返回即为翻译后的字符串：

你好，欢迎使用 Lingarr！

3. 批量字幕内容翻译（一次多行）

需要一次翻译多行字幕时，使用内容批量接口，支持一次性传入整个字幕文件的多行内容，服务端自动批量处理：

POST /api/translate/content

请求体参考 TranslateAbleSubtitleContent.cs，其中lines为字幕行数组：

{ "arrMediaId": 123, "sourceLanguage": "en", "targetLanguage": "zh-CN", "mediaType": "Movie", "lines": [ { "index": 1, "text": "Hello" }, { "index": 2, "text": "How are you?" } ] }

返回对应行的译文数组，非常适合 Bazarr 这类需要按行批处理字幕的集成方使用。

4. 批量媒体翻译任务

如果你想为多部影片或剧集统一发起翻译，可使用批量接口，服务端会自动发现字幕文件并解析源语言：

POST /api/translate/bulk

请求体参考 BulkTranslateRequest.cs：

{ "mediaIds": [101, 102, 103], "targetLanguage": "zh-CN", "mediaType": "Show" }

5. 查询支持的语言列表

集成前先确认 Lingarr 支持哪些语言，调用语言列表接口即可：

GET /api/translate/languages

返回一组包含语言代码与英文名称的列表，如en、zh-CN、ja等，作为前端语言选择器的数据源。

五、翻译任务状态管理：查询、取消与重试

异步任务提交后，如何掌握进度？Lingarr 提供了完整的任务管理接口（见 TranslationRequestController.cs）。

接口	方法	用途
`/api/translationrequest/{id}`	GET	查询单个任务详情及事件时间线
`/api/translationrequest/active`	GET	获取所有进行中的任务
`/api/translationrequest/requests`	GET	分页查询历史任务（支持搜索排序）
`/api/translationrequest/cancel`	POST	取消任务
`/api/translationrequest/retry`	POST	重新发起任务
`/api/translationrequest/resume`	POST	从失败/中断处续传（复用已翻译行）
`/api/translationrequest/remove`	POST	删除任务记录

其中resume（续传）功能非常实用：翻译中断后重新发起，已翻译过的行不会重复消耗翻译服务额度，大幅节省成本 💰。

六、前端调用示例：10 行代码接入翻译能力

以 JavaScript 为例，封装一个最简翻译函数，即可在你的应用中集成 Lingarr 字幕翻译能力：

async function translateSubtitle(text, targetLang = "zh-CN") { const resp = await fetch("http://localhost:9876/api/translate/line", { method: "POST", headers: { "Content-Type": "application/json", "X-Api-Key": "你的API密钥" }, body: JSON.stringify({ subtitleLine: text, sourceLanguage: "en", targetLanguage: targetLang }) }); return resp.text(); }