Справочник waafir-translate
Сервер waafir-translate предоставляет подключённому ИИ-клиенту функцию
перевода Waafir в двух формах:
translate_text— фрагмент текста, переводимый прямо в запросе и синхронно.translate_file/translate_file_status— целый документ в комнате данных, переводимый тем же конвейером с сохранением макета, который использует функция продукта ИИ-перевод.
Подключение: https://app.waafir.io/api/mcp/waafir или сервер области
https://app.waafir.io/api/mcp/waafir-translate; имена инструментов на обоих
одинаковые — см. Настройка. Для
translate_text и translate_file_status нужен
PAT с областью доступа
read (или выше); для translate_file нужна write, потому что запуск
перевода документа создаёт долговременные записи и расходует платные
вычислительные ресурсы для перевода.
translate_text
Перевод короткого текста на целевой язык. Вызов синхронный: на входе текст, на выходе текст. Не указывайте исходный язык, чтобы он был определён автоматически; определённый (или указанный) исходный язык возвращается, чтобы вы могли его проверить.
Входные данные
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
text | string | да | Текст для перевода, 1–10 000 байт UTF-8. |
target_lang | string | да | Код целевого языка, например fr, ar, es. |
source_lang | string | нет | Код исходного языка. Не указывайте для автоопределения. |
Выходные данные
{ translated_text, detected_source_lang }translated_text— текст на целевом языке.detected_source_lang— использованный исходный язык: указанный вами или определённый автоматически, еслиsource_langне был указан.
Требования: платный тариф и включённые ИИ-функции вашей организации (по умолчанию включены; администратор организации может отключить их в разделе «Настройки → ИИ и интеграции»). Вызовы также отклоняются, когда ваша организация достигает дневного лимита использования ИИ или пока Waafir приостановил эту функцию; сообщение об ошибке указывает, что именно произошло.
Ограничение размера
Поскольку этот инструмент — синхронный путь, text ограничен 10 000 байт UTF-8 на вызов. Входные данные сверх этого лимита возвращают понятную
ошибку, а не обрезаются молча. Для более крупного содержимого — целых
документов — используйте функцию перевода документов,
которая создана для файлов и сохраняет их макет.
translate_file
Запуск перевода целого документа в комнате данных. Перевод документа
асинхронный — инструмент возвращает ответ, как только задание поставлено в
очередь, а результат вы получаете, опрашивая translate_file_status.
Входные данные
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
file_id | string | да | UUID файла. |
target_lang | string | да | Код целевого языка — один из 28 языков, на которые продукт переводит документы. |
retry | boolean | нет | Повторно запустить перевод, который ранее завершился сбоем. Игнорируется для завершённых или выполняющихся переводов. |
Выходные данные
{ file_id, target_lang, language_name, status, enqueued,
previous_status, delete_with, note? }status—queued,in_progress,already_translatedилиfailed.enqueued— запустил ли работу именно этот вызов. Проверяйте его: инструмент не перезапускает перевод, который уже завершён или выполняется, поэтому повторный вызов возвращаетenqueued: falseи ничего не стоит.previous_status— состояние перевода до этого вызова, прочитанное из самой записи.delete_with— как удалить перевод и вернуть файл к исходному виду.
Один и тот же перевод не выполняется дважды
В отличие от многократного нажатия кнопки «Перевести» в продукте,
translate_file отказывается повторно ставить задание в очередь, пока перевод
того же файла на тот же язык уже находится в состоянии queued, translating
или finalizing, и отказывается перезапускать перевод, завершившийся сбоем, если вы явно не передадите retry: true. Это сделано намеренно: цикл
повторов, ставящий задание в очередь каждый раз, расходовал бы реальные
вычислительные ресурсы для перевода на каждой итерации.
Требования: платный тариф, включённые ИИ-функции вашей организации (по умолчанию включены; администратор организации может отключить их в разделе «Настройки → ИИ и интеграции») и разрешение на чтение и скачивание файла.
Файл, который ещё проверяется. Если файл — новая загрузка или новая версия,
проверку которой Waafir ещё не завершил, translate_file отвечает UNAVAILABLE
с error.reason: "ACTIVATION_PENDING" и сообщением
This file is still being checked. Try again shortly. Ничего не ставится в
очередь; вызовите инструмент снова после короткой паузы.
translate_file_status
Проверка перевода документа и, когда он готов, получение краткосрочного URL для скачивания переведённого файла.
Входные данные
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
file_id | string | да | UUID файла. |
target_lang | string | да | Язык, на который был запрошен перевод. |
Выходные данные
{ file_id, target_lang, language_name, status,
download_url?, expires_in_seconds?, download_withheld_reason? }status—not_found,queued,translating,finalizing,completed,failedилиstale.staleозначает, что исходный файл был откачен к более ранней версии после создания этого перевода, поэтому перевод больше не соответствует документу и больше не выдаётся —download_urlдля него не выпускается. Снова вызовитеtranslate_file, чтобы создать новый. Считайте любой нераспознанный статус значением «не готово», а не ошибкой.download_url— присутствует, только когда переведённый файл готов, его безопасно вам выдать, и у токена включён параметр Читать содержимое документа (Личные токены доступа). Он выдаёт ту же копию, что и скачивание в браузере, с водяным знаком там, где комната добавляет водяные знаки при скачивании, и истекает через несколько минут. Не более 10 ссылок в минуту на токен.- Без Читать содержимое документа вы всё равно получаете
status, аdownload_withheld_reasonравноcontent_grant_required. download_withheld_reason— присутствует вместоdownload_url, когда файл готов, но не выдаётся. Типичный случай: в документе были скрыты данные, а запрашиваемый перевод был создан из исходного документа, поэтому его выдача раскрыла бы содержимое, удалённое при скрытии данных. Снова запуститеtranslate_file, чтобы создать перевод, безопасный с точки зрения скрытия данных.
Каждый URL для скачивания, выпущенный этим инструментом, фиксируется в журнале аудита вашей организации как скачивание файла с указанием токена и пометкой о том, что оно выполнено ИИ-клиентом, — точно так же, как фиксируется скачивание через продукт.