# Tilmoch API — Full Reference

Tilmoch API is a REST translation API specialized in Turkic languages, built by Tahrirchi (Uzbekistan). It powers the Tilmoch translation product and exposes the same models to developers.

Currently only a REST API is offered. An MCP (Model Context Protocol) server is planned, which will let AI agents such as Claude use Tahrirchi translation as a tool directly.

## Getting started

1. Register at the portal to get an account. New accounts receive 1,000 UZS of free credit.
2. Create an API key in the dashboard ("Kalitlar" / Keys section).
3. Call the endpoint below.

## Endpoint

```
POST https://websocket.tahrirchi.uz/translate-v2
Content-Type: application/json
Authorization: YOUR_API_KEY
```

The API key is sent as the raw value of the `Authorization` header (no `Bearer` prefix).

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| text | string | yes | Text to translate, max 5000 characters per request |
| source_lang | string | yes | Source language code (see below) |
| target_lang | string | yes | Target language code (see below) |
| model | string | yes | `"tilmoch"` or `"sayqalchi"` |
| format | string | no | `"text"` (default) or `"html"` — see HTML translation below |

Example request:

```json
{
  "text": "Salom dunyo!",
  "source_lang": "uzn_Latn",
  "target_lang": "eng_Latn",
  "model": "sayqalchi"
}
```

## Response

Success:

```json
{
  "translated_text": "Hello world!"
}
```

Errors return a JSON body with a `message` field describing the problem.

## Batch translation

To translate multiple texts in a single request, send a `texts` array (of strings) instead of the single `text` field. The response returns a `translated_texts` array in the same order. `source_lang`, `target_lang` and `model` apply to the whole batch. Each element is billed separately and the 5000-character limit applies per element.

Example request:

```json
{
  "texts": ["Salom dunyo!", "Qalaysiz?"],
  "source_lang": "uzn_Latn",
  "target_lang": "eng_Latn",
  "model": "sayqalchi"
}
```

Example response:

```json
{
  "translated_texts": ["Hello world!", "How are you?"]
}
```

## HTML translation

Send `format: "html"` (the default is `"text"`) to translate HTML content. The input is parsed, and only user-visible text is translated — tags, attributes and document structure are preserved and returned in the same field (`translated_text` / `translated_texts`).

- Translated: text nodes, and the attributes `alt`, `title`, `placeholder`, `aria-label`, plus `<meta name="description">` / `<meta name="keywords">` content.
- Left intact: `script`, `style`, `pre`, `code`, `kbd`, `samp`, `var`, `textarea`, `svg`, `math`, `template`; any element with `translate="no"` or class `notranslate`.
- Inline formatting (e.g. `<b>`, `<a>`) is preserved and follows its content when word order changes.
- Billing and the size limit count the extracted text only — never the markup.
- Works with both single `text` and batch `texts`.

Example request:

```json
{
  "text": "<p>Salom <b>dunyo</b>!</p>",
  "source_lang": "uzn_Latn",
  "target_lang": "eng_Latn",
  "model": "sayqalchi",
  "format": "html"
}
```

Example response:

```json
{
  "translated_text": "<p>Hello <b>world</b>!</p>"
}
```

## Supported languages

| Code | Language |
|---|---|
| uzn_Latn | Uzbek (Latin script) |
| uzn_Cyrl | Uzbek (Cyrillic script) |
| uzs_Arab | Southern Uzbek (Arabic script) |
| kaa_Latn | Karakalpak (Latin script) |
| kaa_Cyrl | Karakalpak (Cyrillic script) |
| kaz_Cyrl | Kazakh (Cyrillic script) |
| kir_Cyrl | Kyrgyz (Cyrillic script) |
| tuk_Latn | Turkmen (Latin script) |
| azj_Latn | Azerbaijani (Latin script) |
| tur_Latn | Turkish |
| tgk_Cyrl | Tajik (Cyrillic script) |
| kat_Geor | Georgian |
| rus_Cyrl | Russian |
| eng_Latn | English |
| zho_Hans | Chinese (Simplified) |
| kor_Hang | Korean |

Any pair of these languages can be used as source and target.

## Models

| Model id | Name | Price | Description |
|---|---|---|---|
| tilmoch | Tilmoch | 0.2 UZS per character | Fast and affordable, good for bulk/everyday translation |
| sayqalchi | Sayqalchi | 0.35 UZS per character | Higher quality, better context and style handling (recommended) |

## Limits

- Max 5000 characters per request (both models)
- Max 50 requests per minute (both models)
- Contact info@tahrirchi.uz for higher limits

## Pricing

Pay-as-you-go: you are billed per character of input text at the model's rate. No subscription. Top up your balance in the dashboard via local payment systems (Click, Payme). New accounts get 1,000 UZS free credit.

## Code example (curl)

```bash
curl -X POST https://websocket.tahrirchi.uz/translate-v2 \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
    "text": "Salom dunyo!",
    "source_lang": "uzn_Latn",
    "target_lang": "eng_Latn",
    "model": "sayqalchi"
  }'
```

## Code example (Python)

```python
import requests

response = requests.post(
    "https://websocket.tahrirchi.uz/translate-v2",
    headers={
        "Content-Type": "application/json",
        "Authorization": "YOUR_API_KEY",
    },
    json={
        "text": "Salom dunyo!",
        "source_lang": "uzn_Latn",
        "target_lang": "eng_Latn",
        "model": "sayqalchi",
    },
)
print(response.json()["translated_text"])
```

## Code example (JavaScript)

```javascript
const response = await fetch('https://websocket.tahrirchi.uz/translate-v2', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    text: 'Salom dunyo!',
    source_lang: 'uzn_Latn',
    target_lang: 'eng_Latn',
    model: 'sayqalchi'
  })
});
const data = await response.json();
console.log(data.translated_text);
```

## Support

- Telegram: https://t.me/tahrirchi_yordam
- Email: info@tahrirchi.uz
- Docs: https://platform.tahrirchi.uz/docs
- Pricing: https://platform.tahrirchi.uz/pricing