API de Tilvar

Primeros pasos

1. Cada miembro puede usar la API, incluido el nivel gratuito; los patrocinadores y académicos obtienen límites más altos. Niveles de membresía
2. Cree una clave de API en su página de cuenta. Mi cuenta
3. Envíe la clave con cada solicitud en la cabecera Authorization: Bearer ….

No comparta su clave: cualquiera que la tenga puede gastar su cuota. Si tiene dudas, cree una clave nueva en su página de cuenta; la antigua deja de funcionar.

Dirección base: https://tilvar.athena.org.tr

Traducir texto

POST /api/translate Cuerpo JSON: text (el texto), tgt (código de idioma de destino, p. ej., tur, eng), opcional src (código de idioma de origen; detectado automáticamente cuando se omite).

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

Respuesta:

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

warnings enumera avisos como números que faltaron o una regla de glosario que no se pudo aplicar; cuando está vacío no se notó nada.

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

Punto final de estilo de completado de chat (para extensiones de navegador)

POST /v1/chat/completions acepta solicitudes de estilo de chat; este punto final traduce, no chatea: el campo model es tilvar-<target language code> y el último mensaje user se traduce a ese idioma.

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 es un chat sin estado (el cliente mantiene el historial). messages contiene los últimos 10 mensajes, el último de user; tgt es el objetivo predeterminado de las solicitudes de traducción; web: true permite al asistente buscar en la web cuando es útil (la consulta pasa por Tor, las fuentes regresan en la respuesta).

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

Respuesta:

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

Traducción por lotes

POST /api/translate/batch traduce muchos textos cortos en una solicitud (para traducción de página). Como máximo 60 elementos y 3,500 caracteres en total. Si el servidor se queda sin tiempo se detiene; done indica cuántos elementos se tradujeron, envíe el resto de nuevo.

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

Análisis de imágenes

POST /api/vision es una solicitud multipart. Campos:

• image: JPEG, PNG, WebP, GIF o BMP, como máximo 8 MB.
• task: describe describe lo que hay en la imagen; text lee el texto en ella; translate lee el texto y lo traduce al idioma tgt; ask responde a lo question que envías sobre la imagen.
• tgt: código de idioma de destino para descripciones y traducciones (predeterminado tur).

Cada imagen cuenta 1,000 caracteres contra la cuota diaria de API. Las imágenes no se almacenan.

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

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

Extensión de navegador

La extensión Tilvar traduce páginas en su lugar, traduce texto seleccionado y el texto en imágenes, y ofrece un pequeño cuadro de chat. Funciona con la clave API anterior y está sujeta a los mismos límites. Todavía no está en las tiendas (la presentación está en curso); por ahora puedes instalarla manualmente:

1. Descarga el zip que coincida con tu navegador anterior y descomprímelo en una carpeta.
2. Chrome/Edge: chrome://extensions abre "Modo desarrollador" y elige "Cargar carpeta desplegada", luego selecciona la carpeta que descomprimiste. Firefox: about:debugging → "Este Firefox" → "Cargar complemento temporal" (tendrás que cargarlo de nuevo después de que el navegador se reinicie; la presentación en la tienda de Firefox está en curso).
3. Haz clic en el icono de la extensión y pega tu clave API.

Aplicación de escritorio

Usa Tilvar en su propia ventana, desde la bandeja del sistema y con una ventana emergente de traducción rápida en una tecla de acceso rápido global. Solo Windows por ahora; macOS y Linux están planificados.

Modo agente (opcional): en el chat puedes pedir un comando para ejecutar en tu propia computadora. Tilvar solo lo propone; nada se ejecuta hasta que ves el comando exacto en la aplicación y lo apruebas, y una corta lista de patrones irreversibles (formatear un disco, borrar todo, y similares) es rechazada incluso si se aprueba.

Códigos de idioma

Los idiomas usan códigos ISO 639-3 de tres letras: Turco tur, Inglés eng, Alemán deu, Francés fra, Español spa, Ruso rus, Chino zho, Japonés jpn, Coreano kor, Kazajo kaz, Uzbeque uzb, Azerbaiyano aze. Para la lista completa llame GET /api/languages.

Límites

El servidor es pequeño y compartido, por lo que el uso de API está limitado. Las claves solo funcionan en los puntos finales de traducción, chat e imagen. Usar la aplicación web no cuenta para estos límites.

Errores

Las solicitudes que superan un límite obtienen 429 con un encabezado Retry-After (segundos); cuando el servidor está ocupado obtienes 503.

Las traducciones a lenguas túrquicas siempre regresan en el alfabeto turco-turco. Las traducciones son traducciones automáticas; revise el texto importante.