Waafir
Эта страница переведена машинным способом и ожидает проверки человеком. Возможны неточности.

Справочник 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

Перевод короткого текста на целевой язык. Вызов синхронный: на входе текст, на выходе текст. Не указывайте исходный язык, чтобы он был определён автоматически; определённый (или указанный) исходный язык возвращается, чтобы вы могли его проверить.

Входные данные

ПолеТипОбязательноОписание
textstringдаТекст для перевода, 1–10 000 байт UTF-8.
target_langstringдаКод целевого языка, например fr, ar, es.
source_langstringнетКод исходного языка. Не указывайте для автоопределения.

Выходные данные

{ translated_text, detected_source_lang }
  • translated_text — текст на целевом языке.
  • detected_source_lang — использованный исходный язык: указанный вами или определённый автоматически, если source_lang не был указан.

Требования: платный тариф и включённые ИИ-функции вашей организации (по умолчанию включены; администратор организации может отключить их в разделе «Настройки → ИИ и интеграции»). Вызовы также отклоняются, когда ваша организация достигает дневного лимита использования ИИ или пока Waafir приостановил эту функцию; сообщение об ошибке указывает, что именно произошло.

Ограничение размера

Поскольку этот инструмент — синхронный путь, text ограничен 10 000 байт UTF-8 на вызов. Входные данные сверх этого лимита возвращают понятную ошибку, а не обрезаются молча. Для более крупного содержимого — целых документов — используйте функцию перевода документов, которая создана для файлов и сохраняет их макет.

translate_file

Запуск перевода целого документа в комнате данных. Перевод документа асинхронный — инструмент возвращает ответ, как только задание поставлено в очередь, а результат вы получаете, опрашивая translate_file_status.

Входные данные

ПолеТипОбязательноОписание
file_idstringдаUUID файла.
target_langstringдаКод целевого языка — один из 28 языков, на которые продукт переводит документы.
retrybooleanнетПовторно запустить перевод, который ранее завершился сбоем. Игнорируется для завершённых или выполняющихся переводов.

Выходные данные

{ 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_idstringдаUUID файла.
target_langstringдаЯзык, на который был запрошен перевод.

Выходные данные

{ 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 для скачивания, выпущенный этим инструментом, фиксируется в журнале аудита вашей организации как скачивание файла с указанием токена и пометкой о том, что оно выполнено ИИ-клиентом, — точно так же, как фиксируется скачивание через продукт.