เอกสารประกอบ API

WebSocketเหตุการณ์ที่เข้ากันได้กับ OpenAI

เปลี่ยนคำพูดเป็นข้อความ

ส่งเสียงผ่านการเชื่อมต่อ WebSocket และรับการอัปเดตการถอดเสียง ตัวอย่างแรกนี้จะอ่านการบันทึกเพื่อให้คุณสามารถเรียนรู้โฟลว์ได้โดยไม่ต้องตั้งค่าไมโครโฟน

รหัสรุ่น
เสียงเข้าส่งข้อความออกมา
WSSwss://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 เมื่อการเชื่อมต่อเปิดขึ้น

การเชื่อมต่อครั้งแรกของคุณ

เลือกวิธีการผสานรวมและสภาพแวดล้อมของคุณ จากนั้นทำตามขั้นตอนด้านล่าง

  1. เตรียมโฟลเดอร์และติดตั้งไลบรารี่

    ใช้ Python 3.10 หรือใหม่กว่า เปิดเทอร์มินัลในโฟลเดอร์ว่างและติดตั้ง OpenAI SDK อย่างเป็นทางการ เชื่อมต่อกับเกตเวย์คำพูดผ่าน WebSocket; ตัวอย่างได้รับการทดสอบกับเวอร์ชันด้านล่าง ดาวน์โหลด ↗

    bash
    python3 -m venv .venv
    .venv/bin/python -m pip install "openai[realtime]==3.35.1"
  2. ตั้งค่าคีย์ API ของคุณ

    สร้างคีย์ในคอนโซล จากนั้นแทนที่ YOUR_API_KEY ด้านล่างด้วยคีย์ของคุณเอง รันสิ่งนี้ในเทอร์มินัลเดียวกันกับตัวอย่าง จัดการคีย์ API ↗

    bash
    export STARSG_API_KEY="YOUR_API_KEY"

    เก็บกุญแจของคุณไว้เป็นส่วนตัว นี่เป็นตัวอย่างในเครื่อง/เซิร์ฟเวอร์ ไม่ใช่โค้ดของเบราว์เซอร์ อย่าใส่คีย์ API แบบถาวรลงในเว็บเพจหรือที่เก็บข้อมูลสาธารณะ การรันตัวอย่างจะทำให้การเรียกโมเดลที่เรียกเก็บเงินได้

  3. เตรียมบันทึกสั้นๆ

    วาง input.wav ไว้ในโฟลเดอร์เดียวกัน: mono, 24,000 Hz, 16-bit PCM WAV, คำพูดอย่างน้อย 100 ms คุณยังสามารถใช้ output.wav จากตัวอย่างการสังเคราะห์และเปลี่ยนชื่อเป็น input.wav

    หากการบันทึกของคุณใช้รูปแบบอื่น ให้ติดตั้ง FFmpeg แทนที่ recording.mp3 ด้วยชื่อไฟล์ของคุณ จากนั้นแปลงเป็น: FFmpeg ↗

    bash
    ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
  4. บันทึกตัวอย่างและรัน

    คัดลอกตัวอย่างที่สมบูรณ์ด้านล่างลงในไฟล์ข้อความธรรมดาใหม่ที่ชื่อว่า speech.py ในโฟลเดอร์นี้ บันทึก จากนั้นรันคำสั่งนี้ในเทอร์มินัลเดียวกัน

    bash
    .venv/bin/python speech.py
    ความสำเร็จมีลักษณะอย่างไร.

    เทอร์มินัลอาจพิมพ์การอัปเดต "บางส่วน:" จากนั้น "สุดท้าย:" ตามด้วยการถอดเสียงที่เสร็จสมบูรณ์ บางรุ่นอาจให้ผลลัพธ์สุดท้ายเท่านั้น

ตัวอย่างที่สมบูรณ์

คัดลอกไฟล์ทั้งหมด โดยจะเชื่อมต่อ กำหนดค่าเซสชัน ส่งข้อมูลหนึ่งรายการ รอจนเสร็จสิ้น และปิดการเชื่อมต่อ มันไม่ลองใหม่โดยอัตโนมัติ

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())

