Ubah teks menjadi ucapan
Kirim teks melalui koneksi WebSocket dan terima audio dalam beberapa bagian. Mulailah dengan contoh lengkap yang menyimpan file WAV yang dapat diputar.
wss://api.starsg.ai/v1/realtime?model=tts-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.
- Suara
- Suara yang digunakan untuk sintesis. Pilih voice_id dari katalog model yang dipilih; pengakuan tidak membutuhkan suara.
- 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.
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 mencetak “Tersimpan:” dan membuat output.wav. Buka dengan pemutar audio Anda. Untuk menjalankannya kembali, ganti nama atau hapus file itu terlebih dahulu; contoh tidak akan menimpanya.
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 = "tts-altair-v1-mini"
SESSION = json.loads("{\"type\":\"realtime\",\"output_modalities\":[\"audio\"],\"audio\":{\"output\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000}}}}")
TEXT = "Halo! Ini adalah contoh sintesis pidato pertama saya."
OUTPUT = Path("output.wav")
if OUTPUT.exists():
raise FileExistsError("output.wav exists; rename it before running again")
voice = os.environ.get("SPEECH_VOICE")
if voice:
SESSION["audio"]["output"]["voice"] = voice
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")
await connection.conversation.item.create(item={
"type": "message", "role": "user",
"content": [{"type": "input_text", "text": TEXT}]
})
await connection.response.create()
audio = bytearray()
while True:
event = await receive()
if event["type"] == "response.output_audio.delta":
audio.extend(base64.b64decode(event["delta"], validate=True))
elif event["type"] == "response.done":
if event.get("response", {}).get("status") != "completed":
raise RuntimeError("Audio generation did not complete")
if not audio or len(audio) % 2:
raise ValueError("No valid PCM audio received")
with OUTPUT.open("xb") as target:
with wave.open(target, "wb") as wav:
wav.setparams((1, 2, 24000, 0, "NONE", "not compressed"))
wav.writeframes(audio)
print("Saved:", OUTPUT.resolve())
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 ↗
Untuk memilih suara, temukan voice_id-nya di katalog suara model tersebut dan setel SPEECH_VOICE di terminal Anda sebelum dijalankan. Abaikan untuk menggunakan suara default. Nama tampilan seperti “Alloy” bukanlah voice_id. Ganti VOICE_ID di bawah dengan nilai dari katalog tersebut.
export SPEECH_VOICE="VOICE_ID"
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 tugas, format audio, dan suara opsional.
- Menerima
session.updatedServer menerima konfigurasi. Sekarang kirimkan masukannya.
- Mengirim
conversation.item.createBuat pesan pengguna dengan content.type=input_text dan content.text berisi teks Anda.
- Mengirim
response.createMinta server untuk menghasilkan audio untuk teks tersebut.
- Menerima
response.output_audio.deltaDekode bidang delta Base64 dan kumpulkan byte PCM secara berurutan. Potongan ini bukan file WAV yang terpisah.
- Menerima
response.donePeriksa respon.status selesai, lalu tambahkan header WAV dan simpan audio yang dikumpulkan. Status lainnya adalah kegagalan.
Periksa pesan session.update
{
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": [
"audio"
],
"audio": {
"output": {
"format": {
"type": "audio/pcm",
"rate": 24000
}
}
}
}
}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 / pengaturantts-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 waktu nyata untuk sesi text-to-speech. Ini adalah alur kerja sintesis, bukan percakapan agen suara umum.
Contoh / pengaturan"realtime"session.output_modalitiesstring[]DiperlukanMinta keluaran audio untuk sintesis. Kirim array ini di session.update.
Contoh / pengaturan["audio"]session.audio.output.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.output.voicestringOpsionalvoice_id opsional dari katalog suara model yang dipilih. Ini tercakup dalam model. Abaikan untuk default server; jangan gunakan nama tampilan vendor. Atur sebelum output audio dimulai.
Telusuri suaraDefault / dihilangkan Suara default modelitem.content[].textstringDiperlukanTeks yang akan disintesis, di dalam percakapan.item.buat → item → konten. Atur tipe item konten ke input_text, item.type ke message dan item.role ke pengguna. Batas teks bergantung pada model.
Kontrol suara opsional
Mulailah tanpa kontrol ini. Periksa output_controls model sebelum menambahkannya. Nilai volume atau nada yang tidak didukung menyebabkan kesalahan; mereka tidak diabaikan secara diam-diam. Kunci suara dan kecepatan setelah keluaran audio pertama; volume dan nada dapat diperbarui nanti.
session.audio.output.speednumberOpsionalPengganda kecepatan bicara: 1.0 adalah kecepatan normal. Nilai min/maks yang diterima bergantung pada model; periksa katalog. Atur sebelum audio keluaran pertama.
Contoh / pengaturan1.0session.audio.output.options.volumenumber | nullOpsionalEkstensi platform dalam opsi: pengganda penguatan, nilai netral 1.0. Rentang protokolnya adalah 0 < volume ≤ 10, tetapi model harus mendukungnya. Dihilangkan atau null menggunakan nilai netral; nilai yang tidak didukung ditolak.
Default / dihilangkan1.0session.audio.output.options.pitchnumber | nullOpsionalEkstensi platform dalam opsi: pergeseran nada dalam seminada, nilai netral 0. Rentang protokol luar adalah −24 hingga 24; sebuah model mungkin mengizinkan lebih sedikit. Gunakan batasan yang diiklankan. Dihilangkan atau nol menggunakan nada netral.
Default / dihilangkan0
Pemecahan masalah
Baca pesan kesalahan yang dikembalikan terlebih dahulu. Pembukaan koneksi atau potongan audio yang masuk tidak berarti permintaan berhasil diselesaikan.
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 transkrip, audio tidak valid, atau pemutaran kacau
Periksa 24 kHz, mono, 16-bit little-endian PCM dan setidaknya 100 ms ucapan. Gunakan perintah konversi daripada mengganti nama file. Pengakuan mengirimkan PCM mentah, bukan header WAV. Untuk sintesis, dekode Base64 dan gabungkan potongan PCM sebelum membuat file WAV.
invalid_value atau kontrol yang tidak didukung
Hapus pengaturan kecepatan, volume, dan nada opsional, lalu centang output_controls untuk model yang dipilih. Jangan menggunakan kembali voice_id atau batas numerik model lain. Session.update yang ditolak tidak menerapkan konfigurasi itu.
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.
output.wav sudah ada atau file input tidak ada
Jalankan skrip dari folder yang berisi Speech.py atau Speech.mjs. Letakkan input.wav (Python) atau input.pcm (Node.js) di sana. Ganti nama output.wav sebelumnya sebelum menghasilkan lagi. Baris “Final:” adalah hasil pengenalan; itu tidak membuat file audio.
Latar belakang protokol: OpenAI WebSockets ↗