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

Додайте переклад документів до свого застосунку чи робочого процесу. Надішліть витягнутий текст, перекладіть його вибраною мовою та відновіть документ у власному клієнті. Використовуйте передплачені кредити без передплати.

Швидкий початок

  1. Увійдіть і створіть ключ API. Скопіюйте його запис .env у приватний файл .env поруч із прикладом. Для перекладів через API використовуються кредити облікового запису, зокрема доступні бонусні кредити за реєстрацію; денний ліміт вебсайту не застосовується. Ніколи не додавайте ключ до системи контролю версій і не розміщуйте його у відкритому коді браузера.
  2. Завантажити приклад для Node.js. Використовуйте Node.js 22 або новішої версії; пакети не потрібні. Збережіть короткий текстовий документ у кодуванні UTF-8 під назвою input.txt у тій самій папці. Цей приклад підтримує до 16 000 символів; більші документи обробляються кількома сегментами через API нижче.
  3. Виконайте першу команду, щоб переглянути пропозицію без використання кредитів. Перевірте її, а потім виконайте другу команду, щоб перекласти документ і зберегти його як translated.txt. За потреби замініть мову та шляхи.
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

У прикладі виконується опитування, доки завдання не буде готове, і наявний результат ніколи не перезаписується. Збережіть контрольну точку .translation.json і після переривання повторно запустіть ту саму команду: вона відновить наявне завдання та завантаження без повторного списання коштів. Контрольна точка не містить тексту документа чи ключа API. Часове обмеження очікування не скасовує обробку.

API перекладу приймає видобутий текст і повертає перекладені фрагменти. Необов’язкові приватні резервні копії дають змогу відновити документ протягом 24 годин після завершення. Зберіть готовий документ у своєму клієнтському застосунку.

Або скопіюйте https://document-translator.com/api/ і передайте його своєму AI-агенту, щоб розпочати роботу.

Створіть процес перекладу документів

Витягуйте текст зі стабільними ідентифікаторами сегментів у своєму застосунку. Надішліть наведені нижче дані, а потім використайте кожен повернутий ідентифікатор, щоб вставити переклад у документ.

Створити цінову пропозицію

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

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

У відповіді вказано ID розрахунку, кількість слів у вихідному тексті, точну вартість у кредитах і термін дії. Розрахунки дійсні протягом десяти хвилин. Запит розрахунку не резервує кредити й не зберігає текст документа.

За замовчуванням у цінових запитах використовується суворий режим виводу. Додайте output=best-effort-v1 до URL цінового запиту, щоб дозволити часткові результати. Готові результати містять результат і проблеми; перевірте їх перед використанням. Політику визначає ціновий запит.

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/13",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

Під час запуску повторно надішліть початкове тіло запиту, використане для отримання пропозиції. Перш ніж зберігати текст або резервувати кредити, сервер перевіряє власника й канонічний хеш. Порядок ключів у JSON не має значення; якщо змінити текст, порядок сегментів, формат, відбиток або мови, потрібно отримати нову пропозицію.

Прочитайте перекладений результат

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

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

Використайте ідентифікатори сегментів, щоб відновити файл: кінцева точка результату повертає JSON, а не готовий документ. У клієнтській програмі зберігайте пробіли, посилання, стилі та інші структури, які не перекладаються. Кожен сегмент має мати унікальний ідентифікатор довжиною від 1 до 48 символів: літери a–z, цифри 0–9, підкреслення або дефіси. Текст сегмента може містити до 16 000 одиниць коду UTF-16. Відбиток — це хеш SHA-256 байтів оригінального файлу в нижньому регістрі.

Сайт аналізує та відтворює документи. Клієнти API передають видобутий текст і самостійно відтворюють файли. Оптичне розпізнавання тексту (OCR) у браузері підтримує чіткі скани шістьма мовами. Докладніше читайте в поширених запитаннях на головній сторінці. Для складних макетів можуть знадобитися додаткові сторінки або спрощена читабельна версія.

Один приклад запиту з cURL

Збережіть наведений вище JSON пропозиції як payload.json і задайте DOCUMENT_TRANSLATOR_API_KEY у командній оболонці. Ця команда лише запитує пропозицію. Щоб запустити переклад, надішліть JSON запуску з отриманим ID пропозиції та ідентичним тілом запиту до кінцевої точки 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

У разі невизначеного результату запиту на запуск повторно використовуйте той самий 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":2,"parserVersion":"document-ir/9","fingerprint":"{original SHA-256}","ocr":[],"scans":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/9
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-пакет на кінцеву точку розрахунку вартості, а потім надішліть ідентифікатор розрахунку, пакет і стабільний ключ ідемпотентності завдовжки від 16 до 80 символів на кінцеву точку перекладів. Додайте затримку й надсилайте GET-запити для перевірки стану, доки переклад не буде готовий, отримайте результат і відновіть або збережіть перекладений текст. Зберігайте ідентифікатор розрахунку й ключ повторної спроби в записі робочого процесу. Спеціальний конектор або передавання даних через multipart не потрібні.

Обмеження та помилки

Помилки містять повідомлення про помилку та код. 400 означає некоректне введення, 401 — недійсну авторизацію, 402 — недостатньо кредитів, 404 — недоступне завдання, 409 — конфлікт цитати або стану, 410 — завершення строку дії, 429 — обмеження частоти запитів або потужності, а 503 — недоступність сервісу.

Ми зберігаємо приватну копію оригіналу документа протягом 24 годин після завершення перекладу, щоб ви могли відновити файли для завантаження. Копію можна видалити раніше, видаливши переклад. Постачальнику послуг перекладу надсилаємо лише видобутий текст. Деталі конфіденційності