MultiTEL
Pengembang

Tugas ucapan dan terjemahan

Autentikasi permintaan, periksa status tugas, ulangi pengiriman yang hasilnya tidak pasti, selesaikan pembayaran hasil yang menunggu pembayaran, periksa penggunaan, serta tangani kesalahan dan batas.

Di halaman ini
  1. Autentikasi
  2. Periksa status hingga selesai
  3. Ulangi permintaan yang hasilnya tidak pasti dengan aman
  4. Buka akses hasil setelah menambah dana
  5. Periksa penggunaan
  6. Batas
  7. Tangani kesalahan permintaan

Ganti SERVICE di bawah dengan speech_to_text atau translate, dan JOB_ID dengan UUID yang dikembalikan. Semua operasi memerlukan kredensial akun Anda, seperti dijelaskan dalam Autentikasi, dan dibatasi pada akun pemiliknya. Tugas dapat dibaca dari salah satu host API, tetapi masing-masing menggunakan pembungkus responsnya sendiri, jadi gunakan satu host secara konsisten.

HostBerhasilKesalahan
api.multi.tel{"status":"success","data":{...}}{"status":"error","code":"...","message":"...","requestId":"..."}
api.multitel.net{"status":{"code":200},"response":{...}}{"status":{"code":409},"response":{"code":"idempotency_conflict"}}

Pada api.multitel.net, kegagalan autentikasi (401) dikembalikan sebelum pembungkus ini diterapkan dan dapat memiliki isi respons yang berbeda, jadi periksa status HTTP sebelum mengurai respons.

Autentikasi

Setiap permintaan harus membawa kredensial akun Anda. Tugas, kunci idempotensi, batas, penggunaan, dan biaya merupakan milik akun pemilik kredensial tersebut. Semuanya dipakai bersama oleh seluruh kredensial akun itu pada kedua host, terlepas dari kredensial mana yang mengirim permintaan.

  • HTTP Basic (Authorization: Basic atau curl --user). Kredensial yang diterima adalah akun API bertipe kata sandi, subakun, atau login akun Anda. Kami menyarankan akun API khusus. Nama pengguna tidak boleh mengandung titik dua, dan nama pengguna maupun kata sandi tidak boleh kosong.
  • Token Bearer (Authorization: Bearer YOUR_TOKEN). Diterima untuk akun API bertipe token. Akun API token wajib memiliki pembatasan IP, dan permintaan harus berasal dari alamat yang diizinkan. Kedua host API menerima alamat IPv4 dan rentang CIDR yang dikonfigurasi untuk akun tersebut. Token tidak dapat dikirim sebagai kata sandi Basic. Pastikan token berfungsi pada host yang Anda gunakan.
API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Jika akun API dibatasi berdasarkan alamat IP, kirim permintaan dari alamat yang diizinkan. Kredensial yang tidak ada atau tidak valid mengembalikan 401. Pada api.multitel.net, kredensial yang valid tetapi tidak dapat menggunakan layanan ini, misalnya kredensial akun token yang dikirim sebagai Basic, mengembalikan 403 unsupported_transcription_principal atau unsupported_translation_principal. Kegagalan autentikasi berulang dari satu alamat pada api.multitel.net dapat menyebabkan alamat itu diblokir, jadi perbaiki kredensial sebelum mencoba lagi.

Periksa status hingga selesai

Kirim permintaan GET /v3/SERVICE/JOB_ID. Kami menyarankan pemeriksaan status paling sering sekali setiap 3 detik. Pembungkus luar menjelaskan permintaan; periksa status tugas di dalamnya untuk menentukan apakah pemrosesan sudah selesai.

StatusArti
queuedDiterima dan menunggu. Tugas dalam satu akun diproses satu per satu, bergiliran dengan akun lain.
runningSedang diproses. progress dapat bernilai null; nilai null saja tidak berarti tugas macet.
completedHasil tersedia. Simpan dan bandingkan detail penting dengan sumber.
failedPeriksa failureCode. Pekerjaan yang gagal tidak dikenai biaya. Perbaiki penyebabnya dan kirim dengan kunci baru; mengirim ulang kunci yang sama mengembalikan tugas gagal yang sama.
awaiting_paymentPemrosesan selesai, tetapi saldo prabayar tidak cukup untuk menutup biaya. Hasil disimpan dan ditahan sampai pembayaran tugas diselesaikan.
API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

