Dokumentacja interfejsu API zdarzeń GPT-Live

Ten artykuł zawiera pełną dokumentację zdarzeń dla GPT-Live. Aby uzyskać wskazówki oparte na zadaniach, zobacz Use GPT-Live for real-time voice and Delegate work in GPT-Live ( Używanie GPT-Live do pracy głosowej w czasie rzeczywistym i delegowania pracy w usłudze GPT-Live).

Podstawowa przestrzeń nazw

GPT-Live sesje na żywo w obszarze /openai/v1/live w punkcie końcowym zasobu foundry. Klient protokołu WebSocket nawiązuje połączenie z /openai/v1/live/sessions usługą i wysyła element session.start. Sesje webRTC są tworzone za pomocą polecenia POST /openai/v1/live/sessions. Serwer dołącza połączenie paska bocznego pod adresem /openai/v1/live/sessions/{session_id}/attach.

Konfiguracja sesji

Sesja rozpoczyna się od ścisłego obiektu konfiguracji, który odrzuca nieznane pola. Klient protokołu WebSocket wysyła go do programu session.start; Tworzenie sesji webRTC wysyła je jako session pole żądania utworzenia. Oba te elementy są dostarczane model w obiekcie sesji.

{
  "model": "gpt-live-1",
  "instructions": "Answer briefly and ask before taking an external action.",
  "audio": {
    "output": { "voice": "marin" }
  },
  "delegation": {
    "type": "responses",
    "responses": {
      "model": "gpt-5.5",
      "instructions": "Use tools when current information is required.",
      "max_output_tokens": 2048,
      "service_tier": "priority",
      "reasoning": { "effort": "medium", "summary": "auto" },
      "text": { "verbosity": "low" },
      "tools": [
        { "type": "web_search" },
        {
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location.",
          "parameters": {
            "type": "object",
            "properties": { "location": { "type": "string" } },
            "required": ["location"],
            "additionalProperties": false
          }
        }
      ],
      "tool_choice": "auto",
      "parallel_tool_calls": true
    }
  }
}

Pole	Notatki
model	Required. Ustaw w obiekcie sesji zarówno dla tworzenia obiektów WebSocket session.start , jak i WebRTC. Niezmienne po uruchomieniu.
instructions	Instrukcje systemowe. Niezmienne po uruchomieniu; dodaj więcej za pomocą polecenia session.instructions.append.
audio.output.voice	Głos wyjściowy. Wartości domyślne i marin są niezmienne po uruchomieniu.
delegation	{ type: "client" } lub { type: "responses", responses: {...} }. Pominięto lub null wybrano delegowanie klienta.
delegation.responses.service_tier	autoAkceptuje wartości , default, , flexlub priority.
delegation.responses.tools	Narzędzia funkcji i hostowane, w tym web_search, skonfigurowane jako zwykłe wpisy narzędzi.

Aktualizowanie sesji na żywo

Po uruchomieniu session.update program jest rozrzedzony: pominięte pola zachowują bieżące wartości, a tylko delegation.responses ustawienia mogą ulec zmianie. Delegowanie jest zastępowane jako jeden kompletny obiekt — zagnieżdżone pola delegowania nie są poprawiane niezależnie. Pola modeluruchamiania , instructions, inputi audio nie są aktualizowane pola.

Pomyślna aktualizacja powoduje utworzenie session.updated kompletnego zasobu sesji publicznej. Pomyślne potwierdzenia nie są powtarzane event_id; tylko błędy są używane client_event_id do korelacji.

Format dźwięku

Dane wejściowe i wyjściowe protokołu WebSocket używają nieprzetworzonych, bez nagłówków, mono, podpisanych 16-bitowych komputerów PCM próbkowanych przy 24 000 Hz. Base64 koduje nieprzetworzone bajty PCM , a nie plik WAV ani inny kontener audio. Każda próbka jest dwiema bajtami, więc zdekodowany ładunek musi zawierać parzystą liczbę bajtów.

