API ucapan-ke-teks

API ini mentranskripsikan file audio yang sudah selesai sebagai tugas dalam antrean. Kirim file, simpan ID tugas yang dikembalikan, dan ambil informasi tugas hingga pemrosesan selesai. Kirim setiap permintaan melalui HTTPS dengan kredensial akun Anda, baik kredensial HTTP Basic seperti dalam contoh maupun token API, sebagaimana dijelaskan di Autentikasi. Simpan kredensial di server Anda.

Endpoint

Dua host API, https://api.multi.tel dan host kompatibilitas https://api.multitel.net, berbagi tugas, kunci idempotensi, batas, dan penagihan yang sama dalam cakupan akun. Keduanya berbeda dalam pengodean unggahan dan struktur pembungkus respons, jadi gunakan satu host secara konsisten dengan parser yang sesuai.

Pada api.multi.tel, setiap jalur juga tersedia dengan prefiks /v1/speech-to-text sebagai pengganti /v3/speech_to_text, misalnya POST /v1/speech-to-text/estimate. Pada api.multitel.net, gunakan jalur /v3/speech_to_text.

Respons informasi layanan melaporkan mode (batch), realtime (false), paidEnabled (apakah pengiriman baru berbayar saat ini diterima), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) dan maxUploadBytes (26214400), beserta description singkat. Pembacaan ini gratis dan tetap tersedia saat pengiriman berbayar dinonaktifkan; respons 503 transcription_unavailable hanya dikembalikan jika layanan secara keseluruhan tidak tersedia.

Siapkan file audio

Gunakan file audio yang sudah selesai dengan ukuran maksimal 25 MiB (26,214,400 byte) dan durasi maksimal 2 jam (7,200 detik). Saat dikirim, file harus dikenali sebagai media MP3, WAV, Ogg, FLAC, MOV, atau Matroska yang memiliki aliran audio, dengan durasi dalam metadatanya lebih dari nol dan tidak lebih dari 7,200 detik. File yang dikenali tetapi gagal dalam pemeriksaan ini ditolak dengan 422 unsupported_audio. File yang tidak dapat dibaca sebagai salah satu format tersebut saat ini dapat ditolak dengan kesalahan server (500); jangan kirim ulang file seperti itu tanpa perubahan. Ekstensi file saja tidak membuktikan kompatibilitas.

Lolos pemeriksaan ini tidak menjamin audio dapat didekode. Audio diproses sebagai satu atau dua kanal. File dengan lebih dari dua kanal audio, file yang audionya setelah didekode lebih panjang dari 2 jam, atau file lain yang gagal didekode selama pemrosesan berakhir sebagai tugas failed, biasanya dengan decode_failed, dan tidak dikenai biaya. Ubah audio multikanal menjadi mono atau stereo sebelum dikirim.

Petunjuk bahasa opsional berupa kode dua atau tiga huruf kecil untuk bahasa yang diucapkan, misalnya en. Untuk tidak memberikan petunjuk, jangan sertakan kolom tersebut; api.multi.tel menolak string kosong. Petunjuk ini memandu pemrosesan tetapi tidak diperiksa terhadap daftar bahasa yang didukung, jadi gunakan kode yang valid untuk bahasa yang diucapkan.

Kirim tugas transkripsi

Kirim JSON dengan Content-Type: application/json ke POST https://api.multi.tel/v3/speech_to_text. Ukuran isi permintaan dapat mencapai 35 MiB, yang menampung file berukuran maksimal setelah pengodean base64; isi yang lebih besar ditolak dengan 413.

Properti JSON lain apa pun, termasuk idempotency_key, ditolak dengan 400 invalid_transcription_request. Kirim kunci sebagai header.

Kunci idempotensi

Setiap pengiriman memerlukan header Idempotency-Key sepanjang 1 hingga 190 karakter. Gunakan huruf ASCII, angka, -, _, . dan :, tanpa spasi di awal atau akhir: host kompatibilitas memangkas whitespace di sekelilingnya dan mengukur kunci dalam byte, sehingga karakter lain dapat dihitung berbeda oleh masing-masing host. Kunci yang tidak ada, atau panjangnya 191 karakter atau lebih, ditolak dengan 400.

Kunci berlaku dalam cakupan akun Anda dan layanan ucapan-ke-teks, di kedua host dan semua kredensial akun Anda. Mengirim ulang kunci yang sama dengan file dan bahasa yang sama mengembalikan tugas yang sudah ada dengan HTTP 200 dan duplicate: true, apa pun statusnya dan meskipun pemrosesan telah diperbarui sejak tugas dibuat, tanpa biaya tambahan. Menggunakan ulang kunci dengan file atau bahasa berbeda mengembalikan 409 idempotency_conflict. Kunci baru membuat tugas baru meskipun filenya identik, dengan biaya terpisah jika pemrosesan selesai dengan sukses.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

node -e 'process.stdout.write(JSON.stringify({audioBase64:require("node:fs").readFileSync("completed-call.mp3").toString("base64"),language:"en"}))' > completed-call.json

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-call-001" \
  --data-binary @completed-call.json \
  -o speech-job.json \
  https://api.multi.tel/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id'

Tugas baru mengembalikan HTTP 202 dengan kolom yang ditunjukkan di bawah, dan pengiriman ulang mengembalikan HTTP 200 dengan objek tugas lengkap yang dijelaskan di Baca transkrip. Baca ID tugas, berupa UUID, dari data.id. Respons tugas baru tampak seperti ini (pengenal dan nilainya adalah contoh):

