API suara ke teks untuk audio rekaman

API suara ke teks Hushscript menerima rekaman audio lewat /v1/, lalu memungkinkan skrip Anda melakukan polling pekerjaan dan membaca transkrip. Ini alur transkripsi online, bukan endpoint streaming langsung atau endpoint model pengenalan mentah. Server MCP memakai akun, saldo, dan token bearer yang sama jika klien Anda lebih suka alat daripada panggilan HTTP.

Transkrip audio dan video lewat API

API transkripsi audio menerima file audio yang sudah disiapkan, termasuk suara yang direkam. Untuk integrasi STT (speech-to-text), kirim file rekaman; streaming mikrofon langsung tidak tersedia. Untuk transkripsi video, unggah file MP4 atau MOV yang memiliki trek audio apa adanya: server membaca trek audionya dan melewati videonya. Ekstrak audio dari format video lain terlebih dahulu; API tidak menerima URL video. Alur di browser dijelaskan di video ke teks.

Mulai cepat

API memerlukan token akses pribadi, dan ada dua cara untuk memilikinya. Seseorang membuatnya di bawah Tokens pada halaman MCP di akun, memilih scope-nya, dan menentukan apakah token boleh membeli menit. Atau agen membuka akunnya sendiri tanpa pemegang akun manusia: POST /v1/agent/accounts memulai pendaftaran berbayar, dan POST /v1/agent/accounts/{signup_id}/claim menukar claim secret sekali pakainya dengan akun sungguhan dan token pertama. Dengan cara mana pun, token hanya ditampilkan sekali dan berbentuk hsr1:<region>:pat.<id>.<secret>. Token yang dibuat lewat login OAuth server MCP juga berfungsi di sini; lihat Hubungkan. Token tidak pernah dapat membuat, menampilkan daftar, atau mencabut token lain, dan satu akun memiliki paling banyak 25 token aktif; alur akun agen selengkapnya, termasuk rotasi kredensial, ada di panduan Penggunaan otomatis.

Setelah memegang token, panggil API secara langsung. Contoh ini menggambarkan akun pribadi baru sebelum verifikasi kartu atau pembelian; akun buatan agen dimulai dengan paket menit yang dibayarnya:

curl https://api.hushscript.com/v1/account \
  -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

{
  "balance_seconds": 0,
  "held_seconds": 0,
  "credits_expire_at": null,
  "card_on_file": false,
  "data_region": "eu",
  "limits": {
    "max_active_jobs": 50,
    "max_daily_seconds": 144000,
    "active_jobs": 0,
    "used_today_seconds": 0
  }
}

Respons itu memuat saldo dalam detik, detik yang ditahan oleh pekerjaan yang sedang berjalan, credits_expire_at (selalu null karena menit tidak kedaluwarsa), apakah kartu tersimpan, wilayah data, dan batas penerimaan pekerjaan (max_active_jobs, max_daily_seconds, beserta pemakaiannya). Batas harian adalah batas efektif akun saat ini, bukan nilai untuk di-hardcode. POST /v1/uploads memeriksa menit yang tersedia, bukan kartu: tanpa menit yang cukup, panggilan ini mengembalikan 3001 insufficient_balance.

Apakah API suara ke teks gratis?

Tidak ada tingkat API gratis secara umum, tetapi Anda dapat mencoba alurnya sebelum menulis kode: pratinjau publik mentranskripsikan hingga lima menit dari satu rekaman sebelum Anda masuk. Akun pribadi yang memenuhi syarat kemudian mendapat 30 menit gratis setelah verifikasi kartu (lihat harga untuk cara kerjanya); akun buatan agen melewati menit kredit sambutan dan dimulai dengan paket yang dibelinya saat pendaftaran. Pekerjaan API penuh memerlukan akun dan menit dalam kedua kasus.

Otomatisasi dari awal sampai akhir

Panggilan /v1/ yang sama berfungsi dengan token yang dibuat seseorang di aplikasi atau token yang diklaim agen setelah pendaftaran berbayar (lihat Penggunaan otomatis). Menyimpan kartu memerlukan Checkout yang dihosting di browser; agen dapat menjalankannya. Pembelian off-session berikutnya tetap dapat ditolak jika penerbit kartu meminta autentikasi.

1. Baca akun. GET /v1/account. Jika Anda perlu membeli menit dan card_on_file bernilai false, simpan kartu terlebih dahulu.

2. Simpan kartu, sekali saja. POST /v1/billing/setup-session mengembalikan checkout_url, session_id, dan expires_at:

   curl -X POST https://api.hushscript.com/v1/billing/setup-session \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   {
     "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8",
     "session_id": "seti_1PxYzQ2eZvKYlo2C",
     "expires_at": "2026-09-11T15:45:00Z"
   }

   Buka URL itu di browser yang Anda kendalikan dan selesaikan halaman Stripe yang dihosting; tidak ada yang ditagihkan dan Hushscript tidak pernah melihat kartunya. Setelah itu GET /v1/billing/cards menampilkan kartu tersebut beserta id-nya. POST /v1/billing/cards/default mengganti kartu default jika akun memiliki beberapa kartu.

