Tilvar API

Başlarken

1. Ücretsiz kademe dahil her üye API kullanabilir; Destekçi ve Akademisyen daha yüksek sınırlar alır. Üyelik kademeleri
2. Hesap sayfanızdan bir API anahtarı oluşturun. Hesabım
3. Anahtarı her istekte Authorization: Bearer … başlığında gönderin.

Anahtarınızı kimseyle paylaşmayın: anahtarı bilen, kotanızı kullanabilir. Şüphelenirseniz hesap sayfasından yeni bir anahtar oluşturun; eskisi geçersiz olur.

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

Metin çevirme

POST /api/translate JSON gövdesi: text (çevrilecek metin), tgt (hedef dil kodu, örn. tur, eng), isteğe bağlı src (kaynak dil kodu; verilmezse otomatik algılanır).

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

Yanıt:

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

warnings listesi, sayıların kaybolması ya da sözlük kuralının uygulanamaması gibi uyarıları içerir; boşsa bir sorun görülmemiştir.

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

Sohbet uyumlu uç nokta (tarayıcı eklentileri için)

POST /v1/chat/completions Sohbet biçimindeki istekleri kabul eder; bu uç nokta sohbet etmez, çevirir: model alanı tilvar-<hedef dil kodu> biçimindedir ve son user mesajı o dile çevrilir.

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

Sohbet

POST /api/chat durumsuz sohbettir (geçmişi istemci tutar). messages son 10 mesajı içerir, sonuncusu user; tgt çeviri isteklerinin varsayılan hedef dilidir; web: true asistanın gerektiğinde internette aramasına izin verir (sorgu Tor üzerinden gider, kaynaklar yanıtta döner).

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

Yanıt:

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

Toplu çeviri

POST /api/translate/batch kısa metinleri tek istekte çevirir (sayfa çevirisi için). En fazla 60 öğe ve toplam 3.500 karakter. Sunucu süre sınırına gelirse durur; done kaç öğenin çevrildiğini söyler, kalanları yeniden gönderin.

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

Görsel analiz

POST /api/vision çok parçalı (multipart) bir istektir. Alanlar:

• image: JPEG, PNG, WebP, GIF veya BMP, en çok 8 MB.
• task: describe görselde ne olduğunu anlatır; text içindeki yazıyı okur; translate yazıyı okur ve tgt diline çevirir; ask görsel hakkındaki question alanındaki soruyu yanıtlar.
• tgt: betimleme ve çeviri için hedef dil kodu (varsayılan tur).

Her görsel günlük API kotasından 1.000 karakter sayılır. Görseller kaydedilmez.

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

Yanıt (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"}

Tarayıcı eklentisi

Tilvar eklentisi sayfaları yerinde çevirir, seçili metni ve görseldeki yazıyı çevirir, küçük bir sohbet kutusu sunar. Yukarıdaki API anahtarıyla çalışır ve aynı sınırlara tabidir. Firefox mağazasında yayında; Chrome/Edge için mağaza başvurusu sürüyor, şimdilik elle kurabilirsiniz:

1. Chrome/Edge: yukarıdaki zip dosyasını indirin, bir klasöre çıkarın, chrome://extensions sayfasında “Geliştirici modu”nu açın, “Paketlenmemiş öğe yükle” ile çıkardığınız klasörü seçin.
2. Eklenti simgesine tıklayıp API anahtarınızı yapıştırın.

Masaüstü uygulaması

Tilvar’ı ayrı bir pencerede, sistem tepsisinde ve genel bir kısayolla açılan hızlı çeviri kutusuyla kullanın. Şu an yalnızca Windows için hazır; macOS ve Linux yakında.

Ajan modu (isteğe bağlı): sohbette bilgisayarınızda bir komut çalıştırılmasını isteyebilirsiniz. Tilvar bunu yalnızca önerir; siz uygulamada gösterilen komutu gözünüzle görüp onaylamadan hiçbir şey çalışmaz, ayrıca diski formatlama veya kökten silme gibi geri döndürülemez birkaç komut kalıbı onaylansa bile reddedilir.

Dil kodları

Diller üç harfli ISO 639-3 kodlarıyla verilir: Türkçe tur, İngilizce eng, Almanca deu, Fransızca fra, İspanyolca spa, Rusça rus, Çince zho, Japonca jpn, Korece kor, Kazakça kaz, Özbekçe uzb, Azerice aze. Tam liste için GET /api/languages.

Sınırlar

Sunucu küçük ve herkesle paylaşılıyor; bu yüzden API kullanımı sınırlıdır. Anahtarlar yalnızca çeviri, sohbet ve görsel uç noktalarında çalışır. Web uygulamasındaki kullanım bu sınırlara dahil değildir.

Hatalar

Sınıra takılan istekler 429 ve Retry-After başlığıyla (saniye) döner; sunucu yoğunsa 503.

Türk dillerine çeviri her zaman Türkiye Türkçesi alfabesiyle döner. Çeviriler makine çevirisidir; önemli metinleri gözden geçirin.