API Tilvar

Начало работы

1. Каждый участник может использовать API, включен бесплатный уровень; Поддерживающие и Академические получают более высокие лимиты. Уровни членства
2. Создайте ключ API на странице вашей учетной записи. Моя учетная запись
3. Отправляйте ключ с каждым запросом в заголовке 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 МБ.
• task: describe описывает, что находится на изображении; text считывает текст на нем; translate считывает текст и переводит его на язык tgt; ask отвечает на question, который вы отправляете о изображении.
• tgt: код целевого языка для описаний и переводов (по умолчанию tur).

Каждое изображение учитывается как 1 000 символов в дневной квоте API. Изображения не сохраняются.

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 и подпадает под те же ограничения. Оно еще не в магазинах (подача заявки в процессе); на данный момент вы можете установить его вручную:

1. Скачайте zip, соответствующий вашему браузеру выше, и распакуйте его в папку.
2. Chrome/Edge: chrome://extensions откройте «Режим разработчика» и выберите «Загрузить распакованное», затем выберите распакованную папку. Firefox: about:debugging → «Этот Firefox» → «Загрузить временный аддон» (вам придется загрузить его снова после перезапуска браузера; подача заявки в магазин Firefox в процессе).
3. Нажмите на значок расширения и вставьте ваш ключ API.

Десктопное приложение

Используйте Tilvar в собственном окне, из системного трея и с всплывающим окном быстрого перевода по глобальной горячей клавише. Пока только для Windows; macOS и Linux запланированы.

Режим агента (необязательно): в чате вы можете запросить команду для выполнения на вашем собственном компьютере. Tilvar всегда только предлагает ее; ничего не выполняется, пока вы не увидите точную команду в приложении и не одобрите ее, и короткий список необратимых операций (форматирование диска, удаление всего и тому подобное) отклоняется даже при одобрении.

Коды языка

Языки используют трехбуквенные коды ISO 639-3: Turkish tur, English eng, German deu, French fra, Spanish spa, Russian rus, Chinese zho, Japanese jpn, Korean kor, Kazakh kaz, Uzbek uzb, Azerbaijani aze. Для полного списка вызовите GET /api/languages.

Лимиты

Сервер небольшой и общий, поэтому использование API ограничено. Ключи работают только для конечных точек перевода, чата и изображений. Использование веб-приложения не учитывается в этих лимитах.

Ошибки

Запросы, превышающие лимит, получают 429 с заголовком Retry-After (секунды); когда сервер занят, вы получаете 503.

Переводы на тюркские языки всегда возвращаются в турецком алфавите. Переводы являются машинным переводом; проверьте важный текст.