企业官网建设流程全解析

如果你正在为产品接入 AI 视频翻译能力，这篇Violin REST API 参考指南能帮你 10 分钟跑通全流程：上传视频 → 轮询进度 → 下载配音成片与 SRT 字幕。Violin 是一款开源视频翻译工具（Video Translation Skill），它的 FastAPI 服务把 Whisper 转写、LLM 翻译、TTS 配音、ffmpeg 合成整条流水线封装成 4 个核心接口，支持 33 种目标语言。下面从启动服务开始，逐个接口讲清楚参数、响应与常见报错。

快速启动 Violin API 服务

Violin 自带 Web 服务入口，一条命令即可启动（需要 Python 3.10+ 和 ffmpeg）：

uv tool install violin # 或 pip install violin export TOGETHER_API_KEY=你的Key # 或使用 OPENAI_API_KEY / ELEVENLABS_API_KEY violin-api # 默认 http://127.0.0.1:8000 violin-api --host 0.0.0.0 --port 8080 # 对外绑定

启动后有两个入口值得知道：

• http://127.0.0.1:8000/docs— 交互式 OpenAPI 文档，所有接口的请求/响应 Schema 都有（定义见 api/app.py）
• http://127.0.0.1:8000/health— 健康检查，支持 GET/HEAD，方便挂监控

服务启动时会按配置校验 API Key；未配置 Key 时进入BYOK 模式（每个请求需自带together_api_key），逻辑见 run_api.py。

核心流程：提交 → 轮询 → 下载

Violin 的任务模型是「异步 Job」：POST 提交后立即返回 Job ID，后台线程池执行转写、翻译、TTS、合成共 5 步，客户端轮询状态直到done，最后拉取成片。整个流程三步：

POST /jobs → 202 { "id": "a1b2...", "status": "queued" } GET /jobs/{id} → 轮询直到 status = "done" GET /jobs/{id}/video → 下载配音成片 .mp4

POST /jobs：提交翻译任务

multipart/form-data上传视频，立即返回 202 和 Job ID，不阻塞等待翻译完成（源码见 api/routes/jobs.py）：

JOB=$(curl -s -X POST http://localhost:8000/jobs \ -F "file=@lecture.mp4" \ -F "language=Spanish" \ -F "style=academic" | jq -r .id)

提交时服务端会做三道校验：扩展名检查（失败返回415）、文件大小上限（413）、时长上限（413）。未带 Key 的匿名请求还受免费试用次数限制，超限时返回403Free trial used。

不想传本地文件？还有POST /jobs/from-url：JSON 提交{ "url": "...", "language": "Spanish" }，服务端用 yt-dlp 自动下载（可由配置关闭）。

GET /jobs/{job_id}：轮询任务状态

curl -s http://localhost:8000/jobs/$JOB | jq '{status, progress}'

响应核心字段（模型定义见 api/models.py）：

{ "id": "a1b2...", "status": "running", "language": "Spanish", "style": "academic", "progress": [ { "step": 1, "total": 5, "message": "Extracting audio..." }, { "step": 2, "total": 5, "message": "Transcribing with Whisper..." } ], "queue_position": 0, "error": null }

status共 5 种取值：queued→running→done/failed/cancelled。progress数组实时反映流水线 5 个阶段（提取音频 → 转写 → 翻译 → TTS → 合片），后台执行逻辑在 api/worker.py。建议每 3~5 秒轮询一次即可。

任务不想跑了？两个接口收尾：

• POST /jobs/{id}/cancel— 取消排队/运行中的任务
• DELETE /jobs/{id}— 删除任务及全部文件（204 无响应体）

GET /jobs/{job_id}/video：下载配音成片

只有status=done时才能下载（源码见 api/routes/files.py），直接curl -OJ即可保存为{job_id}_dubbed.mp4：

curl -OJ http://localhost:8000/jobs/$JOB/video curl -OJ http://localhost:8000/jobs/$JOB/srt # 下载 SRT 字幕

配套还有三个可选下载端点：

进阶接口：字幕分段与视频问答

翻译完成后，Violin 还开放了「看懂视频」的能力（源码见 api/routes/chat.py）：

• GET /jobs/{id}/segments— 返回全部分段字幕：id、start、end、text、speaker，可直接驱动播放器字幕高亮
• POST /jobs/{id}/chat—视频问答：提交{ "question": "他在第三部分提到了什么？", "current_time": 120.5 }，模型会结合该时间点附近的字幕 + 采样的视频帧作答，返回answer及引用区间。适合做「可对话的学习视频」场景。

目录接口：查询语言、音色与风格

写前端下拉框前，先让接口替你枚举（源码见 api/routes/catalog.py）：

curl -s http://localhost:8000/languages # 语言名 → BCP-47 代码映射 curl -s http://localhost:8000/voices # 按语言分组的全部音色 curl -s http://localhost:8000/voices/es # 某语言的母语音色 curl -s http://localhost:8000/styles # 6 种风格及 TTS 语速/情绪

特别推荐POST /voice-match：用自然语言描述你想要的声音（如 "calm female narrator"），LLM 会从音色目录里返回 3 个候选音色 + 选择理由。音色目录本身由 pipeline/tts.py 维护，覆盖 33 种语言、16 种语言有专属母语音色。

GET /jobs/trial-status则用于查询当前 IP 剩余免费试用次数，方便前端提前提示用户填 Key。

配置、限制与常见错误速查

服务端行为由 YAML 配置控制，API 相关项在 config/default.yaml 的api段；公开部署可参考 config/prod.yaml（2 并发、30 分钟时长上限、500 MB 文件上限、24 小时自动清理 Job）：

翻译完成后的产物与成本结构可参考项目文档中的示例：

常见 HTTP 状态码对照：

小结：一条流水线，四个接口

Violin REST API 的设计非常克制：POST /jobs提交、GET /jobs/{id}轮询、GET /jobs/{id}/video下载构成主干，目录接口负责枚举、chat 接口负责增值。全部端点的完整 Schema 都可通过/docs在线调试。把它接入你的学习平台、内容工厂或自动化管线，几行 HTTP 请求就能让视频「开口说」33 种语言。