ตัวอย่างนี้ใช้ ID โมเดลสาธารณะ ความพร้อมใช้งานขึ้นอยู่กับบัญชีและสภาพแวดล้อมของคุณ เลือกรุ่นที่รองรับงานเรียลไทม์นี้ ดูโมเดล ↗

โฟลว์เหตุการณ์

แต่ละข้อความคือเหตุการณ์ JSON ส่ง หมายถึง โปรแกรมของคุณ → เซิร์ฟเวอร์; รับหมายถึงเซิร์ฟเวอร์ → โปรแกรมของคุณ รอ session.updated ก่อนที่จะส่งข้อมูล

  1. รับ
    session.created

    เซิร์ฟเวอร์ได้เปิดเซสชันแล้ว ตอนนี้คุณสามารถส่งการกำหนดค่าได้แล้ว

  2. ส่ง
    session.update

    ตั้งค่าเซสชันการถอดเสียง รูปแบบเสียงอินพุต โมเดลการจดจำ และการตรวจจับการหมุน

  3. รับ
    session.updated

    เซิร์ฟเวอร์ยอมรับการกำหนดค่า ตอนนี้ส่งข้อมูลเข้า

  4. ส่ง
    input_audio_buffer.append

    ส่ง Base64 PCM ในช่องเสียง ตัวอย่างนี้ใช้ชิ้นไบต์ 4,800 ซึ่งเทียบเท่ากับ 100 ms ในรูปแบบที่กำหนดค่าไว้

  5. ส่ง
    input_audio_buffer.commit

    สิ้นสุดการเลี้ยวอินพุต ด้วย turn_detection=null คุณต้องคอมมิตอย่างชัดเจน อย่าส่งการตอบกลับสร้างการรับรู้

  6. รับ
    conversation.item.input_audio_transcription.delta

    อ่านเดลต้าและ text_mode; อัพเดต item_id และ content_index ที่ตรงกัน

  7. รับ
    conversation.item.input_audio_transcription.completed

    ช่องการถอดเสียงเป็นข้อความสุดท้ายที่เชื่อถือได้ บันทึก จากนั้นปิดตัวอย่างเทิร์นเดียวนี้

ตรวจสอบข้อความ 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
      }
    }
  }
}

การอ้างอิงพารามิเตอร์

ชื่อที่มีจุดแสดงตำแหน่งของฟิลด์ในวัตถุ JSON “จำเป็น” ด้านล่างใช้กับขั้นตอนการทำงานในคู่มือนี้ การสนับสนุนและขีดจำกัดขั้นสูงขึ้นอยู่กับรุ่น

การเชื่อมต่อและการรับรองความถูกต้อง

modelstringที่จำเป็น

พารามิเตอร์การสืบค้นที่จำเป็นใน WebSocket URL ใช้รหัสโมเดลสาธารณะที่แน่นอนจากแค็ตตาล็อกเรียลไทม์ รุ่น ASR และ TTS ไม่สามารถใช้แทนกันได้

ตัวอย่าง/การตั้งค่า asr-altair-v1-mini
Authorizationstringที่จำเป็น

ส่วนหัวการเชื่อมต่อ: 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-mini
session.audio.input.turn_detectionobject | nullไม่จำเป็น

ตัวอย่างนี้ตั้งค่า null ไว้อย่างชัดเจนเพื่อปิดใช้งานการตรวจจับการเลี้ยวอัตโนมัติ (VAD) ส่ง input_audio_buffer.commit เมื่อส่งสัญญาณเสียงอินพุตทั้งหมดแล้ว นี่เป็นการตั้งค่าที่เลือก ไม่ใช่การอ้างสิทธิ์เกี่ยวกับค่าเริ่มต้นของเซิร์ฟเวอร์

ตัวอย่าง/การตั้งค่า null
audiostringที่จำเป็น

ไบต์ 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 ↗