API для перевода документов

node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --start

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/7",
  "format": "txt",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

POST /api/v1/quotes?output=best-effort-v1

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "my-document-0001",
  "payload": {
    "version": "document-ir/7",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...

{
  "version": "document-ir/7",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

Один пример запроса с cURL

Сохраните приведённый выше JSON с расчётом стоимости как payload.json и задайте DOCUMENT_TRANSLATOR_API_KEY в командной оболочке. Эта команда только запрашивает расчёт стоимости. Чтобы начать перевод, отправьте JSON для запуска с полученным идентификатором расчёта и тем же payload на эндпоинт translations.

curl https://document-translator.com/api/v1/quotes \
  -H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

В PowerShell используйте curl.exe и $env:DOCUMENT_TRANSLATOR_API_KEY; напишите команду в одну строку вместо использования символа обратной косой черты для переноса строки, как показано выше.

Кредиты на перевод и ключи API

За каждый документ API в рамках установленных лимитов резервируется один кредит аккаунта. При строгой обработке кредит списывается только после проверки и подготовки результата; для незавершённых заданий, завершившихся ошибкой или отменённых, резерв снимается. При обработке с выдачей результата при частичном успехе небольшие пробелы могут оплачиваться согласованным кредитом, а при серьёзных пробелах или критических ошибках резерв снимается. Ориентируйтесь на outcome.creditOutcome и outcome.completion, а не на предположение, что за каждый готовый результат списан кредит.

В каждом аккаунте можно создать до пяти активных ключей API. Ключи показываются только один раз, хранятся в виде хешей и отзываются в разделе «Аккаунт». Активный ключ даёт доступ к платным переводам аккаунта, включая задания, созданные с помощью другого ключа того же аккаунта. Ключи не дают права входить в аккаунт или совершать платежи.

Повторные попытки и прерванные запросы

GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID

Если запуск запроса прошёл неясно, используйте тот же идентификатор сметы, те же данные и тот же ключ идемпотентности. Повторные идентичные запросы возвращают существующую задачу без повторного списания. Изменение данных или использование ключа для другой сметы приводит к ответу 409. Метаданные задачи и идемпотентности хранятся в течение семи дней после завершения.

Неудачную задачу, которую можно возобновить, можно повторить, пока исходный текст доступен. При повторном запуске сохраняется ID задачи и используются уже обработанные фрагменты. Для каждой задачи допускается не более трёх попыток обработки. Если не удалось скачать результат, можно повторить запрос к конечной точке результата, не запуская перевод заново.

Опрос статуса и загрузка файлов

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

Запрос статуса пакета принимает не более 100 идентификаторов и возвращает { jobs: [...] } только для разрешённых и не удалённых заданий. Во время обработки проверяйте статус примерно каждые пять секунд, а в очереди — каждые пятнадцать секунд. При восстановлении более 100 заданий равномерно чередуйте пакеты. Приостанавливайте проверку в скрытых вкладках и прекращайте её при достижении конечного статуса или постоянной ошибке авторизации.

Когда статус будет «Готово», получите результат, используя ту же авторизацию аккаунта. В нём содержится сопоставление переведённых сегментов для локального восстановления документа. Результаты доступны в течение 24 часов после завершения; при неудачной обработке исходные данные удаляются через час после создания. Для истёкших результатов возвращается код 410. Для удалённых или недоступных заданий возвращается код 404.

queued → processing → ready
                   ↘ failed / cancelled / expired

{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}

Сохраните готовый файл методом PUT, передав его двоичное содержимое, Content-Length и соответствующий Content-Type. Поддерживаются расширения docx, pptx, xlsx, pdf, txt и md; для каждого формата можно сохранить один файл. Максимальный размер выходного файла — 50 MB. Повторный успешный запрос на сохранение оставляет существующий файл без изменений. Запрос GET скачивает сохранённый файл; список доступных форматов указан в savedFormats в статусе задания. Для сохранения и скачивания применяются те же проверки владельца задания, кредиты не списываются, а срок действия в 24 часа не продлевается.

PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}

{binary DOCX body}

GET /api/v1/translations/{id}

{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}

DELETE отменяет незавершённую работу или удаляет доступный текст и сохранённые файлы. Удаление готового результата не возвращает кредиты и не продлевает срок его скачивания. В этой версии вебхуки о завершении отсутствуют.

PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}

{"version":1,"parserVersion":"document-ir/7","fingerprint":"{original SHA-256}","ocr":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/7
X-Source-SHA256: {original SHA-256}

{unchanged original bytes}

GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/source

Баланс и история операций по счёту

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

История доступна только текущему владельцу и использует возвращаемый курсор пагинации. Эндпоинт баланса использует сеанс аккаунта в браузере и возвращает минимум информации о входе и балансе. Пока Checkout ожидает завершения, опрашивайте эндпоинт каждые пять секунд не более десяти раз, приостанавливайте опрос, когда страница скрыта, и прекращайте его, когда поступят кредиты или аккаунт выйдет из системы.

n8n, Make и Zapier

Используйте шаг HTTP-запроса с секретными данными Bearer. Сначала извлеките текст, отправьте JSON-данные на эндпоинт расчёта стоимости, затем отправьте ID расчёта, данные и стабильный ключ идемпотентности длиной от 16 до 80 символов на эндпоинт переводов. Добавьте задержку и запрашивайте статус методом GET до готовности, затем получите результат и восстановите или сохраните переведённый текст. Сохраните ID расчёта и ключ повторной попытки вместе с записью рабочего процесса. Специальный коннектор и загрузка multipart не требуются.

Ограничения и ошибки

• На один документ: до 50 000 исходных слов, 400 000 извлечённых символов и 12 000 текстовых сегментов. Браузер также ограничивает размер исходных файлов до 25 MB, PDF — до 300 страниц, а файлов PowerPoint — до 300 слайдов. Это ограничения на исходный файл, которые проверяются до начала перевода.
• В очереди или обработке может находиться до 100 документов на аккаунт. API-ключи имеют общий лимит: 120 запросов на расчёт стоимости в минуту и пять новых запусков или повторных попыток каждые десять секунд на аккаунт. Соблюдайте значение Retry-After в ответах 429 и используйте ограниченную задержку при временных сбоях; учащение опроса не ускоряет обработку.
• При строгом режиме результат отклоняется, если отсутствуют переводы сегментов, есть дубликаты или ошибки формата; оплата не взимается. В режиме «Максимальное качество» сохраняются проверенные переводы, а в неразрешённых фрагментах может остаться исходный текст; результат и проблемы описываются в отчёте. В содержимое документа не добавляются водяные знаки или упоминания сервиса.

Ошибки содержат сообщение и код. 400 — неверные данные, 401 — неверная авторизация, 402 — недостаточно кредитов, 404 — недоступная задача, 409 — конфликт запроса или состояния, 410 — срок действия истёк, 429 — превышен лимит запросов или пропускной способности, 503 — сервис недоступен.

После начала перевода мы в частном порядке сохраняем резервные копии исходных данных и данных для восстановления документа на срок до 24 часов. Резервные копии удаляются раньше, если вы скачаете готовый файл в исходном формате или удалите перевод. Имена файлов и пароли PDF никогда не загружаются. Поставщику услуг перевода передаётся только извлечённый текст. OCR выполняется в вашем браузере. Сведения о конфиденциальности