3. Beli menit. GET /v1/billing/packs mencantumkan lima paket dengan id, seconds, amount, dan currency:

   curl https://api.hushscript.com/v1/billing/packs \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   POST /v1/billing/purchase dengan pack, quick_payment_method_id (id kartu tersimpan), dan idempotency_key membebankan kartu secara off-session dan menjawab balance_seconds yang baru:

   curl -X POST https://api.hushscript.com/v1/billing/purchase \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "pack": "300min",
       "quick_payment_method_id": "pm_2QeT4bY7uX9mK3nP",
       "idempotency_key": "purchase-2026-09-11-02"
     }'

   { "balance_seconds": 18000 }

   Ini memerlukan scope billing, penagihan yang diaktifkan pada token, dan penagihan yang diaktifkan untuk akun. Body tanpa id kartu, atau kartu yang ditolak, ditolak dengan 4021 pat_purchase_requires_app; kartu yang hendak ditantang penerbitnya ditolak dengan 4023 pat_purchase_requires_authentication. Keduanya tidak membuka halaman yang tidak dapat diselesaikan siapa pun.

4. Unggah. POST /v1/uploads dengan size_bytes, duration_seconds (15 detik sampai 10 jam), title opsional, transcription_options, matter_code, dan idempotency_key:

   curl -X POST https://api.hushscript.com/v1/uploads \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "size_bytes": 41943040,
       "duration_seconds": 1200,
       "title": "Q3 board call",
       "transcription_options": { "speaker_detection": true },
       "idempotency_key": "upload-2026-09-11-02"
     }'

   matter_code adalah teks bebas sepanjang paling banyak 64 karakter, dan hanya bermakna untuk token milik sebuah ruang kerja: kode ini ditampilkan pada pekerjaan di buku besar dan laporan pemakaian ruang kerja itu. Ruang kerja dengan kebijakan matter yang disetel ke wajib menolak unggahan yang datang tanpa kode, dengan org_matter_code_required. client_code diterima dan diabaikan, karena klien adalah atribut matter, yang ditetapkan admin ruang kerja.

   Panggilan ini menahan kredit dan menjawab job_id beserta halaman pertama URL bagian presigned:

   {
     "job_id": "job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8",
     "part_urls": [
       { "n": 1, "url": "https://r2.hushscript.com/uploads/job_5e2a91cf.../part-1?X-Amz-Signature=..." }
     ]
   }

   PUT setiap bagian ke URL-nya (secara default bagian 32 MiB, bagian terakhir lebih kecil):

   curl -X PUT "https://r2.hushscript.com/uploads/job_5e2a91cf.../part-1?X-Amz-Signature=..." \
     --data-binary @part-01.bin

   Ambil halaman berikutnya dari GET /v1/uploads/{job}/part-urls?start=<n>, dan panggil POST /v1/uploads/{job}/heartbeat jauh sebelum batas waktu tidak aktif 20 menit selama transfer panjang. Jika URL presigned tidak tersedia, atau satu bagian gagal, PUT /v1/uploads/{job}/parts/{n} mengirim byte bagian itu lewat API; PUT yang diulang menggantikan bagian tersebut, sehingga percobaan ulang aman. Didukung: mp3, m4a, mp4 atau mov (trek audionya dipakai, trek video dilewati), wav, flac, ogg, atau opus, diperiksa di server; ekstrak audio dari format video lain sebelum mengunggah.

5. Mulai dan tunggu. POST /v1/uploads/{job}/complete dengan n dan etag dari setiap bagian yang Anda kirim ke URL presigned (hilangkan parts jika setiap bagian dikirim lewat API):

   curl -X POST https://api.hushscript.com/v1/uploads/job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8/complete \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "parts": [
         { "n": 1, "etag": "\"9f86d081884c7d65\"" }
       ]
     }'

   Setelah itu polling GET /v1/jobs/{id}: state bergerak melewati uploading, queued, dan processing menuju done atau failed, dan pekerjaan yang selesai membawa transcript_id:

   curl https://api.hushscript.com/v1/jobs/job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8 \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   {
     "id": "job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8",
     "state": "done",
     "transcript_id": "trs_2b6e1d4a9f7c3088a1b2c3d4e5f6a7b9"
   }

6. Baca hasilnya. GET /v1/transcripts/{id} mengembalikan metadata dan isi lengkap, beserta nama penutur, bahasa yang terdeteksi, tag, dan tanggal hapus otomatis:

   curl https://api.hushscript.com/v1/transcripts/trs_2b6e1d4a9f7c3088a1b2c3d4e5f6a7b9 \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   GET /v1/transcripts mengembalikan daftar per halaman.

Opsi transkripsi sama persis dengan opsi aplikasi: language_code atau deteksi otomatis, speaker_detection, medical_mode (memerlukan language_code berupa en, es, fr, atau de, ditagih +100%), translation_targets (+25% per bahasa), multichannel, keyterms_prompt, prompt teks bebas, serta dictionary_ids dan prompt_preset_id tersimpan yang tercantum di GET /v1/transcription-context.

