เปลี่ยนคำพูดเป็นข้อความ
ส่งเสียงผ่านการเชื่อมต่อ WebSocket และรับการอัปเดตการถอดเสียง ตัวอย่างแรกนี้จะอ่านการบันทึกเพื่อให้คุณสามารถเรียนรู้โฟลว์ได้โดยไม่ต้องตั้งค่าไมโครโฟน
wss://api.starsg.ai/v1/realtime?model=asr-altair-v1-miniยังใหม่กับ API คำพูดใช่ไหม เริ่มต้นด้วยคำศัพท์สี่ข้อนี้
- WebSocket
- การเชื่อมต่อที่เปิดอยู่เพื่อให้โปรแกรมของคุณและเซิร์ฟเวอร์สามารถแลกเปลี่ยนข้อความได้ทั้งสองทิศทาง
- แบบอย่าง
- เครื่องยนต์ที่ทำงาน ใช้โมเดล tts ในการพูด และใช้โมเดล asr เพื่อถอดเสียง คัดลอก ID สาธารณะที่ถูกต้อง
- อินพุตเสียง
- การบันทึกที่จะถอดความ ตัวอย่างนี้ใช้โมโน, 24 kHz, PCM 16 บิต Python อ่านเสียงจากไฟล์ WAV; Node.js อ่านไฟล์ PCM โดยไม่มีส่วนหัว
- กุญแจ API
- ข้อมูลรับรองการเข้าถึงของคุณที่สร้างขึ้นในคอนโซล มันจะไปอยู่ในส่วนหัว Authorization เมื่อการเชื่อมต่อเปิดขึ้น
การเชื่อมต่อครั้งแรกของคุณ
เลือกวิธีการผสานรวมและสภาพแวดล้อมของคุณ จากนั้นทำตามขั้นตอนด้านล่าง
เตรียมโฟลเดอร์และติดตั้งไลบรารี่
ใช้ Python 3.10 หรือใหม่กว่า เปิดเทอร์มินัลในโฟลเดอร์ว่างและติดตั้ง OpenAI SDK อย่างเป็นทางการ เชื่อมต่อกับเกตเวย์คำพูดผ่าน WebSocket; ตัวอย่างได้รับการทดสอบกับเวอร์ชันด้านล่าง ดาวน์โหลด ↗
python3 -m venv .venv .venv/bin/python -m pip install "openai[realtime]==3.35.1"
ตั้งค่าคีย์ API ของคุณ
สร้างคีย์ในคอนโซล จากนั้นแทนที่ YOUR_API_KEY ด้านล่างด้วยคีย์ของคุณเอง รันสิ่งนี้ในเทอร์มินัลเดียวกันกับตัวอย่าง จัดการคีย์ API ↗
export STARSG_API_KEY="YOUR_API_KEY"
เก็บกุญแจของคุณไว้เป็นส่วนตัว นี่เป็นตัวอย่างในเครื่อง/เซิร์ฟเวอร์ ไม่ใช่โค้ดของเบราว์เซอร์ อย่าใส่คีย์ API แบบถาวรลงในเว็บเพจหรือที่เก็บข้อมูลสาธารณะ การรันตัวอย่างจะทำให้การเรียกโมเดลที่เรียกเก็บเงินได้
เตรียมบันทึกสั้นๆ
วาง input.wav ไว้ในโฟลเดอร์เดียวกัน: mono, 24,000 Hz, 16-bit PCM WAV, คำพูดอย่างน้อย 100 ms คุณยังสามารถใช้ output.wav จากตัวอย่างการสังเคราะห์และเปลี่ยนชื่อเป็น input.wav
หากการบันทึกของคุณใช้รูปแบบอื่น ให้ติดตั้ง FFmpeg แทนที่ recording.mp3 ด้วยชื่อไฟล์ของคุณ จากนั้นแปลงเป็น: FFmpeg ↗
ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
บันทึกตัวอย่างและรัน
คัดลอกตัวอย่างที่สมบูรณ์ด้านล่างลงในไฟล์ข้อความธรรมดาใหม่ที่ชื่อว่า speech.py ในโฟลเดอร์นี้ บันทึก จากนั้นรันคำสั่งนี้ในเทอร์มินัลเดียวกัน
.venv/bin/python speech.py
ความสำเร็จมีลักษณะอย่างไร.เทอร์มินัลอาจพิมพ์การอัปเดต "บางส่วน:" จากนั้น "สุดท้าย:" ตามด้วยการถอดเสียงที่เสร็จสมบูรณ์ บางรุ่นอาจให้ผลลัพธ์สุดท้ายเท่านั้น
ตัวอย่างที่สมบูรณ์
คัดลอกไฟล์ทั้งหมด โดยจะเชื่อมต่อ กำหนดค่าเซสชัน ส่งข้อมูลหนึ่งรายการ รอจนเสร็จสิ้น และปิดการเชื่อมต่อ มันไม่ลองใหม่โดยอัตโนมัติ
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())
ตัวอย่างนี้ใช้ ID โมเดลสาธารณะ ความพร้อมใช้งานขึ้นอยู่กับบัญชีและสภาพแวดล้อมของคุณ เลือกรุ่นที่รองรับงานเรียลไทม์นี้ ดูโมเดล ↗
โฟลว์เหตุการณ์
แต่ละข้อความคือเหตุการณ์ JSON ส่ง หมายถึง โปรแกรมของคุณ → เซิร์ฟเวอร์; รับหมายถึงเซิร์ฟเวอร์ → โปรแกรมของคุณ รอ session.updated ก่อนที่จะส่งข้อมูล
- รับ
session.createdเซิร์ฟเวอร์ได้เปิดเซสชันแล้ว ตอนนี้คุณสามารถส่งการกำหนดค่าได้แล้ว
- ส่ง
session.updateตั้งค่าเซสชันการถอดเสียง รูปแบบเสียงอินพุต โมเดลการจดจำ และการตรวจจับการหมุน
- รับ
session.updatedเซิร์ฟเวอร์ยอมรับการกำหนดค่า ตอนนี้ส่งข้อมูลเข้า
- ส่ง
input_audio_buffer.appendส่ง Base64 PCM ในช่องเสียง ตัวอย่างนี้ใช้ชิ้นไบต์ 4,800 ซึ่งเทียบเท่ากับ 100 ms ในรูปแบบที่กำหนดค่าไว้
- ส่ง
input_audio_buffer.commitสิ้นสุดการเลี้ยวอินพุต ด้วย turn_detection=null คุณต้องคอมมิตอย่างชัดเจน อย่าส่งการตอบกลับสร้างการรับรู้
- รับ
conversation.item.input_audio_transcription.deltaอ่านเดลต้าและ text_mode; อัพเดต item_id และ content_index ที่ตรงกัน
- รับ
conversation.item.input_audio_transcription.completedช่องการถอดเสียงเป็นข้อความสุดท้ายที่เชื่อถือได้ บันทึก จากนั้นปิดตัวอย่างเทิร์นเดียวนี้
ตรวจสอบข้อความ 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
}
}
}
}การอ้างอิงพารามิเตอร์
ชื่อที่มีจุดแสดงตำแหน่งของฟิลด์ในวัตถุ JSON “จำเป็น” ด้านล่างใช้กับขั้นตอนการทำงานในคู่มือนี้ การสนับสนุนและขีดจำกัดขั้นสูงขึ้นอยู่กับรุ่น
การเชื่อมต่อและการรับรองความถูกต้อง
modelstringที่จำเป็นพารามิเตอร์การสืบค้นที่จำเป็นใน WebSocket URL ใช้รหัสโมเดลสาธารณะที่แน่นอนจากแค็ตตาล็อกเรียลไทม์ รุ่น ASR และ TTS ไม่สามารถใช้แทนกันได้
ตัวอย่าง/การตั้งค่าasr-altair-v1-miniAuthorizationstringที่จำเป็นส่วนหัวการเชื่อมต่อ: Bearer ช่องว่างหนึ่งช่อง ตามด้วยคีย์ API ของคุณ ใช้คีย์สำหรับสภาพแวดล้อมเป้าหมาย อย่าใส่ไว้ใน URL
ตัวอย่าง/การตั้งค่าBearer <API_KEY>
เซสชันและการป้อนข้อมูล
session.typestringที่จำเป็นใช้การถอดเสียงเพื่อการจดจำเท่านั้น ส่งคืนข้อความโดยไม่สร้างการตอบกลับด้วยเสียงของผู้ช่วย
ตัวอย่าง/การตั้งค่า"transcription"session.audio.input.formatobjectที่จำเป็นการกำหนดค่าเสียง: ประเภทคือเสียง/pcm อัตราคือ 24000 ตัวอย่างนี้ใช้ตัวอย่าง little-endian โมโนที่ลงนาม 16: ไบต์ 48,000 ต่อวินาที ส่วนหัว WAV จะไม่ถูกส่งผ่านซ็อกเก็ต
ตัวอย่าง/การตั้งค่า{"type":"audio/pcm","rate":24000}session.audio.input.transcription.modelstringที่จำเป็นใช้ ID โมเดลพับลิก ASR เดียวกันกับเคียวรี URL อย่าแทนที่ชื่อรุ่นของผู้จำหน่ายอัปสตรีม
ตัวอย่าง/การตั้งค่าasr-altair-v1-minisession.audio.input.turn_detectionobject | nullไม่จำเป็นตัวอย่างนี้ตั้งค่า null ไว้อย่างชัดเจนเพื่อปิดใช้งานการตรวจจับการเลี้ยวอัตโนมัติ (VAD) ส่ง input_audio_buffer.commit เมื่อส่งสัญญาณเสียงอินพุตทั้งหมดแล้ว นี่เป็นการตั้งค่าที่เลือก ไม่ใช่การอ้างสิทธิ์เกี่ยวกับค่าเริ่มต้นของเซิร์ฟเวอร์
ตัวอย่าง/การตั้งค่าnullaudiostringที่จำเป็นไบต์ PCM ดิบของ Base64-encoded ใน input_audio_buffer.append ส่งอย่างน้อย 100 ms ในเทิร์นที่คอมมิต MP3, ส่วนหัว WAV, ชื่อไฟล์ หรือ URL ไม่สามารถแทนที่ฟิลด์นี้ได้
การแก้ไขปัญหา
อ่านข้อผิดพลาดที่ส่งคืนก่อน การเชื่อมต่อแบบเปิดหรือการถอดเสียงบางส่วนไม่ได้หมายความว่าการเปิดการรับรู้นี้เสร็จสมบูรณ์แล้ว รอทรานสคริปต์สุดท้าย
ไม่พบคำสั่งหรือโมดูลหายไป
ติดตั้งรันไทม์ที่เลือก เปิดเทอร์มินัลของคุณอีกครั้ง และรันคำสั่งการตั้งค่าในโฟลเดอร์โปรเจ็กต์ สำหรับ Python ให้ใช้ล่าม .venv ที่แสดงด้านบน ติดตั้ง websocket-client ไม่ใช่แพ็คเกจ websocket ที่มีชื่อคล้ายกัน ตัวอย่าง Node.js ใช้แพ็คเกจ ws และไฟล์ .mjs
401 / 403 หรือคีย์ API หายไป
ตรวจสอบว่ามีการตั้งค่าตัวแปรสภาพแวดล้อมในเทอร์มินัลนี้ YOUR_API_KEY ถูกแทนที่ และคีย์เป็นของสภาพแวดล้อมเป้าหมาย ยืนยันการเข้าถึงโมเดลและสถานะบัญชี เก็บคีย์ไว้ในภาพหน้าจอและบันทึก
Handshake ล้มเหลว, 404 / 503 หรือไม่พบรุ่น
ตรวจสอบชื่อโฮสต์ WSS, พอร์ต, พาธ /v1/realtime และ ID โมเดลสาธารณะที่แน่นอน ใช้แค็ตตาล็อกโมเดลเรียลไทม์สำหรับสภาพแวดล้อมเป้าหมาย อย่าติดตามการเปลี่ยนเส้นทางไปยัง HTTP URL ที่ไม่ปลอดภัย 503 อาจกำหนดให้ผู้ให้บริการตรวจสอบความพร้อม
ไม่มีข้อผิดพลาดในการถอดเสียงหรือรูปแบบเสียง
ใช้โมโน, 24 kHz, PCM little-endian 16 บิตที่ลงนามพร้อมคำพูดอย่างน้อย 100 ms Python อ่าน PCM WAV; Node.js อ่าน PCM โดยไม่มีส่วนหัว แปลงการบันทึกโดยใช้คำสั่งด้านบนแทนที่จะเปลี่ยนชื่อนามสกุล
การหมดเวลาหรือการเชื่อมต่อปิดก่อนที่จะเสร็จสิ้น
ตัวอย่างหยุดหลังจาก 90 วินาที ลองป้อนข้อมูลให้สั้นลงและตรวจสอบการเข้าถึงเครือข่าย อย่าถือว่าการถอดเสียงบางส่วนหรือเสียงบางส่วนประสบความสำเร็จ ตรวจสอบว่าคำขอก่อนหน้าทำงานก่อนลองอีกครั้งหรือไม่ เพื่อหลีกเลี่ยงการโทรซ้ำ
ไม่พบ input.wav หรือ input.pcm
เก็บการบันทึกไว้ข้างตัวอย่างและรันคำสั่งจากโฟลเดอร์นั้น Python ใช้ input.wav; Node.js ใช้ input.pcm ข้อความสุดท้ายจะปรากฏต่อจาก “Final:”; การจดจำไม่ได้สร้างไฟล์เสียง
พื้นหลังโปรโตคอล: OpenAI WebSockets ↗