API do tłumaczenia dokumentów z zachowaniem układu

Do czego służy API

API pozwala włączyć tłumaczenie dokumentów w procesy firmy: sklep wysyła karty produktów i instrukcje do tłumaczenia przy dodaniu nowego towaru, system ofertowy tłumaczy cenniki, a obieg dokumentów w kancelarii dołącza wersję roboczą w drugim języku. Dostęp do API ma plan Eksport razem z SSO, umową powierzenia przetwarzania danych i SLA 99,9 procent.

Uwierzytelnianie

Każde żądanie zawiera klucz API w nagłówku Authorization: Bearer YOUR_API_KEY. Klucze tworzysz i unieważniasz w panelu konta. Klucz działa w ramach puli stron Twojego planu.

Wysłanie dokumentu

Endpoint POST https://api.globalnie.pl/v1/translate przyjmuje plik w formacie PDF, DOCX, XLSX lub PPTX oraz parametry tłumaczenia.

• file: plik do tłumaczenia (wymagany).
• target_lang: kod języka docelowego, np. de, en, cs (wymagany).
• source_lang: język źródłowy, domyślnie rozpoznawany automatycznie.
• glossary_id: identyfikator listy haseł firmy.
• tone: formal albo neutral.

curl

curl -X POST https://api.globalnie.pl/v1/translate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "target_lang=de" \
  -F "glossary_id=gl_8f31c2" \
  -F "tone=formal"

Python

import requests

url = "https://api.globalnie.pl/v1/translate"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

with open("oferta.pdf", "rb") as f:
    r = requests.post(
        url,
        headers=headers,
        files={"file": f},
        data={"target_lang": "de", "glossary_id": "gl_8f31c2", "tone": "formal"},
    )

job = r.json()
print(job["id"], job["status"])

Odpowiedź JSON

Żądanie zwraca zadanie tłumaczenia. Status zmienia się z queued na processing i done.

{
  "id": "tr_01hx7k2m9q",
  "status": "processing",
  "source_lang": "pl",
  "target_lang": "de",
  "format": "pdf",
  "pages": 12,
  "glossary_id": "gl_8f31c2",
  "created_at": "2026-10-27T09:14:02Z",
  "result_url": null
}

Odbiór wyniku

Stan zadania sprawdzasz zapytaniem GET https://api.globalnie.pl/v1/translate/tr_01hx7k2m9q. Po zakończeniu pole result_url zawiera adres do pobrania pliku w tym samym formacie co źródło. Możesz też podać adres callback_url, na który wyślemy powiadomienie po zakończeniu zadania.

{
  "id": "tr_01hx7k2m9q",
  "status": "done",
  "pages": 12,
  "characters": 31840,
  "result_url": "https://api.globalnie.pl/v1/translate/tr_01hx7k2m9q/download",
  "expires_at": "2026-10-28T09:14:02Z"
}

Limity i usuwanie plików

• Plik do 250 MB w planie Eksport.
• Strony z API zużywają tę samą pulę co tłumaczenia w panelu.
• Plik źródłowy i wynik są usuwane po 24 godzinach od zakończenia zadania, co widać w polu expires_at.
• Dokumenty wysyłane przez API nie służą do trenowania modeli.

Kody błędów