API Penerjemahan Dokumen

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
}

Satu contoh dengan cURL

Simpan JSON penawaran di atas sebagai payload.json dan atur DOCUMENT_TRANSLATOR_API_KEY di shell Anda. Perintah ini hanya meminta penawaran. Untuk memulai, kirim JSON mulai dengan ID penawaran yang dikembalikan dan payload yang identik ke endpoint terjemahan.

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

Di PowerShell, gunakan curl.exe dan $env:DOCUMENT_TRANSLATOR_API_KEY; tulis perintah dalam satu baris, bukan menggunakan tanda garis miring terbalik untuk melanjutkan seperti yang ditampilkan di atas.

Kredit terjemahan dan kunci API

Setiap dokumen API menggunakan satu kredit akun selama masih dalam batas. Pekerjaan ketat hanya dikenai biaya setelah divalidasi dan siap; pekerjaan yang gagal atau dibatalkan sebelum selesai akan melepaskan reservasi. Untuk hasil upaya terbaik, kekurangan kecil dapat menggunakan kredit yang disepakati, sedangkan kekurangan besar atau kesalahan kritis akan melepaskannya. Periksa outcome.creditOutcome dan outcome.completion, jangan berasumsi setiap hasil yang siap telah dikenai biaya.

Buat hingga lima kunci API aktif per akun. Kunci hanya ditampilkan sekali, disimpan dalam bentuk hash, dan dapat dicabut di Akun. Kunci aktif dapat mengakses terjemahan berbayar akun tersebut, termasuk pekerjaan yang dibuat dengan kunci lain di akun yang sama. Kunci tidak memberikan wewenang untuk masuk atau melakukan pembayaran.

Percobaan ulang dan permintaan yang terputus

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

Gunakan kembali ID penawaran, payload, dan kunci idempotensi yang sama setelah permintaan mulai yang hasilnya tidak pasti. Percobaan ulang yang identik akan mengembalikan pekerjaan yang sudah ada tanpa biaya tambahan. Payload yang berubah atau kunci yang digunakan kembali untuk penawaran lain akan menghasilkan respons 409. Metadata pekerjaan dan idempotensi disimpan selama tujuh hari setelah pekerjaan berakhir.

Pekerjaan gagal yang dapat dilanjutkan bisa dicoba ulang selama teks sumbernya masih tersedia. Percobaan ulang mempertahankan ID pekerjaan dan menggunakan kembali bagian yang telah selesai. Setiap pekerjaan maksimal menjalani tiga upaya pemrosesan. Jika unduhan gagal, coba lagi melalui endpoint hasil tanpa memulai terjemahan baru.

Permintaan status dan unduhan

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 batch menerima paling banyak 100 ID dan mengembalikan { jobs: [...] } yang hanya berisi pekerjaan yang diizinkan dan belum dihapus. Lakukan polling kira-kira setiap lima detik saat diproses dan setiap lima belas detik saat dalam antrean. Rotasikan batch secara adil saat memulihkan lebih dari 100 pekerjaan. Hentikan sementara polling di tab tersembunyi dan hentikan saat mencapai status akhir atau terjadi kesalahan otorisasi permanen.

Saat statusnya siap, ambil hasilnya dengan otorisasi akun yang sama. Hasil tersebut berisi pemetaan segmen terjemahan untuk rekonstruksi lokal. Hasil dapat diakses selama 24 jam setelah selesai; input yang gagal akan kedaluwarsa satu jam setelah dibuat. Hasil yang kedaluwarsa mengembalikan 410. Pekerjaan yang dihapus atau tidak dapat diakses mengembalikan 404.

queued → processing → ready
                   ↘ failed / cancelled / expired

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

