API Tilvar

Commencer

1. Chaque membre peut utiliser l'API, niveau gratuit inclus ; les contributeurs et les universitaires obtiennent des limites plus élevées. Niveaux d'adhésion
2. Créez une clé API sur votre page de compte. Mon compte
3. Envoyez la clé avec chaque requête dans l'en-tête Authorization: Bearer ….

Ne partagez pas votre clé : toute personne qui l'a peut utiliser votre quota. En cas de doute, créez une nouvelle clé sur votre page de compte ; l'ancienne cesse de fonctionner.

Adresse de base : https://tilvar.athena.org.tr

Traduire du texte

POST /api/translate corps JSON: text (le texte), tgt (code de langue cible, par exemple tur, eng), optionnel src (code de langue source ; détecté automatiquement lorsqu'il est omis).

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

Réponse :

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

warnings liste les avis tels que les numéros manquants ou une règle de glossaire qui n'a pas pu être appliquée ; lorsqu'il est vide, rien n'a été remarqué.

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

Point de terminaison de style complétion de chat (pour les extensions de navigateur)

POST /v1/chat/completions accepte les requêtes de style chat ; ce point de terminaison traduit, il ne discute pas : le champ model est tilvar-<target language code> et le dernier message user est traduit dans cette langue.

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 est un chat sans état (le client conserve l'historique). messages contient les 10 derniers messages, le dernier de user ; tgt est la cible par défaut des requêtes de traduction ; web: true permet à l'assistant de rechercher sur le web lorsque cela est utile (la requête passe par Tor, les sources reviennent dans la réponse).

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

Réponse :

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

Traduction par lots

POST /api/translate/batch traduit de nombreux textes courts en une seule requête (pour la traduction de page). Au maximum 60 éléments et 3 500 caractères au total. Si le serveur manque de temps, il s'arrête ; done indique combien d'éléments ont été traduits, renvoyez le reste.

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

Analyse d'image

POST /api/vision est une requête multipartie. Champs :

• image : JPEG, PNG, WebP, GIF ou BMP, au maximum 8 Mo.
• task : describe décrit ce qu'il y a dans l'image ; text lit le texte qu'elle contient ; translate lit le texte et le traduit dans la langue tgt ; ask répond à question que vous envoyez sur l'image.
• tgt : code de langue cible pour les descriptions et les traductions (par défaut tur).

Chaque image compte 1 000 caractères dans le quota API quotidien. Les images ne sont pas stockées.

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

Réponse (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"}

Extension de navigateur

L'extension Tilvar traduit les pages en place, traduit le texte sélectionné et le texte dans les images, et propose une petite boîte de discussion. Elle fonctionne avec la clé API ci-dessus et est soumise aux mêmes limites. Elle n'est pas encore dans les magasins (la soumission est en cours) ; pour l'instant, vous pouvez l'installer manuellement :

1. Téléchargez le zip correspondant à votre navigateur ci-dessus et décompressez-le dans un dossier.
2. Chrome/Edge : chrome://extensions ouvrez le « Mode développeur » et choisissez « Charger un dossier non compressé », puis sélectionnez le dossier que vous avez décompressé. Firefox : about:debugging → « Ce Firefox » → « Charger un module complémentaire temporaire » (vous devrez le recharger après le redémarrage du navigateur ; la soumission sur le magasin Firefox est en cours).
3. Cliquez sur l'icône de l'extension et collez votre clé API.

Application de bureau

Utilisez Tilvar dans sa propre fenêtre, depuis la zone de notification du système, et avec une fenêtre contextuelle de traduction rapide sur une touche de raccourci globale. Windows seulement pour l'instant ; macOS et Linux sont prévus.

Mode agent (optionnel) : dans le chat, vous pouvez demander une commande à exécuter sur votre propre ordinateur. Tilvar ne propose jamais ; rien ne s'exécute tant que vous ne voyez pas la commande exacte dans l'application et ne l'approuvez pas, et une courte liste de modèles irréversibles (formater un disque, tout supprimer, etc.) est refusée même si elle est approuvée.

Codes de langue

Les langues utilisent des codes ISO 639-3 à trois lettres : Turc tur, Anglais eng, Allemand deu, Français fra, Espagnol spa, Russe rus, Chinois zho, Japonais jpn, Coréen kor, Kazakh kaz, Ouzbek uzb, Azerbaïdjanais aze. Pour la liste complète, appelez GET /api/languages.

Limites

Le serveur est petit et partagé, donc l'utilisation de l'API est limitée. Les clés ne fonctionnent que sur les points de terminaison de traduction, de chat et d'image. L'utilisation de l'application web ne compte pas dans ces limites.

Erreurs

Les requêtes dépassant une limite reçoivent 429 avec un en-tête Retry-After (secondes) ; lorsque le serveur est occupé, vous recevez 503.

Les traductions dans les langues turciques reviennent toujours dans l'alphabet turc-turc. Les traductions sont des traductions automatiques ; révisez le texte important.