Tilvar API

Erste Schritte

1. Jedes Mitglied kann die API nutzen, inklusive Free tier; Supporter und Academic erhalten höhere Limits. Mitgliedschaftsstufen
2. Erstellen Sie einen API-Schlüssel auf Ihrer Kontoseite. Mein Konto
3. Senden Sie den Schlüssel mit jeder Anfrage im Authorization: Bearer … Header.

Teilen Sie Ihren Schlüssel nicht: Jeder, der ihn hat, kann Ihr Kontingent verbrauchen. Bei Zweifel erstellen Sie einen neuen Schlüssel auf Ihrer Kontoseite; der alte funktioniert nicht mehr.

Basisadresse: https://tilvar.athena.org.tr

Text übersetzen

POST /api/translate JSON-Body: text (der Text), tgt (Zielsprache, z.B. tur, eng), optional src (Quellsprache; wird automatisch erkannt, wenn es weggelassen wird).

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

Antwort:

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

warnings listet Benachrichtigungen wie fehlende Zahlen oder eine Glossarregel, die nicht angewendet werden konnte; wenn sie leer ist, wurde nichts bemerkt.

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-Vervollständigungs-Endpunkt (für Browser-Erweiterungen)

POST /v1/chat/completions akzeptiert Chat-Anfragen; dieser Endpunkt übersetzt, er chattet nicht: das Feld model ist tilvar-<target language code> und die letzte user Nachricht wird in diese Sprache übersetzt.

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 ist ein zustandsloses Chat (der Client behält die Historie). messages enthält die letzten 10 Nachrichten, die letzte von user; tgt ist das Standardziel für Übersetzungsanfragen; web: true lässt den Assistenten im Bedarfsfall im Web suchen (die Abfrage läuft über Tor, die Quellen kommen in der Antwort zurück).

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

Antwort:

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

Stapelübersetzung

POST /api/translate/batch übersetzt viele kurze Texte in einer Anfrage (für Seitenübersetzung). Maximal 60 Elemente und insgesamt 3.500 Zeichen. Wenn der Server die Zeit aufgebraucht hat, stoppt er; done gibt an, wie viele Elemente übersetzt wurden, sende den Rest erneut.

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

Bildanalyse

POST /api/vision ist eine multipart-Anfrage. Felder:

• image: JPEG, PNG, WebP, GIF oder BMP, maximal 8 MB.
• task: describe beschreibt, was sich auf dem Bild befindet; text liest den Text darin; translate liest den Text und übersetzt ihn in die tgt Sprache; ask beantwortet die question, die Sie zum Bild senden.
• tgt: Zielsprachencode für Beschreibungen und Übersetzungen (Standard tur).

Jedes Bild zählt 1.000 Zeichen für das tägliche API-Kontingent. Bilder werden nicht gespeichert.

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

Antwort (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-Erweiterung

Die Tilvar-Erweiterung übersetzt Seiten direkt, übersetzt ausgewählten Text und Text in Bildern und bietet eine kleine Chatbox. Sie funktioniert mit dem oben genannten API-Schlüssel und unterliegt denselben Limits. Sie ist noch nicht in den Stores (Einreichung läuft); im Moment können Sie sie manuell installieren:

1. Laden Sie das Zip herunter, das zu Ihrem Browser oben passt, und entpacken Sie es in einen Ordner.
2. Chrome/Edge: chrome://extensions öffnen Sie „Entwicklermodus“ und wählen Sie „Entpackte Seite laden“, dann wählen Sie den Ordner, den Sie entpackt haben. Firefox: about:debugging → „Dieser Firefox“ → „Temporäres Add-on laden“ (Sie müssen es nach dem Neustart des Browsers erneut laden; die Einreichung im Firefox Store läuft).
3. Klicken Sie auf das Erweiterungs-Symbol und fügen Sie Ihren API-Schlüssel ein.

Desktop-App

Verwenden Sie Tilvar in seinem eigenen Fenster, aus der Taskleiste und mit einem Schnellübersetzungs-Popup auf einer globalen Tastenkombination. Nur Windows vorerst; macOS und Linux sind geplant.

Agentenmodus (optional): Im Chat können Sie einen Befehl anfordern, der auf Ihrem eigenen Computer ausgeführt wird. Tilvar schlägt ihn nur vor; nichts wird ausgeführt, bis Sie den genauen Befehl in der App sehen und genehmigen, und eine kurze Liste irreversibler Muster (Festplatte formatieren, alles löschen und Ähnliches) wird abgelehnt, selbst wenn sie genehmigt wird.

Sprachcodes

Sprachen verwenden dreibuchstabige ISO 639-3-Codes: Türkisch tur, Englisch eng, Deutsch deu, Französisch fra, Spanisch spa, Russisch rus, Chinesisch zho, Japanisch jpn, Koreanisch kor, Kasachisch kaz, Usbekisch uzb, Aserbaidschanisch aze. Für die vollständige Liste rufen Sie GET /api/languages auf.

Limits

Der Server ist klein und geteilt, daher ist die API-Nutzung begrenzt. Schlüssel funktionieren nur für die Endpunkte Übersetzung, Chat und Bild. Die Nutzung der Webanwendung zählt nicht zu diesen Limits.

Fehler

Anfragen über einem Limit erhalten 429 mit einem Retry-After-Header (Sekunden); wenn der Server beschäftigt ist, erhalten Sie 503.

Übersetzungen in turkische Sprachen kommen immer im türkischen Alphabet zurück. Übersetzungen sind maschinelle Übersetzungen; überprüfen Sie wichtigen Text.