W usłudze WebRTC dźwięk używa wynegocjowanego śledzenia multimediów zamiast zdarzeń audio JSON i nie zawiera pól chronometrażu JSON.

Zdarzenia klienta

Zdarzenie	Transport	Description
session.start	WebSocket	Wysyła konfigurację sesji początkowej i tworzy polecenie session.started.
session.update	Dowolny strumień JSON	Stosuje rozrzedliwą aktualizację do delegation.responses programu i tworzy session.updatedpolecenie .
session.input_audio.append	Tylko protokół WebSocket	Dołącza niepusty dźwięk mono pcm16 PCM16. Nie potwierdzono.
session.input_audio.mute / session.input_audio.unmute	Dowolny strumień JSON	Wycisz lub nie wycisza danych wejściowych wywołujących i generuje session.input_audio.muted / session.input_audio.unmutedpolecenie .
session.instructions.append	Dowolny strumień JSON	Dołącza zaufane instrukcje i tworzy polecenie session.instructions.appended.
session.thinking.append	Dowolny strumień JSON	Dołącza cichy kontekst i generuje element session.thinking.appended.
session.commentary.append	Dowolny strumień JSON	Dołącza zawartość modelu do wypowiadania i tworzenia session.commentary.appended.
response.item.create	Dowolny strumień JSON	W przypadku delegowania odpowiedzi przesyła wynik funkcji lub komunikat użytkownika dla zaplecza.
response.create	Dowolny strumień JSON	W przypadku delegowania odpowiedzi uruchamia lub kontynuuje odpowiedź zaplecza.
session.close	Dowolny strumień JSON	Rozpoczyna bezproblemowe zamykanie, tworzy session.closedpolecenie , a następnie zamyka transport.

Zdarzenia , i każda session.instructions.appendz nich przyjmują zwykły ciąg content do 500 tokenów i wymagane delegation_id.session.commentary.appendsession.thinking.append Służy null do ogólnego kontekstu sesji lub identyfikatora delegowania klienta, aby zaktualizować to zadanie.

Zdarzenia serwera

Zdarzenie	Description
session.started	Konfiguracja uruchamiania.
session.updated	Zastosowano późniejszą aktualizację rozrzedzono; zawiera pełny zasób sesji publicznej.
session.output_audio.delta	Zakodowany w formacie base64 nieprzetworzonym nieprzetworzonym mono 24 kHz podpisany dźwięk wyjściowy PCM16 (tylko protokół WebSocket).
session.input_transcript.delta / session.output_transcript.delta	Fragment transkrypcji danych wejściowych lub wyjściowych.
session.instructions.appended / session.thinking.appended / session.commentary.appended	Dołączanie kontekstu zostało zaakceptowane do wstrzykiwania.
session.input_audio.muted / session.input_audio.unmuted	Zastosowano polecenie wyciszenia lub wyciszenia.
session.delegation.created	GPT-Live utworzono jednostkę docelową klienta lub odpowiedzi dla delegowanej pracy.
response.event	Koperta z zagnieżdżonym zdarzeniem delegowania odpowiedzi; wyślij na zagnieżdżone event.type i zachowaj zewnętrzne delegation_id.
session.usage.updated	Skumulowane użycie sesji, emitowane mniej więcej raz na minutę.
session.closed	Ukończono bezproblemowe zamknięcie, w tym końcowe skumulowane użycie i reason.
error	Błąd uruchamiania, walidacji, polecenia lub delegowanych odpowiedzi; error.client_event_id koreluje z poleceniem, które zakończyło się niepowodzeniem.

session.started

{
  "type": "session.started",
  "session": {
    "id": "sess_123",
    "expires_at": 1782518400,
    "model": "gpt-live-1",
    "instructions": "Be concise.",
    "audio": { "output": { "voice": "marin" } },
    "delegation": { "type": "client" }
  }
}

session.output_audio.delta

start_ms i end_ms użyj osi czasu serwera, więc różnica między zakresami reprezentuje pominiętą ciszę. Nie ma zdarzenia wyjściowego gotowego do dźwięku.

