Dokumentasi API

WebSocketAcara yang kompatibel dengan OpenAI

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.

ID Model
Audio masukKirim SMS
WSSwss://api.starsg.ai/v1/realtime?model=asr-altair-v1-mini
Baru 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.

  1. 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 ↗

    bash
    python3 -m venv .venv
    .venv/bin/python -m pip install "openai[realtime]==3.35.1"
  2. 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 ↗

    bash
    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.

  3. 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 ↗

    bash
    ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
  4. 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.

    bash
    .venv/bin/python speech.py
    Seperti apa kesuksesan itu

    Terminal 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.

python
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.

  1. Menerima
    session.created

    Server telah membuka sesi. Anda sekarang dapat mengirim konfigurasinya.

  2. Mengirim
    session.update

    Atur sesi transkripsi, format audio input, model pengenalan, dan deteksi belokan.

  3. Menerima
    session.updated

    Server menerima konfigurasi. Sekarang kirimkan masukannya.

  4. Mengirim
    input_audio_buffer.append

    Kirim Base64 PCM di bidang audio. Contoh ini menggunakan potongan byte 4,800, setara dengan 100 ms pada format yang dikonfigurasi.

  5. Mengirim
    input_audio_buffer.commit

    Selesaikan giliran masukan. Dengan turn_detection=null, Anda harus melakukan komitmen secara eksplisit; jangan kirim respons.buat untuk pengakuan.

  6. Menerima
    conversation.item.input_audio_transcription.delta

    Baca delta dan text_mode; perbarui item_id dan content_index yang cocok.

  7. Menerima
    conversation.item.input_audio_transcription.completed

    Bidang transkrip adalah teks akhir yang otoritatif. Simpan, lalu tutup contoh satu putaran ini.

Periksa pesan session.update
json
{
  "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

modelstringDiperlukan

Parameter kueri yang diperlukan di WebSocket URL. Gunakan ID model publik yang tepat dari katalog realtime. Model ASR dan TTS tidak dapat dipertukarkan.

Contoh / pengaturan asr-altair-v1-mini
AuthorizationstringDiperlukan

Header koneksi: Bearer, satu spasi, lalu kunci API Anda. Gunakan kunci untuk lingkungan target; jangan taruh di URL.

Contoh / pengaturan Bearer <API_KEY>

Sesi dan masukan

session.typestringDiperlukan

Gunakan transkripsi hanya untuk pengenalan. Ini mengembalikan teks tanpa menghasilkan balasan suara asisten.

Contoh / pengaturan "transcription"
session.audio.input.formatobjectDiperlukan

Konfigurasi 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.modelstringDiperlukan

Gunakan ID model publik ASR yang sama dengan kueri URL. Jangan mengganti nama model vendor hulu.

Contoh / pengaturan asr-altair-v1-mini
session.audio.input.turn_detectionobject | nullOpsional

Contoh 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 / pengaturan null
audiostringDiperlukan

Base64-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 ↗