Sebagian fungsi akun masih hanya tersedia lewat MCP. Impor dari tautan, pengeditan atau penghapusan transkrip, Insights, ekspor, penyimpanan kamus dan preset instruksi, serta pengaturan akun belum memiliki rute /v1/; server MCP mencakup semuanya dengan token yang sama.

Autentikasi

Setiap panggilan /v1/ membawa token bearer di header Authorization, yang diperiksa terhadap scope sama seperti yang dipakai server MCP:

Panggilan di luar scope token gagal dengan pat_scope_missing, pada 403. Scope billing juga tidak berpengaruh kecuali penagihan diaktifkan baik pada token maupun untuk akun. Panggilan penagihan dengan salah satu sakelar mati gagal dengan pat_scope_missing yang sama; menerbitkan ulang token tidak mengaktifkan sakelar akun. Token tidak dapat membuat, menampilkan daftar, atau mencabut token, dan satu akun memiliki paling banyak 25 token aktif.

11 scope ini dapat dipilih oleh pemanggil. pat:rotate adalah scope terpisah yang diberikan kepada token pertama akun agen dan penerus hasil rotasinya; scope ini memungkinkan token itu menggantikan dirinya sendiri, bukan mengelola token lain. Anda tidak dapat memilihnya saat membuat token di aplikasi.

Endpoint

Dokumen OpenAPI produksi mencantumkan 38 operasi metode/path pada 37 path. Setiap operasi di bawah dibatasi oleh scope yang ditampilkan:

/v1/agent/accounts membuka pendaftaran headless yang belum memiliki token, /v1/agent/accounts/{signup_id}/claim mengubah pendaftaran berbayar menjadi akun sungguhan beserta token pertamanya, dan /v1/agent/credentials/rotate membuat penerus bagi token pemanggil lalu mencabutnya, tanpa menyentuh kredensial lain di akun. Panduan Penggunaan otomatis membahas ketiganya dari awal sampai akhir.

Setiap daftar menerima limit dan cursor buram, dan menjawab next_cursor yang bernilai null pada halaman terakhir. Kembalikan cursor apa adanya; cursor menyandikan posisi, sehingga halaman tidak pernah terlewat atau berulang saat baris baru masuk di antara panggilan.

Definisi lengkap dan terkini, dengan parameter dan skema respons untuk setiap operasi, adalah dokumen OpenAPI: anggaplah dokumen itu sumber kebenaran di atas tabel ini. Dokumen ini disajikan kepada token bearer mana pun tanpa memandang scope, sehingga klien dapat mengambilnya dengan kredensial yang sudah dimilikinya.

Antarmuka MCP

Lebih suka alat daripada HTTP mentah? Server MCP menyediakan akun yang sama lewat 56 alat, bukan endpoint ini, untuk klien yang sudah memakai MCP dan bukan REST. Server ini hanya menawarkan alat yang diizinkan oleh scope token yang terhubung.

Batas

Permintaan yang dibuat dengan token akun manusia dibatasi 1.200 per menit per token. Token hasil rotasi milik akun agen berbagi jatah itu di seluruh akun. Rute penagihan yang memanggil Stripe berbagi batas yang lebih ketat, 60 per menit per akun untuk pemanggil PAT: sesi setup, pembelian, perubahan kartu default, penghapusan kartu, dan cache miss pada daftar kartu. Pembatasan biasa dijawab dengan 429 rate_limited beserta Retry-After dalam detik; tunggu selama itu sebelum mencoba lagi. Pembelian oleh akun agen atau oleh PAT akun manusia berbagi batas 3 percobaan per 24 jam bergulir per akun. Pembelian saat pendaftaran agen dihitung; penolakan atau error setelah reservasi juga dihitung. Pembelian lewat sesi browser manusia dikecualikan. Penolakan karena batas dijawab dengan HTTP 429 beserta 4038 agent_purchase_capped dan Retry-After. Rekaman dapat berdurasi 15 detik sampai 10 jam. GET /v1/account melaporkan batas penerimaan akun saat ini (max_active_jobs, max_daily_seconds).

Sandbox

Tidak ada sandbox transkripsi secara umum: panggilan /v1/ biasa berjalan pada akun sungguhan, dan pembelian memakai uang sungguhan. Pengecualiannya adalah validasi pendaftaran: POST /v1/agent/accounts menerima dry_run: true, mengembalikan signup id dry_ yang tidak dapat diklaim, dan tidak membuka sesi Stripe maupun akun.

Error

Error berupa body JSON yang membawa code numerik stabil dan slug error, dengan status HTTP seperti di bawah. Body error /v1/ adalah proyeksi beku: error, code, dan sekumpulan kunci detail yang tetap. Bentuk error /api tidak dibekukan dan dapat membawa lebih banyak. Kode yang harus ditangani pemanggil otomatis:

Dokumen OpenAPI menyebutkan kode persis yang dapat dikembalikan setiap operasi, dan server MCP menerbitkan seluruh katalognya sebagai resource hushscript://error-codes.