Tilvar API

HTTP経由で独自のツール、スクリプト、ブラウザ翻訳拡張機能からTilvarを使用します。

はじめに

すべてのメンバーがAPIを使用できます。無料ティアが含まれます。サポーターとアカデミックはより高い制限が適用されます。メンバーシップティア
アカウントページでAPIキーを作成します。マイアカウント
すべてのリクエストで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 is a stateless chat (the client keeps the history). messages holds the last 10 messages, the last one from user; tgt is the default target of translation requests; web: true lets the assistant search the web when useful (the query goes through Tor, sources come back in the answer).

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 translates many short texts in one request (for page translation). At most 60 items and 3,500 characters in total. If the server runs out of time it stops; done says how many items were translated, send the rest again.

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、最大 8 MB。
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キーで動作し、同じ制限が適用されます。まだストアにはありません（提出中です）。今のところは手動でインストールできます:

⬇ Firefox用ダウンロード ⬇ Chrome / Edge用ダウンロード

上記のブラウザに対応するzipをダウンロードし、フォルダに展開してください。
Chrome/Edge: chrome://extensions 「デベロッパーモード」を開き、「アンパックされたものを読み込む」を選択し、展開したフォルダを選択します。Firefox: about:debugging → 「このFirefox」→「一時アドオンを読み込む」（ブラウザを再起動した後に再度読み込む必要があります。Firefoxストアへの提出中です）。
拡張機能アイコンをクリックし、APIキーを貼り付けます。

デスクトップアプリ

Tilvarを独自のウィンドウ、システムトレイから、グローバルホットキーのクイック翻訳ポップアップで利用します。今のところWindowsのみです。macOSとLinuxは予定されています。

⬇ Windows用ダウンロード (.exe)

エージェントモード（オプション）: チャットでご自身のコンピューターで実行するコマンドをリクエストできます。Tilvarは提案するだけで、アプリで正確なコマンドを確認して承認するまで何も実行されず、不可逆的なパターンの短いリスト（ディスクのフォーマット、すべて削除など）は承認されても拒否されます。

言語コード

Languages use three-letter ISO 639-3 codes: Turkish tur, English eng, German deu, French fra, Spanish spa, Russian rus, Chinese zho, Japanese jpn, Korean kor, Kazakh kaz, Uzbek uzb, Azerbaijani aze. For the full list call GET /api/languages.

制限

サーバーは小さく共有されているため、APIの使用は制限されています。キーは翻訳、チャット、画像エンドポイントでのみ機能します。ウェブアプリの使用はこれらの制限にはカウントされません。

	サポーター	学術
API characters per day	50,000	100,000
Requests per minute	20	20
並列リクエスト	1	1
リクエストあたりの文字数	4,000	4,000

エラー

制限を超えたリクエストは、Retry-Afterヘッダー（秒）で429が返されます。サーバーがビジーな場合は503が返されます。

401	キーが見つからないか、無効です。
403	キーのティアにはAPIアクセスがありません。
413	テキストが長すぎるため、TilvarのDocumentsタブからドキュメントを送信してください。
429	日々の文字数制限が使い切られました。

トルコ語族の言語への翻訳は、常にトルコ語アルファベットで返されます。翻訳は機械翻訳です。重要なテキストは確認してください。