Tilvar API

通过 HTTP 从您自己的工具、脚本和浏览器翻译扩展中使用 Tilvar。

开始使用

每个成员都可以使用 API，包括免费套餐；支持者和学术用户享有更高的限制。会员等级
在您的账户页面上创建 API 密钥。我的账户
在 Authorization: Bearer … 头中随每次请求发送密钥。

请勿分享您的密钥：拥有它的人可以消耗您的配额。如有疑问，请在您的账户页面上创建一个新密钥；旧密钥将停止工作。

基础地址：https://tilvar.athena.org.tr

翻译文本

POST /api/translate JSON 主体：text (文本)，tgt (目标语言代码，例如 tur, eng)，可选 src (源语言代码；如果省略则自动检测)。

curl -s https://tilvar.athena.org.tr/api/translate \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hello world", "tgt": "tur"}'

响应：

{"translation": "Merhaba dünya", "warnings": [], "source_language": "eng"}

warnings 列出通知，例如丢失的编号或无法应用的术语表规则；如果为空，则没有注意到任何事情。

import requests

r = requests.post(
    "https://tilvar.athena.org.tr/api/translate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"text": "Hello world", "tgt": "tur"},
    timeout=120,
)
r.raise_for_status()
print(r.json()["translation"])

聊天补全风格的端点（用于浏览器扩展）

POST /v1/chat/completions 接受聊天风格的请求；此端点 翻译，它不聊天：model 字段是 tilvar-<target language code>，最后一个 user 消息被翻译成该语言。

curl -s https://tilvar.athena.org.tr/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model": "tilvar-tur", "messages": [{"role": "user", "content": "Hello world"}]}'

聊天

POST /api/chat 是一个无状态的聊天（客户端保留历史记录）。messages 包含最近的 10 条消息，最后一条来自 user；tgt 是翻译请求的默认目标；web: true 在有用时允许助手搜索网络（查询通过 Tor，来源在答案中返回）。

curl -s https://tilvar.athena.org.tr/api/chat \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"messages": [{"role": "user", "content": "What is new in llama.cpp?"}], "tgt": "tur", "web": true}'

响应：

{"reply": "…", "kind": "chat", "sources": [{"title": "…", "url": "https://…"}]}

批量翻译

POST /api/translate/batch 在一个请求中翻译多条短文本（用于页面翻译）。最多 60 个项目和总共 3,500 个字符。如果服务器时间用尽则停止；done 说明翻译了多少个项目，请再次发送其余部分。

curl -s https://tilvar.athena.org.tr/api/translate/batch \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"items": ["Hello", "Read more"], "tgt": "tur"}'

图像分析

POST /api/vision 是一个多部分请求。字段：

image：JPEG、PNG、WebP、GIF 或 BMP，最多 8 MB。
task：describe 描述图像内容；text 读取图像中的文本；translate 读取文本并将其翻译成 tgt 语言；ask 回答您关于图像的 question。
tgt：描述和翻译的目标语言代码（默认为 tur）。

每张图片计入每日 API 配额 1,000 个字符。图片不会被存储。

curl -s https://tilvar.athena.org.tr/api/vision \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F [email protected] -F task=translate -F tgt=eng

响应 (translate):

{"result": "Coffee House - Open: 08:00-22:00", "text": "Kahve Evi — Açık: 08:00-22:00", "translation": "Coffee House - Open: 08:00-22:00", "source_language": "tur"}

浏览器扩展

Tilvar 扩展在原地翻译页面，翻译选定文本和图片中的文本，并提供一个小聊天框。它使用上面的 API 密钥，并受相同的限制。它尚未在商店中（提交过程中）；目前您可以手动安装它：

⬇ Firefox 下载 ⬇ Chrome / Edge 下载

下载与您的浏览器相匹配的 zip 文件并将其解压到一个文件夹中。
Chrome/Edge：chrome://extensions 打开“开发者模式”并选择“加载解压的扩展程序”，然后选择您解压的文件夹。Firefox：about:debugging → “此 Firefox” → “加载临时附加组件”（浏览器重启后您需要再次加载它；Firefox 商店提交正在进行中）。
点击扩展程序图标并粘贴您的 API 密钥。

桌面应用

在其自己的窗口中、从系统托盘以及通过全局热键的快速翻译弹出窗口中使用 Tilvar。目前仅限 Windows；计划支持 macOS 和 Linux。

⬇ Windows 下载 (.exe)

代理模式（可选）：在聊天中，您可以要求在您自己的计算机上运行一个命令。Tilvar 仅提出它；在您在应用程序中看到确切的命令并批准它之前，没有任何东西会运行，即使批准了，也会拒绝执行一小部分不可逆的模式（格式化磁盘、删除所有内容等）。

语言代码

语言使用三字母 ISO 639-3 代码：土耳其语 tur，英语 eng，德语 deu，法语 fra，西班牙语 spa，俄语 rus，中文 zho，日语 jpn，韩语 kor，哈萨克语 kaz，乌兹别克语 uzb，阿塞拜疆语 aze。要查看完整列表，请调用 GET /api/languages。

限制

服务器较小且共享，因此 API 使用有限制。密钥仅在翻译、聊天和图像端点上有效。使用 Web 应用程序不计入这些限制。

	支持者	学术
每日 API 字符数	50,000	100,000
每分钟请求数	20	20
并行请求数	1	1
每个请求的字符数	4,000	4,000

错误

超过限制的请求会返回 429，带有 Retry-After 标头（秒）；当服务器繁忙时，您会收到 503。

401	密钥缺失或无效。
403	密钥的层级没有 API 访问权限。
413	文本太长，无法在一个请求中处理；请通过 Tilvar 中的“文档”选项卡发送文档。
429	每日字符配额已用完。

译入突厥语系的翻译总是使用土耳其-土耳其字母。翻译是机器翻译；请审阅重要文本。