Tilvar API

Başlarken

1. Destekçi ya da Akademisyen kademesinde olun. API erişimi yalnızca bu kademelere dahildir. Ü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 (Chrome, Edge ve Firefox) 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. Mağazalarda henüz yayında değil; elle kurabilirsiniz:

1. Eklentiyi indirin (zip) ve bir klasöre çıkarın.
2. Chrome/Edge: chrome://extensions sayfasında “Geliştirici modu”nu açın, “Paketlenmemiş öğe yükle” ile klasörü seçin. Firefox: about:debugging → “This Firefox” → “Load Temporary Add-on”.
3. Eklenti simgesine tıklayıp API anahtarınızı yapıştırın.

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.