API перевода текста
Переведите текст на нужный язык с учётом контекста и терминологии.
Создайте ключ в консоли API и передавайте его в заголовке Authorization: Bearer <API_KEY>. Перед запуском примеров задайте LECSYNC_API_KEY в окружении сервера. Храните ключ на сервере.
Отправка запроса
POST /v1/translate
Параметры
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
text | string | Да | Непустая строка, до 2000 символов Unicode. |
target_lang | string | Да | Код целевого языка, например ru, en или zh. |
source_lang | string | Нет | Исходный язык; по умолчанию auto. Для короткого или неоднозначного текста лучше задать явно. |
context | string | Нет | Контекст, до 2000 символов Unicode. |
terms | object[] | Нет | До 20 пар {source, target}, каждая сторона до 120 символов Unicode. |
model | string | Нет | Необязательный идентификатор модели; указанное значение используется по умолчанию. translate-default. |
Ответ
Примеры показывают основные поля; ответ также может содержать метаданные использования.
| Поле | Описание |
|---|---|
request_id | Идентификатор запроса для проверки состояния и диагностики; сохраните его. |
status | accepted, processing, succeeded, failed или cancelled. |
text | Переведённый текст. |
source_lang | Исходный язык; по умолчанию auto. Для короткого или неоднозначного текста лучше задать явно. |
target_lang | Код целевого языка, например ru, en или zh. |
unchanged | true, если исходный и целевой языки совпадают; текст возвращён без изменений. |
result_expires_at | Срок хранения результата в ISO 8601; до готовности может быть null. |
Получение результата и повторы
Каждый новый запрос на выполнение должен содержать Idempotency-Key: 1–128 видимых ASCII-символов. Сохраните ключ и повторите его с теми же параметрами, если ответ потерян. Другие параметры с тем же ключом дают 409 IDEMPOTENCY_CONFLICT. Пока запрос выполняется, повтор возвращает его состояние без нового запуска. Новый ключ создаёт новый запрос.
Успешные результаты по умолчанию хранятся 24 часа. Получите их через GET /v1/requests/{request_id}: сохранённое содержимое находится в result. Повтор успешного POST также использует эту обёртку. После истечения срока возвращается 410 RESULT_EXPIRED. Точный срок указан в result_expires_at.
Ограничения и использование
Учитываются символы исходного текста; контекст и термины не учитываются. Совпадение языков не отменяет учёт.
usage.charge_cents — сумма в центах США в виде десятичной строки.
GET /v1/models возвращает доступные модели, языки, ограничения, цены и сроки хранения результатов.
Ошибки
HTTP-ошибка содержит error и request_id; идентификатор также есть в заголовке X-Request-Id. Сохраняйте его для диагностики.
| HTTP | error | Действие |
|---|---|---|
| 401 | UNAUTHORIZED | Проверьте API Key. |
| 402 | INSUFFICIENT_BALANCE | Проверьте баланс API перед повтором. |
| 503 | ADMISSION_DISABLED | Сервис недоступен для этой учётной записи. |
| 409 | IDEMPOTENCY_CONFLICT | Проверьте существующий запрос; для другого ввода используйте новый ключ. |
| 410 | RESULT_EXPIRED | Результат истёк; при необходимости создайте новый запрос. |
| 422 | INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLE | Проверьте имена, типы и обязательные поля. |
| 422 | UNSUPPORTED_LANGUAGE / LANGUAGE_UNDETERMINED | Используйте поддерживаемый язык; при сбое автоопределения задайте source_lang. |
| 429 | RESOURCE_LIMIT | Повторите после интервала Retry-After. |
| 503 | MODEL_UNAVAILABLE / SERVICE_UNAVAILABLE | Перед повтором проверьте состояние запроса. |
| 504 | DEADLINE_EXCEEDED | Перед новым запросом проверьте состояние текущего. |