How baba's Hebrew tools talk to the translation engine
Every AI-backed free tool on this site calls the same internal gateway. This page documents that contract as it exists today.
This page is documentation only; there is no interactive tool on it.
The gateway contract
Every AI-backed free tool on this site (translation, slang, nikud, grammar checking, and the rest) calls a server-side endpoint at POST /api/tools/<tool> with a JSON body of { text, options, session }. The endpoint checks the session, a per-IP hourly burst guard, a cache, then the visitor's daily quota for that tool, before calling the translation model and returning its result plus a remaining count.
Getting a session
A tool call needs a session token first. POST /api/tools/session with a solved Turnstile token returns a signed session good for 12 hours; pass it back as session on every tool call from that browser.
POST /api/tools/session
Content-Type: application/json
{ "turnstileToken": "..." }
→ { "token": "...", "expiresIn": 43200 }Calling a tool
This is the actual shape of the internal translate call, sent from this site's own pages.
POST /api/tools/translate
Content-Type: application/json
{
"text": "I need to renew my passport",
"options": { "direction": "en-he", "speaker": "female", "listener": "male" },
"session": "..."
}
→ {
"translation": "אני צריכה לחדש את הדרכון שלי",
"transliteration": "ani tricha lechadesh et hadarkon sheli",
"remaining": 27
}Tool ids, options and limits
Limits are per visitor per UTC day, except the character cap, which is per request.
| Tool id | Options | Max characters | Daily requests | Daily characters |
|---|---|---|---|---|
translate | direction, speaker, listener | 500 | 30 | 6000 |
slang | direction, speaker, listener | 300 | 10 | 2000 |
biblical | era | 600 | 15 | 5000 |
aramaic | direction | 600 | 15 | 5000 |
yiddish | direction, target | 600 | 15 | 5000 |
pair | source, target, speaker, listener | 500 | 20 | 5000 |
register | register, direction, speaker, listener | 800 | 15 | 6000 |
nikud | style | 800 | 20 | 8000 |
grammar | strictness | 1200 | 15 | 8000 |
tattoo | none | 200 | 10 | 1500 |
lookup | context | 120 | 60 | 3000 |
Error codes
| Code | Status | Meaning |
|---|---|---|
gate | 401 | The session token is missing, expired or was not issued for this IP. Solve the Turnstile challenge again to get a new one. |
too_long | 413 | The text is over that tool's per-request character cap. |
quota | 429 | The daily request or character limit for this tool and session has been reached. It resets at midnight UTC. |
burst | 429 | Too many requests from this IP across every tool in the last hour. |
unavailable | 503 | The quota store is unreachable, so no paid call is made. Retry after a minute. |
Public API status
There is no public API key programme for this engine yet. Anyone wanting Hebrew translation access at scale for a business, newsroom or government use case should go through /enterprise instead of calling the internal /api/tools/* endpoint, which is not for external use and can change without notice.