Simpan file yang sudah selesai dengan PUT menggunakan isi biner, Content-Length, dan Content-Type yang sesuai. Ekstensi yang didukung adalah docx, pptx, xlsx, pdf, txt, dan md, dengan satu file tersimpan per format dan batas ukuran output 50 MB. Jika penyimpanan berhasil diulangi, file yang sudah ada akan tetap digunakan. GET mengunduh file tersimpan; savedFormats pada status pekerjaan mencantumkan format yang tersedia. Penyimpanan dan pengunduhan menggunakan pemeriksaan kepemilikan pekerjaan yang sama, tidak memerlukan kredit tambahan, dan tidak memperpanjang batas waktu 24 jam.

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 membatalkan pekerjaan yang belum selesai atau menghapus teks yang tersedia dan file tersimpan. Menghapus hasil yang sudah selesai tidak akan mengembalikan kredit atau memperpanjang masa unduhnya. Rilis ini tidak menyediakan webhook penyelesaian.

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

Saldo dan riwayat akun

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

Riwayat hanya terbatas pada pemilik saat ini dan menggunakan kursor paginasi yang dikembalikan. Endpoint saldo menggunakan sesi akun browser dan mengembalikan informasi masuk dan saldo yang minimal. Selama Checkout masih tertunda, periksa endpoint tersebut setiap lima detik hingga maksimal sepuluh kali, jeda saat halaman tersembunyi, dan berhenti saat kredit masuk atau akun keluar.

n8n, Make, dan Zapier

Gunakan langkah permintaan HTTP dengan kredensial Bearer rahasia. Ekstrak teks terlebih dahulu, lakukan POST payload JSON ke endpoint kutipan, lalu lakukan POST ID kutipan, payload, dan kunci idempotensi stabil sepanjang 16–80 karakter ke endpoint terjemahan. Tambahkan jeda dan lakukan GET status hingga siap, ambil hasilnya, lalu susun kembali atau simpan teks terjemahan. Simpan ID kutipan dan kunci percobaan ulang bersama catatan alur kerja Anda. Konektor khusus atau unggahan multipart tidak diperlukan.

Batas dan kesalahan

• Maksimal 50.000 kata sumber, 400.000 karakter hasil ekstraksi, dan 12.000 segmen teks per dokumen. Browser juga membatasi file asli hingga 25 MB, PDF hingga 300 halaman, dan file PowerPoint hingga 300 slide. Ini adalah batas sumber yang diperiksa sebelum penerjemahan dimulai.
• Maksimal 100 dokumen dalam antrean atau sedang diproses per akun. Kunci API berbagi kuota 120 kutipan per menit dan lima permintaan baru atau percobaan ulang setiap sepuluh detik per akun. Patuhi Retry-After pada respons 429 dan gunakan backoff terbatas untuk kegagalan sementara; meningkatkan frekuensi polling tidak mempercepat pemrosesan.
• Keluaran ketat menolak segmen terjemahan yang hilang, duplikat, atau tidak valid sebelum penagihan. Keluaran upaya terbaik mempertahankan terjemahan yang sudah divalidasi dan dapat mempertahankan teks asli di bagian yang belum terselesaikan, dengan hasil dan masalah yang menjelaskan hasilnya. Tidak ada tanda air atau atribusi layanan yang ditambahkan ke konten dokumen.

Kesalahan mencakup pesan kesalahan dan kode. 400 menunjukkan masukan tidak valid, 401 otorisasi tidak valid, 402 kredit tidak mencukupi, 404 pekerjaan tidak tersedia, 409 kutipan atau status yang bertentangan, 410 kedaluwarsa, 429 batas laju atau kapasitas, dan 503 layanan tidak tersedia.

Setelah penerjemahan dimulai, kami mencadangkan data asli dan rekonstruksi Anda secara privat hingga 24 jam. Cadangan dihapus lebih cepat setelah file lengkap dalam format asli disimpan atau Anda menghapus terjemahan. Nama file dan kata sandi PDF tidak pernah diunggah. Hanya teks yang diekstrak yang dikirim ke penyedia terjemahan kami. OCR berjalan di browser Anda. Detail privasi