{
  "type": "session.output_audio.delta",
  "delta": "<base64-encoded-24khz-pcm16le-mono-audio>",
  "start_ms": 0,
  "end_ms": 100
}

session.input_transcript.delta/session.output_transcript.delta

Każde zdarzenie przenosi delta fragment z zakresem start_ms / end_ms na osi czasu sesji. Granice fragmentów odzwierciedlają cykl dźwięku, a nie semantyczne granice kolei, a fragmenty użytkowników i asystentów mogą się przeplatać.

{
  "type": "session.input_transcript.delta",
  "delta": "What is the",
  "start_ms": 600,
  "end_ms": 800
}

session.delegation.created

Obiekt delegation niesie ze sobą id, typei target. W przypadku delegowania klienta użyj wartości delegation.id w przypadku nowszych delegation_idsession.commentary.append lub session.thinking.append zdarzeń. W przypadku delegowania response_id Odpowiedzi powiąż delegowanie z cyklem życia Odpowiedzi, który następuje w response.event kopertach. Aby uzyskać pełny przepływ, zobacz Delegowanie pracy w usłudze GPT-Live .

{
  "type": "session.delegation.created",
  "offset_ms": 1000,
  "delegation": {
    "id": "item_delegation_123",
    "type": "delegation",
    "target": "client"
  }
}

session.usage.updated / session.closed

session.usage.updated raportuje skumulowany czas trwania głosu w sekundach wraz ze współczynnikiem użycia okna kontekstowego. Są to uruchomione migawki, a nie przyrosty do sumy. session.closedprogram przenosi końcowe użycie i .reason

{
  "type": "session.usage.updated",
  "usage": { "seconds": 12 },
  "context_window": { "usage_ratio": 0.42 }
}

{
  "type": "session.closed",
  "reason": "close_requested",
  "usage": { "seconds": 128 }
}

W reason polu wyjaśniono, dlaczego sesja została zakończona: close_requested, , expiredcontent, remote_hanguplub connection_lost. Użycie tokenu zaplecza jest oddzielne; odczytuje go z zagnieżdżonych zdarzeń dostarczonych response.completed w programie response.event.

Obsługa błędów

Wszystkie błędy GPT-Live używają jednej koperty błędów. error.client_event_id występuje tylko wtedy, gdy błąd może być skorelowany z poleceniem klienta; param zostanie pominięty, gdy żadne określone pole nie spowodowało błędu. Błąd uruchamiania uniemożliwia session.started. Błąd polecenia nie musi zamknąć już uruchomionej sesji.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_audio",
    "message": "PCM16 audio must contain an even number of bytes",
    "param": "audio",
    "client_event_id": "event_audio_1"
  }
}

Pełny cykl życia protokołu WebSocket

// 1. Client startup
{ "type": "session.start",
  "session": {
    "model": "gpt-live-1",
    "instructions": "Be concise.",
    "delegation": { "type": "client" }
  }
}

// 2. Server startup acknowledgment
{ "type": "session.started",
  "session": {
    "id": "sess_123",
    "model": "gpt-live-1",
    "instructions": "Be concise.",
    "audio": { "output": { "voice": "marin" } },
    "delegation": { "type": "client" }
  }
}

// 3. Client audio, repeated as data becomes available
{ "type": "session.input_audio.append",
  "audio": "<base64-encoded-24khz-pcm16le-mono-audio>"
}

// 4. Server events may interleave
{ "type": "session.input_transcript.delta",
  "delta": "Hello",
  "start_ms": 600,
  "end_ms": 800
}
{ "type": "session.output_audio.delta",
  "delta": "<base64-encoded-24khz-pcm16le-mono-audio>",
  "start_ms": 0,
  "end_ms": 100
}

// 5. Client shutdown; keep reading until session.closed
{ "type": "session.close" }

Treści powiązane

• Co to jest GPT-Live?
• Używanie GPT-Live na potrzeby głosu w czasie rzeczywistym
• Delegowanie pracy w GPT-Live
• Dokumentacja interfejsu API w czasie rzeczywistym