เปลี่ยนข้อความเป็นคำพูด
ส่งข้อความผ่านการเชื่อมต่อ WebSocket และรับเสียงเป็นชิ้นๆ เริ่มต้นด้วยตัวอย่างที่สมบูรณ์ซึ่งบันทึกไฟล์ WAV ที่สามารถเล่นได้
wss://api.starsg.ai/v1/realtime?model=tts-altair-v1-miniยังใหม่กับ API คำพูดใช่ไหม เริ่มต้นด้วยคำศัพท์สี่ข้อนี้
- WebSocket
- การเชื่อมต่อที่เปิดอยู่เพื่อให้โปรแกรมของคุณและเซิร์ฟเวอร์สามารถแลกเปลี่ยนข้อความได้ทั้งสองทิศทาง
- แบบอย่าง
- เครื่องยนต์ที่ทำงาน ใช้โมเดล tts ในการพูด และใช้โมเดล asr เพื่อถอดเสียง คัดลอก ID สาธารณะที่ถูกต้อง
- เสียง
- เสียงที่ใช้ในการสังเคราะห์ เลือก voice_id จากแค็ตตาล็อกของรุ่นที่เลือก การรับรู้ไม่จำเป็นต้องมีเสียง
- กุญแจ 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 แบบถาวรลงในเว็บเพจหรือที่เก็บข้อมูลสาธารณะ การรันตัวอย่างจะทำให้การเรียกโมเดลที่เรียกเก็บเงินได้
บันทึกตัวอย่างและรัน
คัดลอกตัวอย่างที่สมบูรณ์ด้านล่างลงในไฟล์ข้อความธรรมดาใหม่ที่ชื่อว่า speech.py ในโฟลเดอร์นี้ บันทึก จากนั้นรันคำสั่งนี้ในเทอร์มินัลเดียวกัน
.venv/bin/python speech.py
ความสำเร็จมีลักษณะอย่างไร.เทอร์มินัลจะพิมพ์ “Saved:” และสร้าง output.wav เปิดด้วยเครื่องเล่นเสียงของคุณ หากต้องการรันอีกครั้ง ให้เปลี่ยนชื่อหรือลบไฟล์นั้นก่อน ตัวอย่างจะไม่เขียนทับมัน
ตัวอย่างที่สมบูรณ์
คัดลอกไฟล์ทั้งหมด โดยจะเชื่อมต่อ กำหนดค่าเซสชัน ส่งข้อมูลหนึ่งรายการ รอจนเสร็จสิ้น และปิดการเชื่อมต่อ มันไม่ลองใหม่โดยอัตโนมัติ
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 = "สวัสดี! นี่เป็นตัวอย่างการสังเคราะห์คำพูดครั้งแรกของฉัน"
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())
ตัวอย่างนี้ใช้ ID โมเดลสาธารณะ ความพร้อมใช้งานขึ้นอยู่กับบัญชีและสภาพแวดล้อมของคุณ เลือกรุ่นที่รองรับงานเรียลไทม์นี้ ดูโมเดล ↗
หากต้องการเลือกเสียง ให้ค้นหา voice_id ในแค็ตตาล็อกเสียงของรุ่นนั้น และตั้งค่า SPEECH_VOICE ในเทอร์มินัลของคุณก่อนเรียกใช้ ละเว้นเพื่อใช้เสียงเริ่มต้น ชื่อที่แสดง เช่น “โลหะผสม” ไม่ใช่ voice_id แทนที่ VOICE_ID ด้านล่างด้วยค่าจากแค็ตตาล็อกนั้น
export SPEECH_VOICE="VOICE_ID"
โฟลว์เหตุการณ์
แต่ละข้อความคือเหตุการณ์ JSON ส่ง หมายถึง โปรแกรมของคุณ → เซิร์ฟเวอร์; รับหมายถึงเซิร์ฟเวอร์ → โปรแกรมของคุณ รอ session.updated ก่อนที่จะส่งข้อมูล
- รับ
session.createdเซิร์ฟเวอร์ได้เปิดเซสชันแล้ว ตอนนี้คุณสามารถส่งการกำหนดค่าได้แล้ว
- ส่ง
session.updateตั้งค่างาน รูปแบบเสียง และเสียงเสริม
- รับ
session.updatedเซิร์ฟเวอร์ยอมรับการกำหนดค่า ตอนนี้ส่งข้อมูลเข้า
- ส่ง
conversation.item.createสร้างข้อความผู้ใช้ด้วย content.type=input_text และ content.text ที่มีข้อความของคุณ
- ส่ง
response.createขอให้เซิร์ฟเวอร์สร้างเสียงสำหรับข้อความ
- รับ
response.output_audio.deltaถอดรหัสฟิลด์เดลต้า Base64 และรวบรวมไบต์ PCM ตามลำดับ ส่วนเหล่านี้ไม่ใช่ไฟล์ WAV แยกกัน
- รับ
response.doneตรวจสอบการตอบกลับสถานะเสร็จสมบูรณ์ จากนั้นเพิ่มส่วนหัว WAV และบันทึกเสียงที่รวบรวมไว้ สถานะอื่นๆ คือความล้มเหลว
ตรวจสอบข้อความ session.update
{
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": [
"audio"
],
"audio": {
"output": {
"format": {
"type": "audio/pcm",
"rate": 24000
}
}
}
}
}การอ้างอิงพารามิเตอร์
ชื่อที่มีจุดแสดงตำแหน่งของฟิลด์ในวัตถุ JSON “จำเป็น” ด้านล่างใช้กับขั้นตอนการทำงานในคู่มือนี้ การสนับสนุนและขีดจำกัดขั้นสูงขึ้นอยู่กับรุ่น
การเชื่อมต่อและการรับรองความถูกต้อง
modelstringที่จำเป็นพารามิเตอร์การสืบค้นที่จำเป็นใน WebSocket URL ใช้รหัสโมเดลสาธารณะที่แน่นอนจากแค็ตตาล็อกเรียลไทม์ รุ่น ASR และ TTS ไม่สามารถใช้แทนกันได้
ตัวอย่าง/การตั้งค่าtts-altair-v1-miniAuthorizationstringที่จำเป็นส่วนหัวการเชื่อมต่อ: Bearer ช่องว่างหนึ่งช่อง ตามด้วยคีย์ API ของคุณ ใช้คีย์สำหรับสภาพแวดล้อมเป้าหมาย อย่าใส่ไว้ใน URL
ตัวอย่าง/การตั้งค่าBearer <API_KEY>
เซสชันและการป้อนข้อมูล
session.typestringที่จำเป็นใช้เรียลไทม์สำหรับเซสชันการอ่านออกเสียงข้อความ นี่คือเวิร์กโฟลว์การสังเคราะห์ ไม่ใช่การสนทนาด้วยเสียงทั่วไป
ตัวอย่าง/การตั้งค่า"realtime"session.output_modalitiesstring[]ที่จำเป็นขอเอาต์พุตเสียงสำหรับการสังเคราะห์ ส่งอาร์เรย์นี้ใน session.update
ตัวอย่าง/การตั้งค่า["audio"]session.audio.output.formatobjectที่จำเป็นการกำหนดค่าเสียง: ประเภทคือเสียง/pcm อัตราคือ 24000 ตัวอย่างนี้ใช้ตัวอย่าง little-endian โมโนที่ลงนาม 16: ไบต์ 48,000 ต่อวินาที ส่วนหัว WAV จะไม่ถูกส่งผ่านซ็อกเก็ต
ตัวอย่าง/การตั้งค่า{"type":"audio/pcm","rate":24000}session.audio.output.voicestringไม่จำเป็นอุปกรณ์เสริม voice_id จากแค็ตตาล็อกเสียงของรุ่นที่เลือก มันถูกกำหนดขอบเขตไว้ที่โมเดล ละไว้สำหรับค่าเริ่มต้นของเซิร์ฟเวอร์ อย่าใช้ชื่อที่แสดงของผู้ขาย ตั้งค่าก่อนที่เอาต์พุตเสียงจะเริ่มต้น
เรียกดูเสียงค่าเริ่มต้น/ละไว้ เสียงเริ่มต้นของโมเดลitem.content[].textstringที่จำเป็นข้อความที่จะสังเคราะห์ ภายใน Conversation.item.create → item → content ตั้งค่าประเภทของรายการเนื้อหาเป็น input_text, item.type เป็นข้อความ และ item.role เป็นผู้ใช้ ขีดจำกัดข้อความขึ้นอยู่กับรุ่น
การควบคุมด้วยเสียงเสริม
เริ่มต้นโดยไม่มีการควบคุมเหล่านี้ ตรวจสอบ output_controls ของรุ่นก่อนเพิ่ม ค่าระดับเสียงหรือระดับเสียงที่ไม่รองรับทำให้เกิดข้อผิดพลาด พวกเขาไม่ได้ถูกละเลยอย่างเงียบ ๆ ล็อคเสียงและความเร็วหลังจากเอาต์พุตเสียงแรก ระดับเสียงและระดับเสียงอาจมีการอัปเดตในภายหลัง
session.audio.output.speednumberไม่จำเป็นตัวคูณอัตราการพูด: 1.0 คือความเร็วปกติ ค่าต่ำสุด/สูงสุดที่ยอมรับได้ขึ้นอยู่กับรุ่น ตรวจสอบแคตตาล็อก ตั้งค่าก่อนเสียงออกครั้งแรก
ตัวอย่าง/การตั้งค่า1.0session.audio.output.options.volumenumber | nullไม่จำเป็นส่วนขยายแพลตฟอร์มในตัวเลือก: รับตัวคูณ ค่าเป็นกลาง 1.0 ช่วงโปรโตคอลคือ 0 < ปริมาณ ≤ 10 แต่รุ่นจะต้องรองรับ ละเว้นหรือเป็นโมฆะใช้ค่าที่เป็นกลาง ค่าที่ไม่รองรับจะถูกปฏิเสธ
ค่าเริ่มต้น/ละไว้1.0session.audio.output.options.pitchnumber | nullไม่จำเป็นส่วนขยายแพลตฟอร์มในตัวเลือก: การเปลี่ยนระดับเสียงในเซมิโทน, ค่ากลาง 0 ช่วงโปรโตคอลภายนอกคือ −24 ถึง 24 โมเดลอาจอนุญาตน้อยกว่า ใช้ขีดจำกัดที่โฆษณาไว้ ละเว้นหรือเป็นโมฆะใช้ระดับเสียงที่เป็นกลาง
ค่าเริ่มต้น/ละไว้0
การแก้ไขปัญหา
อ่านข้อความแสดงข้อผิดพลาดที่ส่งคืนก่อน การเปิดการเชื่อมต่อหรือเสียงที่ดังขึ้นไม่ได้หมายความว่าคำขอเสร็จสมบูรณ์
ไม่พบคำสั่งหรือโมดูลหายไป
ติดตั้งรันไทม์ที่เลือก เปิดเทอร์มินัลของคุณอีกครั้ง และรันคำสั่งการตั้งค่าในโฟลเดอร์โปรเจ็กต์ สำหรับ 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, โมโน, 16-bit little-endian PCM และอย่างน้อย 100 ms ของคำพูด ใช้คำสั่งการแปลงแทนการเปลี่ยนชื่อไฟล์ การรับรู้จะส่ง PCM แบบดิบ ไม่ใช่ส่วนหัว WAV สำหรับการสังเคราะห์ ให้ถอดรหัส Base64 และรวมชิ้นส่วน PCM ก่อนสร้างไฟล์ WAV
invalid_value หรือตัวควบคุมที่ไม่สนับสนุน
ลบการตั้งค่าความเร็ว ระดับเสียง และระดับเสียงที่เป็นตัวเลือก จากนั้นตรวจสอบ output_controls สำหรับรุ่นที่เลือก อย่าใช้ voice_id ของรุ่นอื่นหรือขีดจำกัดตัวเลขของรุ่นอื่นซ้ำ session.update ที่ถูกปฏิเสธไม่ได้ใช้การกำหนดค่านั้น
การหมดเวลาหรือการเชื่อมต่อปิดก่อนที่จะเสร็จสิ้น
ตัวอย่างหยุดหลังจาก 90 วินาที ลองป้อนข้อมูลให้สั้นลงและตรวจสอบการเข้าถึงเครือข่าย อย่าถือว่าการถอดเสียงบางส่วนหรือเสียงบางส่วนประสบความสำเร็จ ตรวจสอบว่าคำขอก่อนหน้าทำงานก่อนลองอีกครั้งหรือไม่ เพื่อหลีกเลี่ยงการโทรซ้ำ
output.wav มีอยู่แล้วหรือไฟล์อินพุตหายไป
เรียกใช้สคริปต์จากโฟลเดอร์ที่มีคำพูด.py หรือคำพูด.mjs ใส่ input.wav (Python) หรือ input.pcm (Node.js) ตรงนั้น เปลี่ยนชื่อ output.wav ก่อนหน้าก่อนที่จะสร้างอีกครั้ง บรรทัด “สุดท้าย:” คือผลการจดจำ มันไม่ได้สร้างไฟล์เสียง
พื้นหลังโปรโตคอล: OpenAI WebSockets ↗