Beranda → Blog → Suara ke teks dengan Python: dari satu berkas ke skrip yang jalan

Suara ke teks dengan Python: dari satu berkas ke skrip yang jalan

Diterbitkan 2026-08-18 · 6 menit baca

Suara ke teks dengan Python hanya empat baris kode. Sisanya di panduan ini adalah bagian yang tidak kentara: format respons mana yang perlu diminta, apa yang harus dilakukan saat berkasnya terlalu besar, dan mengapa skrip pertama Anda akan lebih lambat daripada seharusnya.

Pemasangan dan permintaan pertama

Satu dependensi — SDK resmi OpenAI. API-nya kompatibel di tingkat protokol, jadi tidak perlu klien khusus:

pip install openai
from openai import OpenAI

client = OpenAI(base_url="https://voicesscribe.com/v1", api_key="kunci Anda")

with open("audio.mp3", "rb") as f:
    result = client.audio.transcriptions.create(model="whisper-1", file=f)

print(result.text)

Hanya itu. Simpan kuncinya di variabel lingkungan, bukan di dalam kode:

import os
client = OpenAI(base_url="https://voicesscribe.com/v1", api_key=os.environ["VS_KEY"])

Memilih format respons

Bawaannya mengembalikan objek dengan medan text. Tiga format lain juga penting:

FormatYang dikembalikanDipakai saat
jsonObjek dengan .textBawaan; Anda hanya butuh kata-katanya
verbose_jsonSegmen, waktu, bahasa terdeteksiPenanda waktu, bab, kendali mutu
srt / vttBerkas takarir siap pakai sebagai stringTakarir untuk video
textString polos tanpa pembungkusDiteruskan ke alat lain

Dengan verbose_json, respons juga membawa bahasa terdeteksi dan probabilitasnya — sinyal kualitas termurah yang bisa Anda dapatkan:

r = client.audio.transcriptions.create(
    model="whisper-1", file=f, response_format="verbose_json",
)

for s in r.segments:
    print(f"[{s.start:6.1f}] {s.text.strip()}")

if r.language_probability < 0.6:
    print("rekaman mencurigakan — layak diperiksa manual")

Menangani galat dengan benar

SDK melempar pengecualian bertipe, jadi penanganannya langsung saja. Pembedaan yang penting: sebagian galat layak diulang, sebagian lain akan gagal dengan cara yang sama selamanya.

from openai import APIStatusError, APIConnectionError

try:
    r = client.audio.transcriptions.create(model="whisper-1", file=f)
except APIConnectionError:
    ...                      # jaringan — mengulang masuk akal
except APIStatusError as e:
    if e.status_code == 401:
        raise RuntimeError("kunci API tidak sah")
    if e.status_code == 413:
        raise RuntimeError("berkas di atas 25 MB — kompres ulang atau potong")
    if e.status_code == 429:
        ...                  # limit atau menit habis — tunggu dulu
    raise

Galat 400 biasanya berarti berkasnya kosong atau rusak. Pastikan ia bisa dibuka pemutar sebelum menyalahkan API.

Berkas lebih besar dari 25 MB

Batas per permintaan adalah 25 MB. Ada dua jalan, menurut urutan pilihan.

Kompres ulang dulu. Sebagian besar berkas kebesaran karena ia wav atau stereo bitrate tinggi. Mono 16 kHz memang yang dipakai model di dalamnya:

ffmpeg -i masukan.wav -ac 1 -ar 16000 -b:a 48k keluaran.mp3

Itu mengubah satu jam audio menjadi kira-kira 25 MB — kebanyakan berkas berhenti perlu dipotong sama sekali.

Baru potong, kalau masih perlu. Potong di jeda alih-alih pada menit tetap, supaya kalimatnya tetap utuh:

ffmpeg -i panjang.mp3 -f segment -segment_time 1800 -c copy bagian%03d.mp3

Membuatnya lebih cepat

Skrip pertama yang ditulis semua orang memproses berkas satu per satu dan menghabiskan hampir seluruh waktunya menunggu jaringan. Transkripsi terikat I/O, jadi utas menyelesaikannya:

from concurrent.futures import ThreadPoolExecutor

def transkrip(path):
    with open(path, "rb") as f:
        return client.audio.transcriptions.create(model="whisper-1", file=f).text

with ThreadPoolExecutor(max_workers=4) as pool:
    teks = list(pool.map(transkrip, daftar_path))

Tentukan max_workers dari batas permintaan per detik pada paket Anda, bukan dari jumlah inti CPU. Melebihi batas mengubah permintaan yang berhasil menjadi 429.

Menaikkan akurasi pada kosakata sendiri

Parameter yang paling kurang dimanfaatkan adalah prompt. Ia tidak muncul di keluaran — ia mencondongkan pengenalan ke arah kata-kata yang Anda sebutkan:

r = client.audio.transcriptions.create(
    model="whisper-1", file=f,
    prompt="Produk: Kestrel, Hawknest. Pembicara: Duarte, Wijaya.",
    language="id",
)

Dua puluh sampai empat puluh istilah yang benar-benar muncul di audio Anda bekerja dengan baik; satu paragraf deskripsi umum tidak berpengaruh. Menambahkan language saat audionya satu bahasa menghapus salah deteksi pada potongan pendek.

Kesalahan yang paling banyak memakan waktu

Coba dengan rekaman Anda sendiri. Pendaftaran memakan waktu satu menit, dan menit gratisnya cukup untuk menilai kualitasnya.

Ambil kunci API gratis

Pertanyaan yang sering diajukan

Perlukah pustaka Python khusus?

Tidak, paket resmi openai bisa dipakai apa adanya — API-nya kompatibel di tingkat protokol. Yang berbeda dari setelan bawaan OpenAI hanya alamat basis dan kuncinya.

Perlukah format audionya disiapkan lewat Python?

Tidak ada yang khusus: ogg, opus, mp3, wav, m4a, dan webm diterima apa adanya. Mengubahnya ke mp3 mono 16 kHz hanya soal tetap di bawah batas 25 MB per permintaan.

Bagaimana mendapatkan penanda waktu di Python?

Minta response_format=verbose_json — responsnya berisi segmen dengan waktu mulai dan selesai, ditambah bahasa terdeteksi dan probabilitasnya.

Bisakah banyak berkas ditranskrip paralel?

Bisa, dengan ThreadPoolExecutor. Transkripsi menunggu jaringan, jadi utas adalah alat yang tepat; ukur kolamnya di bawah batas permintaan per detik pada paket Anda.

Apa yang harus dilakukan untuk berkas di atas 25 MB?

Kompres ulang ke mono 16 kHz lebih dulu — itu saja sudah menyelesaikan sebagian besar kasus. Kalau masih terlalu besar, potong di jeda lalu gabungkan hasilnya.

Bacaan terkait