API pro překlad dokumentů

Přidejte překlad dokumentů do své aplikace nebo pracovního postupu. Odešlete extrahovaný text, přeložte jej do zvoleného jazyka a znovu sestavte dokument ve vlastním klientovi. Používejte předplacené kredity bez předplatného.

Rychlý začátek

  1. Přihlaste se a vytvořte klíč API. Zkopírujte jeho záznam .env do soukromého souboru .env vedle ukázkového souboru. Překlady přes API využívají kredity účtu, včetně případných uvítacích kreditů; denní limit webu se na ně nevztahuje. Nikdy klíč neukládejte do systému správy verzí ani do veřejného kódu prohlížeče.
  2. Stáhnout ukázku pro Node.js. Použijte Node.js 22 nebo novější; nejsou potřeba žádné balíčky. Uložte krátký textový dokument v kódování UTF-8 jako input.txt do stejné složky. Tento příklad podporuje až 16,000 znaků; větší dokumenty se prostřednictvím níže uvedeného API zpracují ve více segmentech.
  3. Spuštěním prvního příkazu zobrazíte cenovou nabídku, aniž byste použili kredity. Projděte si ji a poté spusťte druhý příkaz, který přeloží text do španělštiny a uloží soubor translated.txt. Podle potřeby upravte jazyk a cesty.
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

Tento příklad opakovaně kontroluje stav, dokud není úloha připravena, a nikdy nepřepíše existující výstup. Ponechte jeho kontrolní soubor .translation.json a po přerušení znovu spusťte stejný příkaz: obnoví existující úlohu i stažení, aniž by vám byly znovu účtovány kredity. Kontrolní soubor neobsahuje text dokumentu ani klíč API. Časový limit čekání nezruší zpracování.

Překladové API přijímá extrahovaný text a vrací přeložené úseky. Volitelné soukromé zálohy umožňují obnovit dokument do 24 hodin od dokončení. Výsledný dokument sestavte ve své klientské aplikaci.

Nebo zkopírujte https://document-translator.com/api/ a předejte ho svému AI agentovi, který vám pomůže začít.

Vytvořte pracovní postup pro překlad dokumentů

Extrahujte text ve své aplikaci a zachovejte stabilní ID segmentů. Odešlete níže uvedený obsah a pak pomocí vrácených ID vložte každý překlad zpět do dokumentu.

Vytvořit cenovou nabídku

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."
    }
  ]
}

Odpověď obsahuje ID cenové nabídky, počet zdrojových slov, přesnou cenu v kreditech a datum vypršení platnosti. Nabídka platí deset minut. Vyžádáním nabídky se kredity nerezervují ani se neukládá text dokumentu.

Cenové nabídky ve výchozím nastavení používají přísný výstup. Chcete-li povolit částečné výsledky, přidejte do adresy URL nabídky output=best-effort-v1. Hotové výsledky obsahují údaj o výsledku a případných problémech; před použitím je zkontrolujte. Zásady jsou pevně stanoveny v cenové nabídce.

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

Zahájit překlad

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."
      }
    ]
  }
}

Při zahájení znovu odešlete původní payload nabídky. Server před uložením textu nebo rezervací kreditů ověří jeho vlastníka a kanonický hash. Na pořadí klíčů v objektu JSON nezáleží; změna textu, pořadí segmentů, formátu, otisku nebo jazyků vyžaduje novou nabídku.

Přečíst přeložený výsledek

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
}

K opětovnému sestavení souboru použijte ID segmentů; koncový bod výsledku vrací JSON, nikoli hotový dokument. Ve své aplikaci zachovejte mezery, odkazy, styly a další struktury, které se nepřekládají. Každý segment musí mít jedinečné ID o délce 1–48 znaků, které obsahuje pouze a–z, 0–9, podtržítka nebo spojovníky. Text segmentu může obsahovat až 16 000 jednotek kódu UTF-16. Otisk je hash SHA-256 původních bajtů souboru zapsaný malými písmeny.

Web zajišťuje načtení a opětovné sestavení dokumentu. Klienti API dodávají extrahovaný text a soubory sestavují sami. Rozpoznávání textu (OCR) v prohlížeči podporuje zřetelné skeny v šesti jazycích. Podrobnosti najdete v častých dotazech na úvodní stránce. U složitých rozvržení se mohou použít další stránky nebo čitelná náhradní verze.

Jeden příklad požadavku pomocí cURL

Uložte výše uvedený JSON nabídky jako payload.json a nastavte v shellu DOCUMENT_TRANSLATOR_API_KEY. Tento příkaz pouze vyžádá cenovou nabídku. Chcete-li zahájit překlad, odešlete na endpoint translations JSON požadavku na zahájení s vráceným ID nabídky a totožným payloadem.

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

V PowerShellu použijte curl.exe a $env:DOCUMENT_TRANSLATOR_API_KEY; příkaz napište na jeden řádek místo použití pokračování pomocí zpětného lomítka uvedeného výše.

Překladové kredity a klíče API