Pada api.multitel.net, atur HOST ke https://api.multitel.net dan baca .response.id alih-alih .data.id.

Ulangi permintaan yang hasilnya tidak pasti dengan aman

Jika pengiriman kehabisan waktu atau mengembalikan 429 maupun status 5xx, kirim ulang masukan yang sama dengan kunci idempotensi yang sama. Respons dari salah satu host dapat hilang atau diganti dengan kesalahan setelah pekerjaan diterima; pengiriman ulang dengan kunci yang sama mengembalikan tugas jika ada. Kunci yang digunakan kembali dengan masukan berbeda mengembalikan 409 idempotency_conflict. Beberapa kesalahan berulang pada setiap percobaan, misalnya 503 saat layanan berbayar dinonaktifkan atau 500 untuk berkas audio yang tidak dapat dibaca, jadi berhenti setelah beberapa percobaan.

Mengubah kunci memiliki dampak yang berbeda untuk setiap layanan.

  • Untuk ucapan ke teks, kunci baru membuat tugas baru dengan biaya terpisah jika pemrosesan selesai dengan sukses. Kunci awal terus mengembalikan tugas awal, bahkan setelah pemrosesan diperbarui.
  • Untuk terjemahan, kunci baru dengan konten identik mengembalikan tugas yang cocok dalam antrean, sedang diproses, selesai, atau menunggu pembayaran tanpa biaya baru. Pekerjaan baru dibuat jika tugas sebelumnya gagal atau versi pemrosesan berubah. Percobaan terjemahan ulang dengan kunci awal mengembalikan 409 setelah perubahan versi pemrosesan, jadi simpan ID tugas awal dan baca tugas secara langsung.

Buka akses hasil setelah menambah dana

Untuk tugas berstatus awaiting_payment, tambahkan dana agar saldo setidaknya sebesar costUsd tugas yang dibulatkan ke atas ke kelipatan $0.00001 berikutnya, lalu kirim POST /v3/SERVICE/JOB_ID/settle. Pendebitan dilakukan dalam kelipatan utuh $0.00001 dan menyertakan sisa yang dibawa dari tugas sebelumnya pada layanan yang sama, sehingga jumlah yang didebit dapat melebihi costUsd dengan selisih kurang dari $0.00001. Pada api.multi.tel, kirim JSON {} atau isi permintaan kosong; properti apa pun dalam isi ditolak dengan 400. api.multitel.net mengabaikan isi permintaan. Penyelesaian pembayaran membuka hasil tersimpan tanpa menjalankan transkripsi atau terjemahan lagi. Respons berisi tugas; pastikan statusnya completed. Jika saldo tetap tidak cukup, tugas tetap berstatus awaiting_payment dan respons tetap HTTP 200.

Untuk ucapan ke teks, penyelesaian pembayaran tugas yang sudah selesai mengembalikannya dengan duplicate: true, sedangkan penyelesaian pembayaran tugas dalam antrean, sedang diproses, atau gagal mengembalikan 409 transcription_not_awaiting_payment. Untuk terjemahan, penyelesaian pembayaran tugas dalam status lain apa pun mengembalikan tugas tanpa perubahan. Penyelesaian pembayaran hanya tersedia selama pemrosesan berbayar diaktifkan (jika tidak, 503). Tugas yang menunggu pembayaran dihitung sebagai biaya yang dicadangkan, sehingga untuk akun prabayar tugas tersebut dapat memblokir pengiriman berbayar baru dengan 402 hingga pembayarannya diselesaikan.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Periksa penggunaan

