API Tilvar

Iniziare

1. Ogni membro può utilizzare l'API, incluso il livello gratuito; Supporter e Academic ottengono limiti più elevati. Livelli di iscrizione
2. Crea una chiave API sulla tua pagina account. Il mio account
3. Invia la chiave con ogni richiesta nell'intestazione Authorization: Bearer ….

Non condividere la tua chiave: chiunque la abbia può consumare la tua quota. In caso di dubbio, crea una nuova chiave sulla tua pagina account; quella vecchia smette di funzionare.

Indirizzo base: https://tilvar.athena.org.tr

Traduci testo

POST /api/translate corpo JSON: text (il testo), tgt (codice lingua di destinazione, es. tur, eng), opzionale src (codice lingua di origine; rilevato automaticamente se omesso).

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

Risposta:

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

warnings elenca avvisi come numeri mancanti o una regola del glossario che non è stata applicata; quando è vuoto non è stato notato nulla.

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

Endpoint in stile chat-completamento (per estensioni del browser)

POST /v1/chat/completions accetta richieste in stile chat; questo endpoint traduce, non chiacchiera: il campo model è tilvar-<target language code> e l'ultimo messaggio user viene tradotto in quella lingua.

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 è una chat senza stato (il client mantiene la cronologia). messages contiene gli ultimi 10 messaggi, l'ultimo da user; tgt è il target predefinito delle richieste di traduzione; web: true permette all'assistente di cercare sul web quando utile (la query passa attraverso Tor, le fonti tornano nella risposta).

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

Risposta:

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

Traduzione in blocco

POST /api/translate/batch traduce molti testi brevi in una singola richiesta (per la traduzione di pagine). Al massimo 60 elementi e 3.500 caratteri in totale. Se il server esaurisce il tempo si ferma; done indica quanti elementi sono stati tradotti, invia il resto di nuovo.

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

Analisi di immagini

POST /api/vision è una richiesta multipart. Campi:

• image: JPEG, PNG, WebP, GIF o BMP, al massimo 8 MB.
• task: describe descrive cosa c'è nell'immagine; text legge il testo al suo interno; translate legge il testo e lo traduce nella lingua tgt; ask risponde a question che invii sull'immagine.
• tgt: codice della lingua di destinazione per descrizioni e traduzioni (predefinito tur).

Ogni immagine conta 1.000 caratteri della quota API giornaliera. Le immagini non vengono salvate.

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

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

Estensione del browser

L'estensione Tilvar traduce le pagine sul posto, traduce il testo selezionato e il testo nelle immagini, e offre una piccola casella di chat. Funziona con la chiave API sopra e è soggetta agli stessi limiti. Non è ancora disponibile nei negozi (la sottomissione è in corso); per ora puoi installarla manualmente:

1. Scarica lo zip corrispondente al tuo browser sopra e comprimilo in una cartella.
2. Chrome/Edge: chrome://extensions apri "Modalità sviluppatore" e scegli "Carica cartella non compressa", quindi seleziona la cartella che hai decompresso. Firefox: about:debugging → "Questo Firefox" → "Carica estensione temporanea" (dovrai caricarla di nuovo dopo che il browser si riavvia; la sottomissione al negozio Firefox è in corso).
3. Clicca sull'icona dell'estensione e incolla la tua chiave API.

App desktop

Usa Tilvar nella sua finestra, dalla barra di sistema e con un popup di traduzione rapida su una scorciatoia da tastiera globale. Solo Windows per ora; macOS e Linux sono previsti.

Modalità agente (opzionale): nella chat puoi chiedere un comando da eseguire sul tuo computer. Tilvar propone solo, nulla viene eseguito finché non vedi il comando esatto nell'app e non lo approvi, e una breve lista di pattern irreversibili (formattare un disco, cancellare tutto, e simili) viene rifiutata anche se approvata.

Codici linguistici

Le lingue utilizzano codici ISO 639-3 a tre lettere: Turco tur, Inglese eng, Tedesco deu, Francese fra, Spagnolo spa, Russo rus, Cinese zho, Giapponese jpn, Coreano kor, Kazako kaz, Uzbeko uzb, Azerbaigiano aze. Per l'elenco completo chiama GET /api/languages.

Limiti

Il server è piccolo e condiviso, quindi l'uso dell'API è limitato. Le chiavi funzionano solo sugli endpoint di traduzione, chat e immagini. L'uso dell'app web non conta in questi limiti.

Errori

Le richieste oltre un limite ricevono 429 con un header Retry-After (secondi); quando il server è occupato ricevi 503.

Le traduzioni nelle lingue turche tornano sempre nell'alfabeto turco-turco. Le traduzioni sono traduzioni automatiche; rivedi il testo importante.