Ubah ucapan menjadi teks
Kirim audio melalui koneksi WebSocket dan terima pembaruan transkripsi. Contoh pertama ini membaca rekaman sehingga Anda dapat mempelajari alurnya tanpa menyiapkan mikrofon.
wss://api.starsg.ai/v1/realtime?model=asr-altair-v1-miniBaru mengenal API ucapan? Mulailah dengan empat istilah ini.
- WebSocket
- Koneksi yang tetap terbuka sehingga program Anda dan server dapat bertukar pesan dua arah.
- Model
- Mesin yang melakukan tugas tersebut. Gunakan model tts untuk berbicara dan model asr untuk menuliskannya; salin ID publik persisnya.
- masukan audio
- Rekaman yang akan ditranskrip. Contoh ini menggunakan mono, 24 kHz, 16-bit PCM. Python membaca audio dari file WAV; Node.js membaca file PCM tanpa header.
- Kunci API
- Kredensial akses Anda, dibuat di konsol. Itu masuk dalam header Authorization saat koneksi terbuka.
Koneksi pertama Anda
Pilih metode dan lingkungan integrasi Anda, lalu ikuti langkah-langkah di bawah ini.
Siapkan folder dan instal perpustakaan
Gunakan Python 3.10 atau lebih baru. Buka terminal di folder kosong dan instal OpenAI SDK resmi. Terhubung ke gateway ucapan melalui WebSocket; contohnya diuji dengan versi di bawah ini. Unduh ↗
python3 -m venv .venv .venv/bin/python -m pip install "openai[realtime]==3.35.1"
Setel kunci API Anda
Buat kunci di konsol, lalu ganti YOUR_API_KEY di bawah ini dengan kunci Anda sendiri. Jalankan ini di terminal yang sama seperti contoh. Kelola kunci API ↗
export STARSG_API_KEY="YOUR_API_KEY"
Jaga kerahasiaan kunci Anda. Ini adalah contoh lokal/server, bukan kode browser. Jangan memasukkan kunci API permanen ke halaman web atau repositori publik. Menjalankan contoh akan membuat panggilan model yang dapat ditagih.
Siapkan rekaman singkat
Tempatkan input.wav di folder yang sama: mono, 24,000 Hz, 16-bit PCM WAV, setidaknya 100 ms ucapan. Anda juga dapat menggunakan output.wav dari contoh sintesis dan mengganti namanya menjadi input.wav.
Jika rekaman Anda menggunakan format lain, instal FFmpeg, ganti recording.mp3 dengan nama file Anda, lalu konversikan: FFmpeg ↗
ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
Simpan contoh dan jalankan
Salin contoh lengkap di bawah ini ke dalam file teks biasa baru bernama speech.py di folder ini. Simpan, lalu jalankan perintah ini di terminal yang sama.
.venv/bin/python speech.py
Seperti apa kesuksesan ituTerminal dapat mencetak pembaruan “Sebagian:”, lalu “Final:” diikuti dengan transkripsi yang telah selesai. Beberapa model mungkin hanya memberikan hasil akhir.
Contoh lengkap
Salin seluruh file. Ia menghubungkan, mengkonfigurasi sesi, mengirimkan satu masukan, menunggu selesai dan menutup koneksi. Itu tidak mencoba lagi secara otomatis.
import asyncio
import base64
import json
import os
from pathlib import Path
import wave
from openai import AsyncOpenAI
API_KEY = os.environ["STARSG_API_KEY"]
BASE_URL = "https://api.starsg.ai/v1"
MODEL = "asr-altair-v1-mini"
SESSION = json.loads("{\"type\":\"transcription\",\"audio\":{\"input\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000},\"transcription\":{\"model\":\"asr-altair-v1-mini\"},\"turn_detection\":null}}}")
with wave.open("input.wav", "rb") as source:
if (source.getnchannels(), source.getsampwidth(),
source.getframerate(), source.getcomptype()) != (1, 2, 24000, "NONE"):
raise ValueError("Expected mono, 24 kHz, 16-bit PCM WAV")
pcm = source.readframes(source.getnframes())
if len(pcm) < 4800:
raise ValueError("Audio must be at least 100 ms")
async def main():
async with AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL,
max_retries=0) as client:
async with client.realtime.connect(model=MODEL) as connection:
async def receive():
event = (await connection.recv()).model_dump()
if event["type"] == "error" or event["type"].endswith(".failed"):
raise RuntimeError(json.dumps(event.get("error", event), ensure_ascii=False))
return event
async def wait_for(kind):
while True:
event = await receive()
if event["type"] == kind:
return event
await wait_for("session.created")
await connection.session.update(session=SESSION)
await wait_for("session.updated")
for offset in range(0, len(pcm), 4800):
await connection.input_audio_buffer.append(
audio=base64.b64encode(pcm[offset:offset + 4800]).decode()
)
await connection.input_audio_buffer.commit()
transcripts = {}
while True:
event = await receive()
kind = event["type"]
item = (event.get("item_id"), event.get("content_index", 0))
if kind == "conversation.item.input_audio_transcription.delta":
mode = event.get("text_mode", "snapshot")
if mode == "snapshot":
transcripts[item] = event["delta"]
elif mode == "append":
transcripts[item] = transcripts.get(item, "") + event["delta"]
else:
raise ValueError("Unknown text_mode: " + str(mode))
print("Partial:", transcripts[item])
elif kind == "conversation.item.input_audio_transcription.completed":
if not event.get("transcript", "").strip():
raise ValueError("Empty final transcript")
print("Final:", event["transcript"])
return
async def run():
await asyncio.wait_for(main(), timeout=90)
asyncio.run(run())
Contohnya menggunakan ID model publik. Ketersediaan bergantung pada akun dan lingkungan Anda; pilih model yang mendukung tugas waktu nyata ini. Lihat model ↗
Alur acara
Setiap pesan adalah acara JSON. Kirim berarti program Anda → server; menerima berarti server → program Anda. Tunggu session.updated sebelum mengirim input.
- Menerima
session.createdServer telah membuka sesi. Anda sekarang dapat mengirim konfigurasinya.
- Mengirim
session.updateAtur sesi transkripsi, format audio input, model pengenalan, dan deteksi belokan.
- Menerima
session.updatedServer menerima konfigurasi. Sekarang kirimkan masukannya.
- Mengirim
input_audio_buffer.appendKirim Base64 PCM di bidang audio. Contoh ini menggunakan potongan byte 4,800, setara dengan 100 ms pada format yang dikonfigurasi.
- Mengirim
input_audio_buffer.commitSelesaikan giliran masukan. Dengan turn_detection=null, Anda harus melakukan komitmen secara eksplisit; jangan kirim respons.buat untuk pengakuan.
- Menerima
conversation.item.input_audio_transcription.deltaBaca delta dan text_mode; perbarui item_id dan content_index yang cocok.
- Menerima
conversation.item.input_audio_transcription.completedBidang transkrip adalah teks akhir yang otoritatif. Simpan, lalu tutup contoh satu putaran ini.
Periksa pesan session.update
{
"type": "session.update",
"session": {
"type": "transcription",
"audio": {
"input": {
"format": {
"type": "audio/pcm",
"rate": 24000
},
"transcription": {
"model": "asr-altair-v1-mini"
},
"turn_detection": null
}
}
}
}Referensi parameter
Nama dengan titik menunjukkan lokasi bidang dalam objek JSON. “Wajib” di bawah ini berlaku untuk alur kerja dalam panduan ini. Dukungan dan batasan lanjutan bergantung pada modelnya.
Koneksi dan otentikasi
modelstringDiperlukanParameter kueri yang diperlukan di WebSocket URL. Gunakan ID model publik yang tepat dari katalog realtime. Model ASR dan TTS tidak dapat dipertukarkan.
Contoh / pengaturanasr-altair-v1-miniAuthorizationstringDiperlukanHeader koneksi: Bearer, satu spasi, lalu kunci API Anda. Gunakan kunci untuk lingkungan target; jangan taruh di URL.
Contoh / pengaturanBearer <API_KEY>
Sesi dan masukan
session.typestringDiperlukanGunakan transkripsi hanya untuk pengenalan. Ini mengembalikan teks tanpa menghasilkan balasan suara asisten.
Contoh / pengaturan"transcription"session.audio.input.formatobjectDiperlukanKonfigurasi audio: jenisnya adalah audio/pcm, kecepatannya adalah 24000. Contoh ini menggunakan sampel little-endian 16-bit mono yang ditandatangani: 48,000 byte per detik. Header WAV tidak dikirim melalui soket.
Contoh / pengaturan{"type":"audio/pcm","rate":24000}session.audio.input.transcription.modelstringDiperlukanGunakan ID model publik ASR yang sama dengan kueri URL. Jangan mengganti nama model vendor hulu.
Contoh / pengaturanasr-altair-v1-minisession.audio.input.turn_detectionobject | nullOpsionalContoh ini secara eksplisit menyetel null untuk menonaktifkan deteksi belokan otomatis (VAD). Kirim input_audio_buffer.commit ketika semua audio input telah terkirim. Ini adalah pengaturan yang dipilih, bukan klaim tentang default server.
Contoh / pengaturannullaudiostringDiperlukanBase64-encoded byte PCM mentah di input_audio_buffer.append. Kirim setidaknya 100 ms secara bergantian. MP3, header WAV, nama file, atau URL tidak dapat menggantikan bidang ini.
Pemecahan masalah
Baca kesalahan yang dikembalikan terlebih dahulu. Koneksi terbuka atau transkrip sebagian tidak berarti giliran pengenalan ini telah selesai. Tunggu transkrip terakhirnya.
Modul perintah tidak ditemukan atau hilang
Instal runtime yang dipilih, buka kembali terminal Anda dan jalankan perintah pengaturan di folder proyek. Untuk Python, gunakan juru bahasa .venv yang ditunjukkan di atas; instal websocket-client, bukan paket websocket yang bernama serupa. Contoh Node.js menggunakan paket ws dan file .mjs.
401 / 403 atau kunci API hilang
Periksa apakah variabel lingkungan disetel di terminal ini, API_KEY ANDA telah diganti, dan kuncinya milik lingkungan target. Konfirmasikan akses model dan status akun. Jauhkan kunci dari tangkapan layar dan log.
Jabat tangan gagal, 404 / 503, atau model tidak ditemukan
Periksa nama host WSS, port, jalur /v1/realtime, dan ID model publik yang tepat. Gunakan katalog model realtime untuk lingkungan target. Jangan ikuti pengalihan ke HTTP URL yang tidak aman. 503 mungkin memerlukan operator layanan untuk memeriksa ketersediaan.
Tidak ada kesalahan transkrip atau format audio
Gunakan mono, 24 kHz, bertanda 16-bit little-endian PCM dengan ucapan minimal 100 ms. Python membaca PCM WAV; Node.js membaca PCM tanpa header. Konversikan rekaman menggunakan perintah di atas, bukan hanya mengganti nama ekstensinya.
Batas waktu atau koneksi ditutup sebelum selesai
Contoh berhenti setelah 90 detik. Coba input yang lebih pendek dan periksa akses jaringan. Jangan anggap sebagian transkrip atau sebagian audio sebagai keberhasilan. Periksa apakah permintaan sebelumnya berjalan sebelum mencoba lagi, untuk menghindari panggilan duplikat.
Tidak dapat menemukan input.wav atau input.pcm
Simpan rekaman di samping contoh dan jalankan perintah dari folder itu. Python menggunakan input.wav; Node.js menggunakan input.pcm. Teks terakhir muncul setelah “Final:”; pengenalan tidak membuat file audio.
Latar belakang protokol: OpenAI WebSockets ↗