API do tłumaczenia dokumentów

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/9",
  "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/9",
    "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/9",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

Jedno przykładowe zapytanie z cURL

Zapisz powyższy JSON wyceny jako payload.json i ustaw DOCUMENT_TRANSLATOR_API_KEY w powłoce. To polecenie służy tylko do uzyskania wyceny. Aby rozpocząć, wyślij JSON rozpoczęcia z otrzymanym identyfikatorem wyceny i identycznym ładunkiem do punktu końcowego tłumaczeń.

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

W PowerShell użyj curl.exe i $env:DOCUMENT_TRANSLATOR_API_KEY; wpisz polecenie w jednym wierszu, zamiast używać pokazanej wyżej kontynuacji za pomocą ukośnika odwrotnego.

Środki na tłumaczenia i klucze API

Każdy dokument API rezerwuje jeden kredyt na koncie w ramach limitów. Zadania w trybie strict są rozliczane dopiero po sprawdzeniu i przygotowaniu wyniku; nieudane lub anulowane, niedokończone zadania zwalniają rezerwację. W przypadku wyników w trybie best-effort niewielkie braki mogą wiązać się z wykorzystaniem uzgodnionego kredytu, natomiast poważne braki lub krytyczne błędy zwalniają go. Sprawdź outcome.creditOutcome i outcome.completion zamiast zakładać, że za każdy gotowy wynik pobrano opłatę.

Utwórz maksymalnie pięć aktywnych kluczy API na konto. Klucze są wyświetlane tylko raz, przechowywane jako skróty i można je unieważnić w sekcji Konto. Aktywny klucz zapewnia dostęp do płatnych tłumaczeń na tym koncie, w tym zadań utworzonych innym kluczem na tym samym koncie. Klucze nie umożliwiają logowania ani dokonywania płatności.

Ponawianie prób i przerwane żądania

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

Po niepewnym żądaniu rozpoczęcia ponownie użyj tego samego identyfikatora wyceny, ładunku i klucza idempotencji. Identyczne ponowienia zwracają istniejące zadanie bez ponownego obciążenia. Zmieniony ładunek lub użycie tego samego klucza dla innej wyceny zwraca błąd 409. Metadane zadania i idempotencji są przechowywane przez siedem dni po zakończeniu.

Nieudaną, możliwą do wznowienia operację można ponowić, dopóki tekst źródłowy jest dostępny. Ponowienie zachowuje identyfikator zadania i wykorzystuje ukończone fragmenty. Zadania można przetwarzać maksymalnie trzy razy. Nieudane pobieranie można ponowić przez punkt końcowy wyników bez rozpoczynania kolejnego tłumaczenia.

Odpytywanie o status i pobieranie

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

Status zbiorczy przyjmuje maksymalnie 100 identyfikatorów i zwraca obiekt { jobs: [...] } zawierający wyłącznie autoryzowane, nieusunięte zadania. Podczas przetwarzania odpytuj co około pięć sekund, a w kolejce co piętnaście sekund. Odzyskując więcej niż 100 zadań, sprawiedliwie rotuj partie. Wstrzymaj odpytywanie na ukrytych kartach i zakończ je po osiągnięciu stanu końcowego lub w przypadku trwałych błędów autoryzacji.

Gdy stan zmieni się na „gotowe”, pobierz wynik, używając autoryzacji tego samego konta. Zawiera on mapowanie przetłumaczonych segmentów, które umożliwia lokalne odtworzenie dokumentu. Wyniki są dostępne przez 24 godziny od zakończenia; nieudane dane wejściowe wygasają godzinę po utworzeniu. Wygasłe wyniki zwracają kod 410. Usunięte lub niedostępne zadania zwracają kod 404.

queued → processing → ready
                   ↘ failed / cancelled / expired

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

