Machine-readable OpenAPI spec: /openapi.json | Swagger UI
Base URL
Authentication
If the server is configured with API_KEYS, every API request must include the header:
X-API-Key: your-api-key
If API_KEYS is empty — no auth required. Multiple keys are supported (comma-separated on server). If ALLOWED_IPS is set, only listed IPs are accepted (returns 403 otherwise).
Endpoints
POST /v1/process
Full pipeline: stress marks + ёфикация + name phonetics + clitics + morphological patterns.
Request body (JSON):
| Field | Type | Default | Description |
|---|
text | string | required | Input text. Max 20 000 chars |
stress_format | string | "combining" | "combining" (U+0301) | "plus" (+ before vowel) | "none" |
preserve_existing | bool | false | Keep stress marks already present in text (LLM stress). Dictionary overrides still apply |
yoficate | bool | true | Restore letter ё where applicable |
name_phonetics | bool | true | Replace е→э in foreign names (Аделина → Адэлина) |
custom_dict | object | null | null | Per-request stress overrides: {"word": "во́рд"}. Highest priority |
Response (JSON):
| Field | Type | Description |
|---|
result | string | Processed text |
processing_ms | integer | Processing time in milliseconds |
Example:
Response:
{
"result": "Го́ды учёбы не напра́сны. Адэли́на ждё́т весну́.",
"processing_ms": 42
}
POST /v1/yoficate
Only ё-fication (restore letter ё). No stress marks, no name phonetics.
Request body: same schema as /v1/process (only text is used).
Example:
Response:
{"result": "учёба ещё", "processing_ms": 5}
GET /health
Service health check. No auth required.
Response:
{
"status": "ok",
"model": "turbo3.1",
"dictionary_loaded": true,
"overrides": {
"stress": 480,
"yo": 56,
"names": 57,
"function_words": 79
}
}
Stress formats
| Format | Example | Description |
|---|
combining | весна́ | Unicode combining diacritical mark U+0301 after stressed vowel |
plus | в+есна | Plus sign before stressed vowel |
none | весна | No stress marks in output (only ёфикация + phonetics) |
Processing pipeline (layers)
- Normalize — lowercase not applied; preserve case
- Tokenize — split into Cyrillic words, non-Cyrillic tokens, markup
- Clitics — strip stress from function words (prepositions, particles, pronouns)
- Name phonetics — е→э in foreign names (Аделина → Адэлина)
- Yofication — е→ё where applicable (учеба → учёба)
- Stress — priority: custom_dict → stress-overrides.json → morphological patterns → RUAccent model
- Monosyllables — skip (no stress needed for single-vowel words)
Error responses
| HTTP | Code | Description |
|---|
401 | UNAUTHORIZED | Missing or invalid X-API-Key |
403 | FORBIDDEN | Client IP not in ALLOWED_IPS |
413 | TEXT_TOO_LONG | Text exceeds 20 000 characters |
422 | VALIDATION_ERROR | Invalid request body (bad JSON, wrong field type) |
503 | MODEL_NOT_READY | Model still loading or failed to load |
Error response format:
{"error": {"code": "TEXT_TOO_LONG", "message": "Text exceeds 20000 characters"}}
SDK integration notes
- All endpoints accept
Content-Type: application/json
- All responses return
Content-Type: application/json
- Full OpenAPI 3.x spec available at
/openapi.json — use it to auto-generate clients
- Swagger UI at
/docs for interactive testing
- Idempotent: re-processing already processed text produces the same result
- Stress mark U+0301 is a combining character — it follows the stressed vowel, not a separate character