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/lingarrLingarr REST API 是一套专为字幕翻译场景设计的开放接口让开发者无需理解复杂的字幕解析与翻译服务适配逻辑即可把多语言字幕翻译能力快速集成到自己的应用、脚本或自动化流程中。本教程将带你从零开始完成服务部署、API Key 获取、核心翻译接口调用到任务状态管理的完整流程适合刚接触 Lingarr 的开发者与普通用户。一、什么是 Lingarr REST APILingarr 是一款开源的字幕翻译应用同时支持本地与 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_URLShttp://:9876 \ -e DB_CONNECTIONsqlite \ -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 界面一键生成 ⚡登录 Lingarr 后台进入「设置 → 身份验证」页面点击Generate API Key按钮即可生成。对应前端组件见 ApiKeyConfiguration.vue。方式二调用接口生成如果已登录 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 }返回即为翻译后的字符串你好欢迎使用 Lingarr3. 批量字幕内容翻译一次多行需要一次翻译多行字幕时使用内容批量接口支持一次性传入整个字幕文件的多行内容服务端自动批量处理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/activeGET获取所有进行中的任务/api/translationrequest/requestsGET分页查询历史任务支持搜索排序/api/translationrequest/cancelPOST取消任务/api/translationrequest/retryPOST重新发起任务/api/translationrequest/resumePOST从失败/中断处续传复用已翻译行/api/translationrequest/removePOST删除任务记录其中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(); }七、常见问题FAQ❓Q1调用接口返回 401 怎么办检查是否在 Header 中正确携带X-Api-Key且 API Key 未被重新生成覆盖。Q2返回 403 并提示 Onboarding required说明服务尚未完成初始化引导请先通过 Web 界面完成首次设置。Q3Lingarr 支持哪些翻译服务支持 LibreTranslate、DeepL、OpenAI、Gemini、DeepSeek、Mistral、Anthropic、本地大模型Ollama等翻译服务适配代码集中在 Translation 目录接口层面无需区分统一调用即可。Q4翻译耗时较长时如何避免超时优先使用异步的/api/translate/file提交任务再轮询任务状态而不是等待同步接口返回。结语Lingarr REST API 的接口设计简洁、语义清晰从单行翻译到批量任务管理一应俱全。无论是做视频网站的字幕本地化还是为内部工具增加多语言支持它都能帮你把字幕翻译能力快速集成到自己的应用中。现在就去部署一个 Lingarr动手试试吧【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考