Tilvar API

시작하기

1. 모든 회원은 API를 사용할 수 있으며, 무료 등급이 포함됩니다. 서포터 및 학술 사용자는 더 높은 제한을 받습니다. 멤버십 등급
2. 계정 페이지에서 API 키를 생성하십시오. 내 계정
3. Authorization: Bearer … 헤더의 모든 요청에 키를 전송하십시오.

키를 공유하지 마십시오: 키를 가진 사람은 누구나 귀하의 할당량을 사용할 수 있습니다. 의심스러우면 계정 페이지에서 새 키를 생성하십시오. 이전 키는 작동을 멈춥니다.

기본 주소: https://tilvar.athena.org.tr

텍스트 번역

POST /api/translate JSON 본문: text (텍스트), tgt (대상 언어 코드, 예: tur, eng), 선택적 src (원본 언어 코드; 생략하면 자동으로 감지됨).

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

응답:

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

warnings은 누락된 번호나 적용할 수 없는 용어집 규칙과 같은 알림 목록을 표시하며, 비어 있으면 아무것도 감지되지 않았음을 의미합니다.

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

채팅 완성 스타일 엔드포인트 (브라우저 확장 프로그램용)

POST /v1/chat/completions은 채팅 스타일 요청을 수락합니다. 이 엔드포인트는 번역하며 채팅하지 않습니다: model 필드는 tilvar-<target language code>이고 마지막 user 메시지는 해당 언어로 번역됩니다.

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

채팅

POST /api/chat은 상태 비저장 채팅입니다 (클라이언트가 기록을 유지합니다). messages는 마지막 10개 메시지를 포함하며, 마지막 메시지는 user에서 가져옵니다. tgt는 번역 요청의 기본 대상이며, web: true는 유용할 때 어시스턴트가 웹을 검색하도록 허용합니다 (쿼리는 Tor를 통해 전송되고 답변은 소스에서 반환됩니다).

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

응답:

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

일괄 번역

POST /api/translate/batch은 한 요청에서 여러 짧은 텍스트를 번역합니다 (페이지 번역용). 최대 60개 항목 및 총 3,500자. 서버가 시간 초과되면 중지됩니다. done는 번역된 항목 수를 알려주며, 나머지는 다시 보내십시오.

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

이미지 분석

POST /api/vision은 멀티파트 요청입니다. 필드:

• image: JPEG, PNG, WebP, GIF 또는 BMP, 최대 8MB.
• task: describe는 이미지에 무엇이 있는지 설명하고; text은 이미지의 텍스트를 읽고; translate는 텍스트를 읽고 tgt 언어로 번역하며; ask은 이미지에 대해 보낸 question에 답변합니다.
• tgt: 설명 및 번역을 위한 대상 언어 코드 (기본값 tur).

모든 이미지는 일일 API 할당량 1,000자만큼 계산됩니다. 이미지는 저장되지 않습니다.

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

응답 (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"}

브라우저 확장 프로그램

Tilvar 확장 프로그램은 페이지를 제자리에서 번역하고, 선택한 텍스트와 이미지의 텍스트를 번역하며, 작은 채팅 상자를 제공합니다. 위 API 키와 함께 작동하며 동일한 제한 사항의 적용을 받습니다. 아직 스토어에 없습니다(제출 진행 중); 현재는 수동으로 설치할 수 있습니다:

1. 위에 있는 브라우저에 맞는 zip을 다운로드하고 폴더에 압축을 해제하세요.
2. Chrome/Edge: chrome://extensions "개발자 모드"를 열고 "압축 해제된 확장 프로그램 로드"를 선택한 다음 압축을 해제한 폴더를 선택합니다. Firefox: about:debugging → "이 Firefox" → "임시 추가 기능 로드" (브라우저를 다시 시작한 후 다시 로드해야 합니다. Firefox 스토어 제출 진행 중).
3. 확장 프로그램 아이콘을 클릭하고 API 키를 붙여넣으세요.

데스크톱 앱

자체 창, 시스템 트레이에서, 전역 단축키를 통해 빠른 번역 팝업으로 Tilvar를 사용하세요. 현재 Windows 전용입니다. macOS 및 Linux는 계획 중입니다.

에이전트 모드 (선택 사항): 채팅에서 자신의 컴퓨터에서 실행할 명령을 요청할 수 있습니다. Tilvar는 항상 제안만 하며, 앱에서 정확한 명령을 보고 승인하기 전까지는 아무것도 실행되지 않으며, 승인하더라도 되돌릴 수 없는 패턴(디스크 포맷, 모든 항목 삭제 등)의 짧은 목록은 거부됩니다.

언어 코드

언어는 세 글자 ISO 639-3 코드를 사용합니다: Turkish tur, English eng, German deu, French fra, Spanish spa, Russian rus, Chinese zho, Japanese jpn, Korean kor, Kazakh kaz, Uzbek uzb, Azerbaijani aze. 전체 목록은 GET /api/languages를 호출하십시오.

제한

서버는 작고 공유되므로 API 사용이 제한됩니다. 키는 번역, 채팅 및 이미지 엔드포인트에서만 작동합니다. 웹 앱을 사용하는 것은 이 제한에 포함되지 않습니다.

오류

제한을 초과하는 요청은 Retry-After 헤더(초)와 함께 429를 받습니다. 서버가 바쁠 때는 503를 받습니다.

투르크어족 언어로의 번역은 항상 터키-터키어 알파벳으로 반환됩니다. 번역은 기계 번역이므로 중요한 텍스트는 검토하십시오.