Tilvar API

Getting started

1. Be on the Supporter or Academic tier. API access is only part of those tiers. Membership tiers
2. Create an API key on your account page. My account
3. Send the key with every request in the Authorization: Bearer … header.

Do not share your key: anyone who has it can spend your quota. If in doubt, create a new key on your account page; the old one stops working.

Base address: https://tilvar.athena.org.tr

Translate text

POST /api/translate JSON body: text (the text), tgt (target language code, e.g. tur, eng), optional src (source language code; detected automatically when left out).

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"}'

Response:

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

warnings lists notices such as numbers that went missing or a glossary rule that could not be applied; when it is empty nothing was noticed.

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"])

Chat-completions style endpoint (for browser extensions)

POST /v1/chat/completions accepts chat-style requests; this endpoint translates, it does not chat: model field is tilvar-<target language code> and the last user message is translated into that language.

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"}]}'

Chat

POST /api/chat is a stateless chat (the client keeps the history). messages holds the last 10 messages, the last one from user; tgt is the default target of translation requests; web: true lets the assistant search the web when useful (the query goes through Tor, sources come back in the answer).

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}'

Response:

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

Batch translation

POST /api/translate/batch translates many short texts in one request (for page translation). At most 60 items and 3,500 characters in total. If the server runs out of time it stops; done says how many items were translated, send the rest again.

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"}'

Image analysis

POST /api/vision is a multipart request. Fields:

• image: JPEG, PNG, WebP, GIF or BMP, at most 8 MB.
• task: describe describes what is in the image; text reads the text in it; translate reads the text and translates it into the tgt language; ask answers the question you send about the image.
• tgt: target language code for descriptions and translations (default tur).

Every image counts 1,000 characters against the daily API quota. Images are not stored.

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

Response (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"}

Browser extension

The Tilvar extension (Chrome, Edge and Firefox) translates pages in place, translates selected text and the text in images, and offers a small chat box. It works with the API key above and is subject to the same limits. It is not in the stores yet; you can install it by hand:

1. Download the extension (zip) and unpack it into a folder.
2. Chrome/Edge: chrome://extensions open “Developer mode” and choose “Load unpacked”, then pick the folder. Firefox: about:debugging → “This Firefox” → “Load Temporary Add-on”.
3. Click the extension icon and paste your API key.

Language codes

Languages use three-letter ISO 639-3 codes: Turkish tur, English eng, German deu, French fra, Spanish spa, Russian rus, Chinese zho, Japanese jpn, Korean kor, Kazakh kaz, Uzbek uzb, Azerbaijani aze. For the full list call GET /api/languages.

Limits

The server is small and shared, so API use is limited. Keys only work on the translation, chat and image endpoints. Using the web app does not count against these limits.

Errors

Requests over a limit get 429 with a Retry-After header (seconds); when the server is busy you get 503.

Translations into Turkic languages always come back in the Turkey-Turkish alphabet. Translations are machine translations; review important text.