{
  "status": "success",
  "data": {
    "id": "3f6c1b2e-8a4d-4e7f-9c21-5b0d7e4a9f13",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "source": "api",
    "durationSeconds": 90.5,
    "billedSeconds": 91,
    "costUsd": "0.007583334",
    "pricePerMinuteUsd": "0.005"
  }
}

Saat tugas berada dalam antrean atau sedang berjalan, durationSeconds, billedSeconds dan costUsd merupakan estimasi dari metadata file. Biaya akhir menggunakan durasi setelah didekode.

Pengiriman juga dapat mengembalikan 402 insufficient_balance ketika saldo prabayar tidak cukup untuk menanggung tugas tersebut beserta tugas lain yang belum selesai, 429 transcription_queue_full ketika akun Anda atau layanan memiliki terlalu banyak tugas yang belum selesai, 429 audio_validation_busy ketika validasi file sudah mencapai kapasitas, dan 503 paid_transcription_not_enabled saat transkripsi berbayar dinonaktifkan. Ulangi respons 429 dan 503 nanti dengan kunci yang sama.

Estimasi tanpa membuat tugas

Kirim isi JSON yang sama ke POST https://api.multi.tel/v3/speech_to_text/estimate. Kunci idempotensi tidak diperlukan. Estimasi memvalidasi dan mengukur file, tetapi tidak mentranskripsikannya, membuat tugas, mencadangkan dana, memeriksa saldo, atau membebankan biaya ke akun Anda. Petunjuk language diterima tetapi tidak memengaruhi estimasi.

Estimasi yang berhasil mengembalikan HTTP 200 dengan estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd dan costUsd di dalam data. Estimasi menggunakan durasi dalam metadata file, sedangkan tugas yang selesai dikenai biaya berdasarkan durasi setelah didekode, yang dapat berbeda. Estimasi menerapkan pemeriksaan file yang sama seperti pengiriman. Estimasi hanya tersedia saat transkripsi berbayar diaktifkan (jika tidak, 503 paid_transcription_not_enabled). Estimasi dapat mengembalikan 429 audio_validation_busy ketika validasi file sudah mencapai kapasitas; coba lagi setelah menunggu sebentar.

Baca transkrip

Lakukan polling pada GET /v3/speech_to_text/JOB_ID seperti dijelaskan dalam panduan alur tugas. Objek tugas berisi kolom berikut:

Transkrip beserta stempel waktu, label bahasa, dan label kanalnya dibuat secara otomatis dan tidak dijamin akurat. Anggap setiap penanda kualitas sebagai alasan untuk meninjau hasil, dan bandingkan nama, angka, serta komitmen penting dengan audio asli. Keheningan panjang dan bagian yang sangat pelan dilewati dan tidak menghasilkan segmen. Hasil tidak mengidentifikasi pembicara individual. Ketika hasil melaporkan channelCount bernilai 2, setiap segmen memiliki channel bernilai A (kanal pertama, atau kiri) atau B (kanal kedua, atau kanan). Ini hanya memisahkan pembicara jika setiap pembicara direkam pada kanal terpisah. Audio dua kanal ditagih satu kali berdasarkan durasi berlalunya, bukan per kanal. Hasil mono tidak memiliki label kanal.

Menggunakan api.multitel.net

Endpoint kompatibilitas POST https://api.multitel.net/v3/speech_to_text menerima multipart/form-data dengan bagian file audio dan kolom opsional language, bukan JSON audioBase64. Nilai language yang kosong dianggap tidak memberikan petunjuk. Kirim header Idempotency-Key yang sama. Jika header tidak ada, host ini juga menerima kolom formulir idempotency_key. Kolom bernama source, free, billing_source, realtime atau stream ditolak dengan 400 unsupported_transcription_option; kolom formulir lainnya diabaikan. Host ini juga mengembalikan kesalahan berikut:

• 400 idempotency_key_required untuk kunci yang tidak ada atau terlalu panjang.
• 400 audio_upload_required untuk unggahan yang tidak ada atau tidak diterima secara lengkap.
• 400 invalid_language untuk bahasa yang tidak valid.
• 413 invalid_audio_size untuk file yang kosong atau terlalu besar.
• 400 invalid_job untuk ID tugas yang formatnya salah.

Respons layanan ucapan-ke-teks dari host ini menggunakan struktur pembungkus {"status":{"code":HTTP_STATUS},"response":{...}}. Perhatikan bahwa status adalah objek, bukan string. Saat berhasil, response memuat objek yang sama dengan data pada host utama, sehingga ID tugas berada di response.id. Saat terjadi kesalahan, response.code memuat kode kesalahan; tidak ada pesan atau ID permintaan. Kegagalan autentikasi (401) dikembalikan oleh pemeriksaan masuk umum host dan dapat memiliki isi berbeda, jadi periksa status HTTP sebelum melakukan parsing. Jangan saling menukar pengodean unggahan atau parser respons antarhost.

Untuk estimasi pada host ini, POST kolom multipart yang sama ke /v3/speech_to_text/estimate. Kunci idempotensi tidak diperlukan, dan estimasi berada di dalam response.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Idempotency-Key: speech-call-001" \
  -F "audio=@completed-call.mp3" -F "language=en" \
  -o speech-job.json \
  https://api.multitel.net/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).response.id'