Každý dokument v API rezervuje jeden kredit účtu v rámci stanovených limitů. U úloh s přísnou kontrolou se kredit strhne až po ověření a připravení výsledku; neúspěšné nebo zrušené nedokončené úlohy rezervaci uvolní. U výstupu s maximálním úsilím mohou drobné nedostatky využít sjednaný kredit, zatímco závažné nedostatky nebo kritické chyby kredit uvolní. Řiďte se hodnotami outcome.creditOutcome a outcome.completion, nikoli předpokladem, že se kredit strhne za každý připravený výsledek.

Pro každý účet můžete vytvořit až pět aktivních klíčů API. Klíče se zobrazí pouze jednou, ukládají se jako hashe a lze je odvolat v sekci Účet. Aktivní klíč umožňuje přístup k placeným překladům daného účtu, včetně úloh vytvořených jiným klíčem v rámci stejného účtu. Klíče neumožňují přihlášení ani platby.

Opakované pokusy a přerušené požadavky

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

Po nejistém požadavku na zahájení použijte stejné ID nabídky, payload a idempotency key. Při opakování se stejnými údaji se vrátí existující úloha bez dalšího poplatku. Změněný payload nebo použití klíče pro jinou nabídku vrátí chybu 409. Metadata úlohy a idempotency se uchovávají sedm dní po ukončení.

Neúspěšnou úlohu, kterou lze obnovit, lze zkusit znovu, dokud je její zdrojový text dostupný. Při opakování si úloha zachová své ID a znovu použije dokončené části. Úlohu lze zpracovat nejvýše třikrát. Pokud se nepodaří stáhnout výsledek, lze znovu zavolat jeho koncový bod, aniž by se spustil další překlad.

Dotazování na stav a stahování

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

Stav dávky přijímá nejvýše 100 ID a vrací { jobs: [...] } obsahující pouze autorizované, nesmazané úlohy. Během zpracování kontrolujte stav přibližně každých pět sekund a ve frontě každých patnáct sekund. Pokud obnovujete více než 100 úloh, střídejte dávky spravedlivě. V neaktivních kartách pozastavte kontrolu a ukončete ji při dosažení konečného stavu nebo při trvalé chybě autorizace.

Až bude stav „připraveno“, načtěte výsledek se stejným ověřením účtu. Obsahuje mapování přeložených segmentů pro místní opětovné sestavení. Výsledky jsou dostupné 24 hodin po dokončení; neúspěšný vstup vyprší hodinu po vytvoření. Výsledky, jejichž platnost vypršela, vracejí stav 410. Smazané nebo nedostupné úlohy vracejí stav 404.

queued → processing → ready
                   ↘ failed / cancelled / expired

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

Uložte dokončený soubor metodou PUT s binárním tělem, hlavičkou Content-Length a odpovídající hlavičkou Content-Type. Podporované přípony jsou docx, pptx, xlsx, pdf, txt a md; pro každý formát lze uložit jeden soubor a limit výstupu je 50 MB. Opakované úspěšné uložení zachová stávající soubor. Metoda GET stáhne uložený soubor; položka savedFormats ve stavu úlohy uvádí dostupné formáty. Ukládání a stahování se řídí stejnou kontrolou vlastnictví úlohy, nespotřebovává další kredity a nikdy neprodlužuje 24hodinovou lhůtu.

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 zruší nedokončenou práci nebo odstraní dostupný text a uložené soubory. Smazání dokončeného výsledku neznamená vrácení kreditů ani prodloužení doby, po kterou je soubor ke stažení. Tato verze nepodporuje webhooky pro dokončení.

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

Zůstatek a historie účtu

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

Historie je dostupná pouze aktuálnímu vlastníkovi a využívá vrácený stránkovací kurzor. Koncový bod zůstatku používá relaci účtu v prohlížeči a vrací pouze základní informace o přihlášení a zůstatku. Během čekající platby Checkout kontrolujte stav každých pět sekund, nejvýše desetkrát, pozastavte kontrolu, když je stránka skrytá, a ukončete ji, jakmile se připíše kredit nebo se účet odhlásí.

n8n, Make a Zapier

Použijte krok s HTTP požadavkem a tajným přihlašovacím údajem Bearer. Nejprve extrahujte text a odešlete datovou část JSON metodou POST na koncový bod pro cenové nabídky. Poté odešlete ID nabídky, datovou část a stabilní idempotency key o délce 16–80 znaků metodou POST na koncový bod překladů. Přidejte prodlevu a pomocí GET kontrolujte stav, dokud nebude překlad připravený, poté načtěte výsledek a přeložený text znovu sestavte nebo uložte. ID nabídky a klíč pro opakování požadavku uchovávejte spolu se záznamem pracovního postupu. Není potřeba vyhrazený konektor ani nahrávání multipart.

Limity a chyby

Chyby obsahují chybovou zprávu a kód. 400 označuje neplatný vstup, 401 neplatnou autorizaci, 402 nedostatek kreditů, 404 nedostupnou úlohu, 409 konfliktující nabídku nebo stav, 410 vypršení platnosti, 429 limit počtu požadavků nebo kapacity a 503 nedostupnou službu.

Soukromou kopii původního dokumentu uchováváme 24 hodin od dokončení překladu, abyste mohli obnovit soubory ke stažení. Kopii můžete odstranit dříve smazáním překladu. Poskytovateli překladové služby odesíláme pouze extrahovaný text. Podrobnosti o soukromí