Zapisz gotowy plik metodą PUT, przesyłając jego treść binarną, nagłówek Content-Length i zgodny nagłówek Content-Type. Obsługiwane rozszerzenia to docx, pptx, xlsx, pdf, txt i md. Dla każdego formatu można zapisać jeden plik, a limit rozmiaru pliku wyjściowego wynosi 50 MB. Ponowne zapisanie po udanym zapisie zachowuje istniejący plik. Metoda GET pobiera zapisany plik, a savedFormats w statusie zadania zawiera listę dostępnych formatów. Zapis i pobieranie podlegają tym samym kontrolom uprawnień do zadania, nie zużywają dodatkowych kredytów i nie przedłużają 24-godzinnego terminu.

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 anuluje niedokończone zadanie albo usuwa dostępny tekst i zapisane pliki. Usunięcie ukończonego wyniku nie powoduje zwrotu środków ani wydłużenia okresu pobierania. W tej wersji nie ma webhooków informujących o ukończeniu.

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

Saldo i historia konta

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

Historia jest dostępna tylko dla bieżącego właściciela i korzysta ze zwróconego kursora stronicowania. Endpoint salda korzysta z sesji konta w przeglądarce i zwraca tylko podstawowe informacje o logowaniu i saldzie. Gdy płatność w Checkout oczekuje na realizację, odpytuj endpoint co pięć sekund, maksymalnie dziesięć razy; wstrzymaj odpytywanie, gdy karta jest ukryta, i zakończ je po dodaniu środków lub wylogowaniu z konta.

n8n, Make i Zapier

Użyj kroku żądania HTTP z poufnymi danymi uwierzytelniającymi typu Bearer. Najpierw wyodrębnij tekst, wyślij żądanie POST z ładunkiem JSON do punktu końcowego wyceny, a następnie wyślij żądanie POST z identyfikatorem wyceny, ładunkiem i stabilnym kluczem idempotencji o długości od 16 do 80 znaków do punktu końcowego tłumaczeń. Dodaj opóźnienie i odpytuj status metodą GET, aż tłumaczenie będzie gotowe. Następnie pobierz wynik i odtwórz lub zapisz przetłumaczony tekst. Zapisuj identyfikator wyceny i klucz ponowienia w rekordzie przepływu pracy. Dedykowany konektor ani przesyłanie wieloczęściowe nie są wymagane.

Limity i błędy

• Do 50 000 słów źródłowych, 400 000 wyodrębnionych znaków i 12 000 segmentów tekstu na dokument. Przeglądarka ogranicza też rozmiar oryginalnych plików do 25 MB, plików PDF do 300 stron, a plików PowerPoint do 300 slajdów. Są to limity źródłowe, sprawdzane przed rozpoczęciem tłumaczenia.
• Do 100 dokumentów w kolejce lub przetwarzanych na konto. Klucze API współdzielą limit 120 wycen na minutę oraz pięciu nowych zleceń lub ponowień na 10 sekund na konto. Przestrzegaj nagłówka Retry-After w odpowiedziach 429 i stosuj ograniczone opóźnienia przy tymczasowych błędach; częstsze odpytywanie nie przyspiesza przetwarzania.
• Tryb ścisły odrzuca brakujące, zduplikowane lub nieprawidłowo sformatowane przetłumaczone segmenty przed naliczeniem opłaty. Tryb najlepszej jakości zachowuje zweryfikowane tłumaczenia, a w nierozwiązanych sekcjach może pozostawić tekst oryginalny; wynik i problemy opisują rezultat. Do treści dokumentu nie jest dodawany znak wodny ani informacja o usłudze.

Błędy zawierają komunikat i kod. 400 oznacza nieprawidłowe dane wejściowe, 401 — nieprawidłowe uwierzytelnienie, 402 — niewystarczającą liczbę kredytów, 404 — niedostępne zadanie, 409 — konflikt dotyczący wyceny lub stanu, 410 — wygaśnięcie, 429 — limit częstotliwości lub przepustowości, a 503 — niedostępność usługi.

We keep a private copy of your original document until 24 hours after translation finishes, so you can recover your downloads. You can remove it sooner by deleting the translation. Only extracted text is sent to our translation provider. Szczegóły dotyczące prywatności