Lewati ke konten

Masukkan alur kerja dokumen ke dalam aplikasi Anda

Mulai dari mengunggah satu berkas hingga menerjemahkannya, memeriksa progres, dan mengunduh hasilnya. Setiap langkah dijelaskan sesuai urutan integrasi Anda, dengan titik masuk untuk manajemen berkas, pemrosesan dokumen, serta layanan audio dan video.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · autentikasi kunci API · terjemahan file dijalankan sebagai pekerjaan asinkron

Situs ini menjelaskan API cloud HTTP.

01 Mulailah dengan permintaan yang tidak dikenakan kredit

Section titled “01 Mulailah dengan permintaan yang tidak dikenakan kredit”

Pastikan kunci dan jaringan Anda berfungsi sebelum mengunggah file. Pemeriksaan saldo tidak memerlukan kredit dan tidak membuat pekerjaan terjemahan apa pun.

  1. Dapatkan kunci API

    Masuk ke API console dan buat kunci yang diawali dengan sk_. Gunakan kunci terpisah untuk setiap aplikasi dan tetapkan anggaran untuknya.

    Kunci berfungsi untuk akun yang membuatnya. Simpan kunci di server dan baca dari variabel lingkungan; jangan pernah menyimpannya dalam kode sumber halaman web atau repositori publik.

  2. Periksa saldo

    Atur variabel lingkungan OMNIDOC_API_KEY, lalu jalankan salah satu contoh di bawah ini. Jika berhasil, akan dikembalikan JSON; 401 berarti kunci mengalami masalah dan perlu diperiksa. Jangan pernah menampilkan kunci lengkap dalam tiket, tangkapan layar, atau log.

    Terminal window
    export OMNIDOC_API_KEY="sk_your_key"
    curl --fail-with-body --silent --show-error \
    'https://omnidoc.top/api/v1/billing/credits/balance' \
    -H "X-API-Key: $OMNIDOC_API_KEY"

Unggahan yang berhasil hanya berarti file telah disimpan. Setelah Anda membuat pekerjaan, tunggu hingga mencapai status akhir, lalu daftar dan unduh hasilnya.

LangkahMetode dan jalurApa yang harus dipertahankan
Minta unggahanPOST /upload/presignupload_url, upload_headers, finalize_token
Kirim file tersebutPUT ke upload_url yang dikembalikanRespons sukses; permintaan ini tidak menyertakan kunci API
Konfirmasi pengunggahanPOST /upload/finalizedocument.id
Buat sebuah terjemahanPOST /jobsPekerjaan id
Periksa statusGET /jobs/{job_id}completed atau failed
Daftar hasilGET /artifacts?job_id={job_id}ID dan format artefak
Unduh hasilGET /artifacts/{artifact_id}/downloadByte file dan nama file respons

Untuk unggahan langsung, kirim upload_headers dari server persis seperti yang dikembalikan, dan jangan pernah mengirim X-API-Key ke alamat penyimpanan. Jika alamat unggahan kedaluwarsa atau transfer gagal, mintalah yang baru. Rincian: protokol unggahan , mulai cepat , workflow Node.js lengkap dan field permintaan terjemahan .

Setiap entri mencantumkan jalur, bidang permintaan, dan contoh. Status layanan akun Anda serta batas kunci Anda berlaku untuk semuanya.

04 Autentikasi dan kepemilikan sumber daya

Section titled “04 Autentikasi dan kepemilikan sumber daya”

Kunci API mengidentifikasi sebuah akun. Kunci ini bukanlah kata sandi unduhan publik untuk sebuah file.

Header permintaan

Gunakan X-API-Key: sk_… atau Authorization: Bearer sk_…, salah satu dari keduanya per permintaan. Kirim Content-Type: application/json bersama badan JSON.

Apa yang dapat dijangkau oleh sebuah kunci

Kunci hanya mencapai sumber daya yang dapat digunakan oleh akunnya; status layanan, anggaran kunci, dan pengaturan terjemahan yang diizinkan tetap berlaku. Perubahan pada akun serta pembuatan, rotasi, atau pencabutan kunci dilakukan melalui konsol.

Lihat autentikasi, anggaran, dan rotasi dan layanan dan izin .

05 Memasukkan penanganan kegagalan build ke dalam integrasi

Section titled “05 Memasukkan penanganan kegagalan build ke dalam integrasi”

Waktu habis bukan berarti pekerjaan tidak dibuat. Bedakan kesalahan yang dapat dicoba ulang dari permintaan yang perlu diperbaiki, agar tidak ada yang dikirim atau diproses dua kali.

  • Pembuatan idempoten : hasilkan Idempotency-Key untuk setiap operasi pembuatan baru; saat Anda mencoba ulang operasi yang sama, gunakan kembali kunci asli dan badan permintaan yang persis sama. Operasi dokumen, pekerjaan media, dan pembuatan suara memerlukan kunci tersebut; untuk endpoint pembuatan lainnya, lihat halaman referensi masing-masing.
  • Notifikasi asinkron : polling cukup baik untuk integrasi pertama; untuk pemantauan berkelanjutan gunakan SSE , dan untuk menerima status akhir di latar belakang gunakan webhook . .
StatusPeriksa terlebih dahuluApa yang harus dilakukan
401 / 403Kunci, izin, kepemilikan sumber dayaPerbaiki kredensial atau izin; jangan mencoba lagi secara membabi buta
402Kredit yang tersediaIsi ulang, lalu kirimkan lagi
409Kunci dan badan idempotensi, status sumber dayaTanyakan operasi asli sebelum memulai yang baru
422Kesalahan bidang dalam responsPerbaiki parameter atau file
429Bisnis code dan Retry-AfterBatasan laju dan antrian dapat ditunggu hingga berakhir; anggaran kunci yang telah habis harus ditingkatkan terlebih dahulu.
5xxKesalahan layanan sementaraPengulangan eksponensial terbatas; pertahankan kunci idempotensi untuk permintaan pembuatan

Simpan header respons X-Request-Id, waktu permintaan, dan jalur untuk pemecahan masalah; jangan pernah mencatat kunci lengkap. Semua kode kesalahan dan contoh pengulangan terdapat dalam referensi kesalahan . .

06 Periksa cara kerja penagihan sebelum Anda melakukan integrasi

Section titled “06 Periksa cara kerja penagihan sebelum Anda melakukan integrasi”

Tanpa kredit

Mengunggah, memeriksa pekerjaan, mengunduh hasil, serta membaca saldo dan catatan penyelesaian tidak dikenakan biaya kredit; demikian pula glosarium, proyek, tag, pencarian, dan berbagi.

Dibebankan berdasarkan penggunaan

Penerjemahan file, alat dokumen, penerjemahan instan, serta layanan audio dan video ditagih berdasarkan penggunaan aktual; pembuatan pekerjaan bukan merupakan biaya akhir.

Sebelum pekerjaan dimulai, hanya ambang batas saldo yang diperiksa; setelah selesai, penggunaan aktuallah yang ditagihkan. Jika saldo tidak mencukupi, selisihnya dicatat sebagai utang, dan kredit yang masuk kemudian akan melunasinya terlebih dahulu. Anda dapat melakukan rekonsiliasi tagihan dan pengembalian dana per pekerjaan atau per operasi kredit. Ketika anggaran suatu kunci habis, Anda tetap dapat melakukan query terhadap pekerjaan, hasil, dan catatan di bawah kunci tersebut.