API Tilvar

Começar

1. Cada membro pode usar a API, nível gratuito incluído; Suporte e Acadêmico obtêm limites mais altos. Níveis de associação
2. Crie uma chave de API na sua página de conta. Minha conta
3. Envie a chave com cada solicitação no cabeçalho Authorization: Bearer ….

Não compartilhe sua chave: qualquer pessoa que a tenha pode gastar sua cota. Em caso de dúvida, crie uma nova chave na sua página de conta; a antiga para de funcionar.

Endereço base: https://tilvar.athena.org.tr

Traduzir texto

POST /api/translate Corpo JSON: text (o texto), tgt (código do idioma de destino, ex. tur, eng), opcional src (código do idioma de origem; detectado automaticamente se omitido).

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

Resposta:

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

warnings lista avisos como números que faltaram ou uma regra de glossário que não pôde ser aplicada; quando está vazio, nada foi notado.

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 no estilo de completamento de chat (para extensões de navegador)

POST /v1/chat/completions aceita requisições no estilo de chat; este endpoint traduz, não conversa: o campo model é tilvar-<target language code> e a última mensagem user é traduzida para esse 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 é um chat sem estado (o cliente mantém o histórico). messages contém as últimas 10 mensagens, a última de user; tgt é o destino padrão das requisições de tradução; web: true permite que o assistente pesquise na web quando útil (a consulta passa pelo Tor, as fontes retornam na resposta).

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

Resposta:

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

Tradução em lote

POST /api/translate/batch traduz vários textos curtos em uma requisição (para tradução de página). No máximo 60 itens e 3.500 caracteres no total. Se o servidor ficar sem tempo, ele para; done diz quantos itens foram traduzidos, envie o restante novamente.

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álise de imagem

POST /api/vision é uma requisição multipart. Campos:

• image: JPEG, PNG, WebP, GIF ou BMP, no máximo 8 MB.
• task: describe descreve o que está na imagem; text lê o texto nela; translate lê o texto e o traduz para o idioma tgt; ask responde ao question que você envia sobre a imagem.
• tgt: código de idioma de destino para descrições e traduções (padrão tur).

Cada imagem conta 1.000 caracteres da cota diária da API. As imagens não são armazenadas.

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

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

Extensão de navegador

A extensão Tilvar traduz páginas no local, traduz texto selecionado e o texto em imagens, e oferece uma pequena caixa de bate-papo. Funciona com a chave API acima e está sujeita aos mesmos limites. Ainda não está nas lojas (o envio está em andamento); por enquanto você pode instalá-la manualmente:

1. Baixe o zip que corresponde ao seu navegador acima e descompacte-o em uma pasta.
2. Chrome/Edge: chrome://extensions abra “Modo desenvolvedor” e escolha “Carregar sem compactar”, depois selecione a pasta que você descompactou. Firefox: about:debugging → “Este Firefox” → “Carregar complemento temporário” (você precisará carregá-lo novamente após o reinício do navegador; o envio para a loja Firefox está em andamento).
3. Clique no ícone da extensão e cole sua chave API.

Aplicativo de desktop

Use o Tilvar em sua própria janela, a partir da bandeja do sistema e com um pop-up de tradução rápida em uma tecla de atalho global. Apenas Windows por enquanto; macOS e Linux estão planejados.

Modo agente (opcional): no chat você pode pedir um comando para executar no seu próprio computador. O Tilvar sempre propõe; nada é executado até que você veja o comando exato no aplicativo e o aprove, e uma lista curta de padrões irreversíveis (formatar um disco, apagar tudo, e assim por diante) é recusada mesmo que aprovada.

Códigos de idioma

Os idiomas usam códigos ISO 639-3 de três letras: Turco tur, Inglês eng, Alemão deu, Francês fra, Espanhol spa, Russo rus, Chinês zho, Japonês jpn, Coreano kor, Cazaque kaz, Uzbeque uzb, Azeri aze. Para a lista completa, chame GET /api/languages.

Limites

O servidor é pequeno e compartilhado, então o uso da API é limitado. As chaves funcionam apenas nos endpoints de tradução, chat e imagem. Usar o aplicativo web não conta para esses limites.

Erros

Requisições acima de um limite recebem 429 com um cabeçalho Retry-After (segundos); quando o servidor está ocupado, você recebe 503.

As traduções para línguas túrquicas sempre retornam no alfabeto da Turquia-Turco. As traduções são máquinas; revise o texto importante.