Gunakan GET /v3/SERVICE/usage. Parameter opsional from dan to adalah tanggal UTC dalam format YYYY-MM-DD, dan kedua tanggal batas disertakan. Jika tidak diisi, from secara default adalah tanggal 30 hari sebelum hari ini dan to adalah hari ini (UTC). to tidak boleh lebih awal daripada from, dan jarak antartanggal paling jauh 366 hari (hingga 367 tanggal). Tanggal kalender yang tidak valid atau rentang terbalik maupun lebih panjang mengembalikan 400, begitu juga parameter kueri lainnya pada api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

Respons berisi mode, currency (USD), from, to dan days, yaitu daftar dengan urutan terbaru terlebih dahulu.

  • Entri ucapan ke teks dikelompokkan berdasarkan tanggal dan sumber. Entri berisi date, source (api atau hpbx untuk rekaman Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd dan debitedUsd.
  • Entri terjemahan dikelompokkan berdasarkan tanggal, sumber, dan mesin. Entri berisi date, source, engine, jobs, sourceCharacters, accruedUsd dan debitedUsd.

accruedUsd adalah nilai biaya yang tepat dengan sembilan angka desimal, sedangkan debitedUsd adalah jumlah yang didebit dengan lima angka desimal. Penggunaan dicatat pada tanggal UTC saat biaya setiap tugas diselesaikan, jadi tugas dalam antrean, sedang diproses, gagal, dan menunggu pembayaran tidak muncul.

Batas

Setiap akun dapat memiliki paling banyak 50 tugas ucapan ke teks dan terjemahan yang belum tuntas secara gabungan: dalam antrean, sedang diproses, atau menunggu pembayaran, termasuk pekerjaan rekaman Hosted PBX. Saat batas itu atau kapasitas layanan keseluruhan tercapai, pengiriman mengembalikan 429 transcription_queue_full atau translation_queue_full. api.multi.tel juga membatasi setiap alamat IP klien hingga 300 permintaan per menit untuk seluruh permintaan ke host itu. Batas ini mengembalikan 429 dengan header pembatasan laju dan isi teks biasa, bukan pembungkus kesalahan JSON.

Tangani kesalahan permintaan

Pada host utama, kegagalan mengembalikan status kesalahan HTTP dan JSON dengan status: "error", code, message dan requestId. Setiap respons juga membawa header X-Request-ID. Anda dapat memberikan nilai sendiri; nilai yang lebih panjang dari 128 karakter dipotong. Host kompatibilitas hanya mengembalikan kode kesalahan dalam response.code. Catat ID permintaan, jika tersedia, dan kode kesalahan; jangan masukkan audio, teks, atau kredensial dalam log.

Status umum:

StatusArti
400Masukan tidak valid.
401Kredensial tidak ada atau tidak valid.
402Saldo prabayar tidak cukup.
403Pada host kompatibilitas, kredensial yang tidak dapat menggunakan layanan ini.
404Tugas atau rute tidak dikenal.
405Metode tidak didukung, atau jalur tidak dikenal di dalam layanan.
409Masukan bertentangan, terjemahan ke bahasa yang sama, atau penyelesaian pembayaran tugas ucapan yang tidak menunggu pembayaran.
413Isi permintaan atau berkas terlalu besar.
422Audio tidak didukung, atau pasangan bahasa standar tidak tersedia.
429Batas antrean, validasi, atau laju permintaan.
500Kesalahan server tak terduga, termasuk berkas audio yang tidak dapat dibaca.
503Layanan dinonaktifkan atau tidak tersedia sementara, atau kredensial yang saat ini tidak dapat diperiksa.

Ikuti kode kesalahan yang dikembalikan, alih-alih menganggap setiap kegagalan validasi memiliki satu status yang sama.

Untuk 429 atau 503, tunggu dan coba lagi dengan jeda yang meningkat serta kunci pengiriman yang sama; patuhi Retry-After jika tersedia. Untuk masukan atau kredensial tidak valid, perbaiki penyebabnya terlebih dahulu. Jangan berulang kali mengirim kunci baru saat tugas sebelumnya masih dalam antrean.