Dokumentacja interfejsu API głosu na żywo

Interfejs API głosu na żywo zapewnia komunikację dwukierunkową w czasie rzeczywistym dla aplikacji obsługujących głos przy użyciu połączeń Protokołu WebSocket. Ten interfejs API obsługuje zaawansowane funkcje, w tym rozpoznawanie mowy, syntezę tekstu na mowę, przesyłanie strumieniowe awatarów, dane animacji i kompleksowe możliwości przetwarzania dźwięku.

Interfejs API używa zdarzeń sformatowanych w formacie JSON wysyłanych za pośrednictwem połączeń Protokołu WebSocket do zarządzania konwersacjami, strumieniami audio, interakcjami awatara i odpowiedziami w czasie rzeczywistym. Zdarzenia są podzielone na kategorie zdarzeń klienta (wysyłanych z klienta do serwera) i zdarzeń serwera (wysyłanych z serwera do klienta).

Najważniejsze funkcje    

• Przetwarzanie audio w czasie rzeczywistym: obsługa wielu formatów audio, w tym PCM16 z różnymi szybkościami próbkowania i koderami G.711
• Zaawansowane opcje głosowe: głosy OpenAI, niestandardowe głosy platformy Azure, standardowe głosy platformy Azure i osobiste głosy platformy Azure
• Integracja awatara: przesyłanie strumieniowe awatara opartego na protokole WebRTC za pomocą wideo, animacji i blendshapes
• Wykrywanie inteligentnego turnu: wiele opcji vaD, w tym semantyczne wykrywanie vaD platformy Azure i wykrywanie po stronie serwera
• Ulepszenia dźwięku: wbudowana redukcja szumu i anulowanie echa
• Wywoływanie funkcji: integracja narzędzi w celu uzyskania rozszerzonych możliwości konwersacyjnych
• Elastyczne zarządzanie sesjami: konfigurowalne modalności, instrukcje i parametry odpowiedzi

Zdarzenia klienta

Interfejs API voice live obsługuje następujące zdarzenia klienta, które można wysyłać z klienta do serwera:

session.update

Zaktualizuj konfigurację sesji. To zdarzenie można wysłać w dowolnym momencie, aby zmodyfikować ustawienia, takie jak głos, modalność, wykrywanie kolei, narzędzia i inne parametry sesji. Należy pamiętać, że po zainicjowaniu sesji przy użyciu określonego modelu nie można go zmienić na inny model.

Struktura zdarzeń

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Właściwości

Przykład z usługą Azure Custom Voice

{
  "type": "session.update",
  "session": {
    "voice": {
      "type": "azure-custom",
      "name": "my-custom-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "temperature": 0.7,
      "style": "cheerful"
    },
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "avatar": {
      "character": "lisa",
      "customized": false,
      "video": {
        "resolution": {
          "width": 1920,
          "height": 1080
        },
        "bitrate": 2000000
      }
    }
  }
}

session.avatar.connect

Ustanów połączenie awatara, podając ofertę protokołu SDP (Session Description Protocol) klienta na potrzeby negocjacji multimediów WebRTC. To zdarzenie jest wymagane w przypadku korzystania z funkcji awatara.

Struktura zdarzeń

{
  "type": "session.avatar.connect",
  "client_sdp": "<client_sdp>"
}

Właściwości

input_audio_buffer.append

Dołącz bajty audio do wejściowego buforu audio.

Struktura zdarzeń

{
  "type": "input_audio_buffer.append",
  "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

Właściwości

input_audio_buffer.commit

Zatwierdź wejściowy bufor audio na potrzeby przetwarzania.

Struktura zdarzeń

{
  "type": "input_audio_buffer.commit"
}

Właściwości

input_audio_buffer.clear

Wyczyść wejściowy bufor audio.

Struktura zdarzeń

{
  "type": "input_audio_buffer.clear"
}

Właściwości

conversation.item.create

Dodaj nowy element do kontekstu konwersacji. Może to obejmować komunikaty, wywołania funkcji i odpowiedzi wywołania funkcji. Elementy można wstawić na określonych pozycjach w historii konwersacji.

Struktura zdarzeń

{
  "type": "conversation.item.create",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Właściwości

Przykład z zawartością audio

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello there"
      }
    ]
  }
}

Przykład z wywołaniem funkcji

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call",
    "name": "get_weather",
    "call_id": "call_123",
    "arguments": "{\"location\": \"San Francisco\", \"unit\": \"celsius\"}"
  }
}

Przykład z wywołaniem MCP

{
  "type": "conversation.item.create",
  "item": {
    "type": "mcp_call",
    "approval_request_id": null,
    "arguments": "",
    "server_label": "deepwiki",
    "name": "ask_question",
    "output": null,
    "error": null
  }
}

conversation.item.retrieve

Pobierz określony element z historii konwersacji. Jest to przydatne do sprawdzania przetworzonego dźwięku po anulowaniu szumu i vaD.

Struktura zdarzeń

{
  "type": "conversation.item.retrieve",
  "item_id": "item_ABC123"
}

Właściwości

conversation.item.truncate

Obcięcie zawartości audio komunikatu asystenta. Jest to przydatne w przypadku zatrzymywania odtwarzania w określonym punkcie i synchronizowania zrozumienia serwera ze stanem klienta.

Struktura zdarzeń

{
  "type": "conversation.item.truncate",
  "item_id": "item_ABC123",
  "content_index": 0,
  "audio_end_ms": 5000
}

Właściwości

conversation.item.delete

Usuń element z historii konwersacji.

Struktura zdarzeń

{
  "type": "conversation.item.delete",
  "item_id": "item_ABC123"
}

Właściwości

response.create

Poinstruuj serwer, aby utworzył odpowiedź za pomocą wnioskowania modelu. To zdarzenie może określać konfigurację specyficzną dla odpowiedzi, która zastępuje wartości domyślne sesji.

Struktura zdarzeń

{
  "type": "response.create",
  "response": {
    "modalities": ["text", "audio"],
    "instructions": "Be extra helpful and detailed.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "output_audio_format": "pcm16",
    "temperature": 0.7,
    "max_response_output_tokens": 1000
  }
}

Właściwości

Przykład z wyborem narzędzi

{
  "type": "response.create",
  "response": {
    "modalities": ["text"],
    "tools": [
      {
        "type": "function",
        "name": "get_current_time",
        "description": "Get the current time",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      }
    ],
    "tool_choice": "get_current_time",
    "temperature": 0.3
  }
}

Przykład z animacją

{
  "type": "response.create",
  "response": {
    "modalities": ["audio", "animation"],
    "animation": {
      "model_name": "default",
      "outputs": ["blendshapes", "viseme_id"]
    },
    "voice": {
      "type": "azure-custom",
      "name": "my-expressive-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "style": "excited"
    }
  }
}

response.cancel

Anuluj odpowiedź w toku. Spowoduje to natychmiastowe zatrzymanie generowania odpowiedzi i powiązanych danych wyjściowych dźwięku.

Struktura zdarzeń

{
  "type": "response.cancel"
}

Właściwości

Właściwości

RealtimeClientEventConversationItemTruncate

Zdarzenie klienta conversation.item.truncate służy do obcinania dźwięku poprzedniego asystenta. Serwer generuje dźwięk szybciej niż w czasie rzeczywistym, więc to zdarzenie jest przydatne, gdy użytkownik przerywa obcięcie dźwięku, który został wysłany do klienta, ale nie został jeszcze odtwarzany. Informacje o dźwięku serwera z odtwarzaniem klienta są synchronizowane.

Obcięcie dźwięku usuwa transkrypcję tekstu po stronie serwera, aby upewnić się, że nie ma tekstu w kontekście, o którego użytkownik nie wie.

Jeśli zdarzenie klienta zakończy się pomyślnie, serwer odpowie zdarzeniem conversation.item.truncated .

Struktura zdarzeń

{
  "type": "conversation.item.truncate",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

Właściwości

RealtimeClientEventInputAudioBufferAppend

Zdarzenie klienta input_audio_buffer.append służy do dołączania bajtów audio do wejściowego buforu audio. Bufor audio jest magazynem tymczasowym, do którego można zapisywać dane, a następnie zatwierdzać.

W trybie vaD serwera (wykrywanie aktywności głosowej) bufor audio jest używany do wykrywania mowy, a serwer decyduje, kiedy zatwierdzić. Gdy funkcja VAD serwera jest wyłączona, klient może wybrać ilość dźwięku do umieszczenia w każdym zdarzeń maksymalnie 15 MiB. Na przykład przesyłanie strumieniowe mniejszych fragmentów z klienta może umożliwić dynamiczne działanie vaD.

W przeciwieństwie do większości innych zdarzeń klienta serwer nie wysyła odpowiedzi potwierdzenia na zdarzenie klienta input_audio_buffer.append .

Struktura zdarzeń

{
  "type": "input_audio_buffer.append",
  "audio": "<audio>"
}

Właściwości

RealtimeClientEventInputAudioBufferClear

Zdarzenie klienta input_audio_buffer.clear służy do czyszczenia bajtów audio w buforze.

Serwer odpowiada za pomocą input_audio_buffer.cleared zdarzenia.

Struktura zdarzeń

{
  "type": "input_audio_buffer.clear"
}

Właściwości

RealtimeClientEventInputAudioBufferCommit

Zdarzenie klienta input_audio_buffer.commit służy do zatwierdzania buforu audio wejściowego użytkownika, który tworzy nowy element wiadomości użytkownika w konwersacji. Dźwięk jest transkrypcji, jeśli input_audio_transcription jest skonfigurowany dla sesji.

W trybie vaD serwera klient nie musi wysyłać tego zdarzenia, serwer zatwierdza bufor audio automatycznie. Bez funkcji VAD serwera klient musi zatwierdzić bufor audio, aby utworzyć element komunikatu użytkownika. To zdarzenie klienta generuje błąd, jeśli wejściowy bufor audio jest pusty.

Zatwierdzenie wejściowego buforu audio nie powoduje utworzenia odpowiedzi na podstawie modelu.

Serwer odpowiada za pomocą input_audio_buffer.committed zdarzenia.

Struktura zdarzeń

{
  "type": "input_audio_buffer.commit"
}

Właściwości

RealtimeClientEventResponseCancel

Zdarzenie klienta response.cancel służy do anulowania odpowiedzi w toku.

Serwer odpowie zdarzeniem response.done o stanie response.status=cancelled.

Struktura zdarzeń

{
  "type": "response.cancel"
}

Właściwości

RealtimeClientEventResponseCreate

Zdarzenie klienta response.create służy do poinstruowania serwera o utworzeniu odpowiedzi za pośrednictwem wnioskowania modelu. Po skonfigurowaniu sesji w trybie vaD serwera serwer automatycznie tworzy odpowiedzi.

Odpowiedź zawiera co najmniej jeden itemelement i może mieć dwa, w tym przypadku drugie jest wywołaniem funkcji. Te elementy są dołączane do historii konwersacji.

Serwer odpowiada za pomocą response.created zdarzenia, co najmniej jednego elementu i zdarzeń zawartości (takich jak conversation.item.created i response.content_part.added), a na koniec response.done zdarzenie wskazujące, że odpowiedź została ukończona.

Struktura zdarzeń

{
  "type": "response.create"
}

Właściwości

RealtimeClientEventSessionUpdate

Zdarzenie klienta session.update służy do aktualizowania domyślnej konfiguracji sesji. Klient może wysłać to zdarzenie w dowolnym momencie, aby zaktualizować konfigurację sesji, a dowolne pole można zaktualizować w dowolnym momencie, z wyjątkiem głosu.

Aktualizowane są tylko bieżące pola. Aby wyczyścić pole (takie jak instructions), przekaż pusty ciąg.

Serwer odpowiada zdarzeniem zawierającym pełną efektywną session.updated konfigurację.

Struktura zdarzeń

{
  "type": "session.update"
}

Właściwości

Zdarzenia serwera

Interfejs API na żywo voice wysyła następujące zdarzenia serwera w celu komunikowania stanu, odpowiedzi i danych do klienta:

session.created

Wysłane po pomyślnym ustanowieniu nowej sesji. Jest to pierwsze zdarzenie odebrane po nawiązaniu połączenia z interfejsem API.

Struktura zdarzeń

{
  "type": "session.created",
  "session": {
    "id": "sess_ABC123DEF456",
    "object": "realtime.session",
    "model": "gpt-realtime",
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful assistant.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Właściwości

session.updated

Wysłane, gdy konfiguracja sesji została pomyślnie zaktualizowana w odpowiedzi na session.update zdarzenie klienta.

Struktura zdarzeń

{
  "type": "session.updated",
  "session": {
    "id": "sess_ABC123DEF456",
    "voice": {
      "type": "azure-custom",
      "name": "my-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012"
    },
    "temperature": 0.7,
    "avatar": {
      "character": "lisa",
      "customized": false
    }
  }
}

Właściwości

session.avatar.connecting

Wskazuje, że trwa nawiązywanie połączenia awatara WebRTC. To zdarzenie jest wysyłane w odpowiedzi na session.avatar.connect zdarzenie klienta.

Struktura zdarzeń

{
  "type": "session.avatar.connecting",
  "server_sdp": "<server_sdp>"
}

Właściwości

conversation.item.created

Wysłane po dodaniu nowego elementu do konwersacji za pośrednictwem zdarzenia klienta conversation.item.create lub automatycznego generowania odpowiedzi.

Struktura zdarzeń

{
  "type": "conversation.item.created",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Właściwości

Przykład z elementem audio

{
  "type": "conversation.item.created",
  "item": {
    "id": "item_GHI789",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": null,
        "transcript": "What's the weather like today?"
      }
    ]
  }
}

conversation.item.retrieved

Wysłane w odpowiedzi na conversation.item.retrieve zdarzenie klienta, podając żądany element konwersacji.

Właściwości

conversation.item.obcięty

Zdarzenie serwera conversation.item.truncated jest zwracane, gdy klient obcina wcześniej asystenta elementu komunikatu audio z zdarzeniem conversation.item.truncate . To zdarzenie służy do synchronizowania zrozumienia dźwięku serwera z odtwarzaniem klienta.

To zdarzenie obcina dźwięk i usuwa transkrypcję tekstu po stronie serwera, aby upewnić się, że nie ma tekstu w kontekście, o którego użytkownik nie wie.

Struktura zdarzeń

{
  "type": "conversation.item.truncated",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

Właściwości

conversation.item.deleted

Wysłane w odpowiedzi na conversation.item.delete zdarzenie klienta, potwierdzając, że określony element został usunięty z konwersacji.

Struktura zdarzeń

{
  "type": "conversation.item.deleted",
  "item_id": "item_ABC123"
}

Właściwości

response.created

Wysłane po rozpoczęciu nowej generacji odpowiedzi. Jest to pierwsze zdarzenie w sekwencji odpowiedzi.

Struktura zdarzeń

{
  "type": "response.created",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "in_progress",
    "status_details": null,
    "output": [],
    "usage": {
      "total_tokens": 0,
      "input_tokens": 0,
      "output_tokens": 0
    }
  }
}

Właściwości

response.done

Wysłane po zakończeniu generowania odpowiedzi. To zdarzenie zawiera ostateczną odpowiedź ze wszystkimi elementami wyjściowymi i statystykami użycia.

Struktura zdarzeń

{
  "type": "response.done",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "completed",
    "status_details": null,
    "output": [
      {
        "id": "item_DEF456",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
          }
        ]
      }
    ],
    "usage": {
      "total_tokens": 87,
      "input_tokens": 52,
      "output_tokens": 35,
      "input_token_details": {
        "cached_tokens": 0,
        "text_tokens": 45,
        "audio_tokens": 7
      },
      "output_token_details": {
        "text_tokens": 15,
        "audio_tokens": 20
      }
    }
  }
}

Właściwości

response.output_item.added

Wysłane po dodaniu nowego elementu wyjściowego do odpowiedzi podczas generowania.

Struktura zdarzeń

{
  "type": "response.output_item.added",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "assistant",
    "content": []
  }
}

Właściwości

response.output_item.done

Wysłane po zakończeniu elementu wyjściowego.

Struktura zdarzeń

{
  "type": "response.output_item.done",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm doing well, thank you for asking."
      }
    ]
  }
}

Właściwości

response.content_part.added

Zdarzenie serwera response.content_part.added jest zwracane po dodaniu nowej części zawartości do elementu komunikatu asystenta podczas generowania odpowiedzi.

Struktura zdarzeń

{
  "type": "response.content_part.added",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": ""
  }
}

Właściwości

response.content_part.done

Zdarzenie serwera response.content_part.done jest zwracane, gdy część zawartości jest wykonywana strumieniowo w elemencie komunikatu asystenta.

To zdarzenie jest również zwracane, gdy odpowiedź zostanie przerwana, niekompletna lub anulowana.

Struktura zdarzeń

{
  "type": "response.content_part.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": "Hello! I'm doing well, thank you for asking."
  }
}

Właściwości

response.text.delta

Przesyłanie strumieniowe zawartości tekstowej z modelu. Wysyłane przyrostowo w miarę generowania tekstu przez model.

Struktura zdarzeń

{
  "type": "response.text.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm"
}

Właściwości

response.text.done

Wysłane po zakończeniu generowania zawartości tekstowej.

Struktura zdarzeń

{
  "type": "response.text.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Właściwości

response.audio.delta

Przesyłanie strumieniowe zawartości audio z modelu. Dźwięk jest dostarczany jako dane zakodowane w formacie base64.

Struktura zdarzeń

{
  "type": "response.audio.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

Właściwości

response.audio.done

Wysyłane po zakończeniu generowania zawartości audio.

Struktura zdarzeń

{
  "type": "response.audio.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Właściwości

response.audio_transcript.delta

Przesyłanie strumieniowe transkrypcji wygenerowanej zawartości audio.

Struktura zdarzeń

{
  "type": "response.audio_transcript.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm doing"
}

Właściwości

response.audio_transcript.done

Wysyłane po zakończeniu generowania transkrypcji audio.

Struktura zdarzeń

{
  "type": "response.audio_transcript.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Właściwości

conversation.item.input_audio_transcription.completed

Zdarzenie serwera conversation.item.input_audio_transcription.completed jest wynikiem transkrypcji audio dla mowy zapisanej w buforze audio.

Transkrypcja rozpoczyna się, gdy wejściowy bufor audio jest zatwierdzany przez klienta lub serwer (w server_vad trybie). Transkrypcja jest uruchamiana asynchronicznie z tworzeniem odpowiedzi, więc to zdarzenie może pojawić się przed zdarzeniami odpowiedzi lub po nim.

Modele interfejsu API czasu rzeczywistego akceptują dźwięk natywnie, a tym samym transkrypcję danych wejściowych to oddzielny proces uruchamiany w oddzielnym modelu rozpoznawania mowy, takim jak whisper-1. W związku z tym transkrypcja może nieco odbiegać od interpretacji modelu i powinna być traktowana jako szorstki przewodnik.

Struktura zdarzeń

{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "<item_id>",
  "content_index": 0,
  "transcript": "<transcript>"
}

Właściwości

conversation.item.input_audio_transcription.delta

Zdarzenie serwera conversation.item.input_audio_transcription.delta jest zwracane po skonfigurowaniu transkrypcji audio wejściowej, a żądanie transkrypcji dla komunikatu użytkownika jest w toku. To zdarzenie zapewnia częściowe wyniki transkrypcji w miarę ich dostępności.

Struktura zdarzeń

{
  "type": "conversation.item.input_audio_transcription.delta",
  "item_id": "<item_id>",
  "content_index": 0,
  "delta": "<delta>"
}

Właściwości

conversation.item.input_audio_transcription.failed

Zdarzenie serwera conversation.item.input_audio_transcription.failed jest zwracane, gdy skonfigurowano transkrypcję dźwięku wejściowego, a żądanie transkrypcji dla komunikatu użytkownika nie powiodło się. To zdarzenie jest oddzielone od innych error zdarzeń, aby klient mógł zidentyfikować powiązany element.

Struktura zdarzeń

{
  "type": "conversation.item.input_audio_transcription.failed",
  "item_id": "<item_id>",
  "content_index": 0,
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

Właściwości

Właściwości błędu

response.animation_blendshapes.delta

Zdarzenie serwera response.animation_blendshapes.delta jest zwracane, gdy model generuje dane blendshapes animacji w ramach odpowiedzi. To zdarzenie zapewnia przyrostowe dane blendshapes, gdy staną się dostępne.

Struktura zdarzeń

{
  "type": "response.animation_blendshapes.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "frame_index": 0,
  "frames": [
    [0.0, 0.1, 0.2, ..., 1.0]
    ...
  ]
}

Właściwości

response.animation_blendshapes.done

Zdarzenie serwera response.animation_blendshapes.done jest zwracane, gdy model zakończył generowanie danych blendshapes animacji w ramach odpowiedzi.

Struktura zdarzeń

{
  "type": "response.animation_blendshapes.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
}

Właściwości

response.audio_timestamp.delta

Zdarzenie serwera response.audio_timestamp.delta jest zwracane, gdy model generuje dane sygnatury czasowej audio w ramach odpowiedzi. To zdarzenie zapewnia przyrostowe dane sygnatury czasowej dla wyjściowego wyrównania dźwięku i tekstu, gdy staną się dostępne.

Struktura zdarzeń

{
  "type": "response.audio_timestamp.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "audio_duration_ms": 500,
  "text": "Hello",
  "timestamp_type": "word"
}

Właściwości

response.audio_timestamp.done

Wysyłane po zakończeniu generowania znacznika czasu audio.

Struktura zdarzeń

{
  "type": "response.audio_timestamp.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Właściwości

response.animation_viseme.delta

Zdarzenie serwera response.animation_viseme.delta jest zwracane, gdy model generuje dane animacji w ramach odpowiedzi. To zdarzenie zapewnia przyrostowe dane widoczne w miarę ich dostępności.

Struktura zdarzeń

{
  "type": "response.animation_viseme.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "viseme_id": 1
}

Właściwości

response.animation_viseme.done

Zdarzenie serwera response.animation_viseme.done jest zwracane po zakończeniu generowania danych animacji w ramach odpowiedzi.

Struktura zdarzeń

{
  "type": "response.animation_viseme.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Właściwości

Zdarzenie serwera response.animation_viseme.delta jest zwracane, gdy model generuje dane animacji w ramach odpowiedzi. To zdarzenie zapewnia przyrostowe dane widoczne w miarę ich dostępności.

błąd

Zdarzenie serwera error jest zwracane, gdy wystąpi błąd, który może być problemem klienta lub problemem serwera. Większość błędów można odzyskać, a sesja pozostaje otwarta.

Struktura zdarzeń

{
  "type": "error",
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>",
    "event_id": "<event_id>"
  }
}

Właściwości

Właściwości błędu

input_audio_buffer.wyczyszczone

Zdarzenie serwera input_audio_buffer.cleared jest zwracane, gdy klient czyści wejściowy bufor audio ze zdarzeniem input_audio_buffer.clear .

Struktura zdarzeń

{
  "type": "input_audio_buffer.cleared"
}

Właściwości

input_audio_buffer.committed

Zdarzenie serwera input_audio_buffer.committed jest zwracane po zatwierdzeniu wejściowego buforu audio przez klienta lub automatycznie w trybie VAD serwera. Właściwość item_id jest identyfikatorem utworzonego elementu komunikatu użytkownika. W związku z conversation.item.created tym zdarzenie jest również wysyłane do klienta.

Struktura zdarzeń

{
  "type": "input_audio_buffer.committed",
  "previous_item_id": "<previous_item_id>",
  "item_id": "<item_id>"
}

Właściwości

input_audio_buffer.speech_started

Zdarzenie serwera input_audio_buffer.speech_started jest zwracane w server_vad trybie, gdy mowa jest wykrywana w buforze audio. To zdarzenie może wystąpić za każdym razem, gdy dźwięk jest dodawany do buforu (chyba że mowa została już wykryta).

Klient powinien oczekiwać odebrania input_audio_buffer.speech_stopped zdarzenia po zatrzymaniu mowy. Właściwość item_id jest identyfikatorem elementu komunikatu użytkownika utworzonego po zatrzymaniu mowy. Element item_id jest również uwzględniony w input_audio_buffer.speech_stopped zdarzeniu, chyba że klient ręcznie zatwierdzi bufor audio podczas aktywacji VAD.

Struktura zdarzeń

{
  "type": "input_audio_buffer.speech_started",
  "audio_start_ms": 0,
  "item_id": "<item_id>"
}

Właściwości

input_audio_buffer.speech_stopped

Zdarzenie serwera input_audio_buffer.speech_stopped jest zwracane w server_vad trybie, gdy serwer wykryje koniec mowy w buforze audio.

Serwer wysyła conversation.item.created również zdarzenie z elementem komunikatu użytkownika utworzonym na podstawie buforu audio.

Struktura zdarzeń

{
  "type": "input_audio_buffer.speech_stopped",
  "audio_end_ms": 0,
  "item_id": "<item_id>"
}

Właściwości

rate_limits.updated

Zdarzenie serwera rate_limits.updated jest emitowane na początku odpowiedzi, aby wskazać zaktualizowane limity szybkości.

Po utworzeniu odpowiedzi niektóre tokeny są zarezerwowane dla tokenów wyjściowych. Przedstawione tutaj limity szybkości odzwierciedlają rezerwację, która jest następnie odpowiednio dostosowywana po zakończeniu odpowiedzi.

Struktura zdarzeń

{
  "type": "rate_limits.updated",
  "rate_limits": [
    {
      "name": "<name>",
      "limit": 0,
      "remaining": 0,
      "reset_seconds": 0
    }
  ]
}

Właściwości

response.audio.delta

Zdarzenie serwera response.audio.delta jest zwracane po zaktualizowaniu dźwięku wygenerowanego przez model.

Struktura zdarzeń

{
  "type": "response.audio.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Właściwości

response.audio.done

Zdarzenie serwera response.audio.done jest zwracane po zakończeniu generowania przez model dźwięku.

To zdarzenie jest również zwracane, gdy odpowiedź zostanie przerwana, niekompletna lub anulowana.

Struktura zdarzeń

{
  "type": "response.audio.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

Właściwości

response.audio_transcript.delta

Zdarzenie serwera response.audio_transcript.delta jest zwracane po zaktualizowaniu transkrypcji wygenerowanej przez model danych wyjściowych dźwięku.

Struktura zdarzeń

{
  "type": "response.audio_transcript.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Właściwości

response.audio_transcript.done

Zdarzenie serwera response.audio_transcript.done jest zwracane po zakończeniu przesyłania strumieniowego wygenerowanego przez model transkrypcji danych wyjściowych dźwięku.

To zdarzenie jest również zwracane, gdy odpowiedź zostanie przerwana, niekompletna lub anulowana.

Struktura zdarzeń

{
  "type": "response.audio_transcript.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "transcript": "<transcript>"
}

Właściwości

response.function_call_arguments.delta

Zdarzenie serwera response.function_call_arguments.delta jest zwracane po zaktualizowaniu argumentów wywołania funkcji wygenerowanej przez model.

Struktura zdarzeń

{
  "type": "response.function_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "delta": "<delta>"
}

Właściwości

response.function_call_arguments.done

Zdarzenie serwera response.function_call_arguments.done jest zwracane, gdy argumenty wywołania funkcji wygenerowane przez model są wykonywane strumieniowo.

To zdarzenie jest również zwracane, gdy odpowiedź zostanie przerwana, niekompletna lub anulowana.

Struktura zdarzeń

{
  "type": "response.function_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "arguments": "<arguments>"
}

Właściwości

mcp_list_tools.in_progress

Zdarzenie serwera mcp_list_tools.in_progress jest zwracane, gdy usługa rozpoczyna wyświetlanie listy dostępnych narzędzi z serwera mcp.

Struktura zdarzeń

{
  "type": "mcp_list_tools.in_progress",
  "item_id": "<mcp_list_tools_item_id>"
}

Właściwości

mcp_list_tools.completed

Zdarzenie serwera mcp_list_tools.completed jest zwracane po zakończeniu wyświetlania listy dostępnych narzędzi z serwera mcp.

Struktura zdarzeń

{
  "type": "mcp_list_tools.completed",
  "item_id": "<mcp_list_tools_item_id>"
}

Właściwości

mcp_list_tools.failed

Zdarzenie serwera mcp_list_tools.failed jest zwracane, gdy usługa nie może wyświetlić listy dostępnych narzędzi z serwera mcp.

Struktura zdarzeń

{
  "type": "mcp_list_tools.failed",
  "item_id": "<mcp_list_tools_item_id>"
}

Właściwości

response.mcp_call_arguments.delta

Zdarzenie serwera response.mcp_call_arguments.delta jest zwracane po zaktualizowaniu argumentów wywołania narzędzia mcp wygenerowanego przez model.

Struktura zdarzeń

{
  "type": "response.mcp_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "delta": "<delta>"
}

Właściwości

response.mcp_call_arguments.done

Zdarzenie serwera response.mcp_call_arguments.done jest zwracane, gdy argumenty wywołania narzędzia mcp wygenerowane przez model są wykonywane strumieniowo.

Struktura zdarzeń

{
  "type": "response.mcp_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "arguments": "<arguments>"
}

Właściwości

response.mcp_call.in_progress

Zdarzenie serwera response.mcp_call.in_progress jest zwracane, gdy wywołanie narzędzia MCP rozpoczyna przetwarzanie.

Struktura zdarzeń

{
  "type": "response.mcp_call.in_progress",
  "item_id": "<item_id>",
  "output_index": 0
}

Właściwości

response.mcp_call.completed

Zdarzenie serwera response.mcp_call.completed jest zwracane po pomyślnym zakończeniu wywołania narzędzia MCP.

Struktura zdarzeń

{
  "type": "response.mcp_call.completed",
  "item_id": "<item_id>",
  "output_index": 0
}

Właściwości

response.mcp_call.failed

Zdarzenie serwera response.mcp_call.failed jest zwracane, gdy wywołanie narzędzia MCP kończy się niepowodzeniem.

Struktura zdarzeń

{
  "type": "response.mcp_call.failed",
  "item_id": "<item_id>",
  "output_index": 0
}

Właściwości

response.output_item.added

Zdarzenie serwera response.output_item.added jest zwracane po utworzeniu nowego elementu podczas generowania odpowiedzi.

Struktura zdarzeń

{
  "type": "response.output_item.added",
  "response_id": "<response_id>",
  "output_index": 0
}

Właściwości

response.output_item.done

Zdarzenie serwera response.output_item.done jest zwracane po zakończeniu przesyłania strumieniowego elementu.

To zdarzenie jest również zwracane, gdy odpowiedź zostanie przerwana, niekompletna lub anulowana.

Struktura zdarzeń

{
  "type": "response.output_item.done",
  "response_id": "<response_id>",
  "output_index": 0
}

Właściwości

response.text.delta

Zdarzenie serwera response.text.delta jest zwracane po zaktualizowaniu tekstu wygenerowanego przez model. Tekst odpowiada text części zawartości elementu komunikatu asystenta.

Struktura zdarzeń

{
  "type": "response.text.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Właściwości

response.text.done

Zdarzenie serwera response.text.done jest zwracane po zakończeniu przesyłania strumieniowego tekstu wygenerowanego przez model. Tekst odpowiada text części zawartości elementu komunikatu asystenta.

To zdarzenie jest również zwracane, gdy odpowiedź zostanie przerwana, niekompletna lub anulowana.

Struktura zdarzeń

{
  "type": "response.text.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "text": "<text>"
}

Właściwości

Components

Formaty audio

RealtimeAudioFormat

Podstawowy format audio używany do wprowadzania dźwięku.

Dozwolone wartości:

• pcm16 - 16-bitowy format audio PCM
• g711_ulaw - G.711 format audio μ-law
• g711_alaw - Format audio G.711 A-law

RealtimeOutputAudioFormat

Format audio używany na potrzeby dźwięku wyjściowego z określonymi częstotliwościami próbkowania.

Dozwolone wartości:

• pcm16 - 16-bitowy format audio PCM z domyślną częstotliwością próbkowania (24kHz)
• pcm16_8000hz - 16-bitowy format audio PCM z częstotliwością próbkowania 8kHz
• pcm16_16000hz - 16-bitowy format audio PCM z częstotliwością próbkowania 16kHz
• g711_ulaw - Format audio G.711 μ-law (mu-law) z częstotliwością próbkowania 8kHz
• g711_alaw - Format audio G.711 A-law z częstotliwością próbkowania 8kHz

RealtimeAudioInputTranscriptionSettings

Konfiguracja transkrypcji dźwięku wejściowego.

RealtimeInputAudioNoiseReductionSettings

Może to być:

• Obiekt RealtimeOpenAINoiseReduction
• Obiekt RealtimeAzureDeepNoiseSuppression

RealtimeOpenAINoiseReduction

Konfiguracja redukcji szumu interfejsu OpenAI z jawnym polem typu, dostępnym tylko dla gpt-realtime modeli i gpt-realtime-mini .

RealtimeAzureDeepNoiseSuppression

Konfiguracja redukcji szumu dźwięku wejściowego.

RealtimeInputAudioEchoCancellationSettings

Konfiguracja anulowania echa na potrzeby przetwarzania dźwięku po stronie serwera.

Konfiguracja głosu

RealtimeVoice

Unii wszystkich obsługiwanych konfiguracji głosowych.

Może to być:

• Obiekt RealtimeOpenAIVoice
• Obiekt RealtimeAzureVoice

RealtimeOpenAIVoice

Konfiguracja głosu OpenAI z jawnym polem typu.

RealtimeAzureVoice

Podstawowe informacje na potrzeby konfiguracji głosowych platformy Azure. Jest to związek dyskryminowany z różnymi typami:

RealtimeAzureStandardVoice

Standardowa konfiguracja głosu platformy Azure.

RealtimeAzureCustomVoice

Niestandardowa konfiguracja głosu platformy Azure (preferowana dla niestandardowych głosów).

Przykład:

{
  "type": "azure-custom",
  "name": "my-custom-voice",
  "endpoint_id": "12345678-1234-1234-1234-123456789012",
  "temperature": 0.7,
  "style": "cheerful",
  "locale": "en-US"
}

RealtimeAzurePersonalVoice

Konfiguracja osobistego głosu platformy Azure.

Wykrywanie obrotu

RealtimeTurnDetection

Konfiguracja wykrywania obrotu. Jest to dyskryminowana unia obsługująca wiele typów VAD.

RealtimeServerVAD

Podstawowe wykrywanie obrotu oparte na vaD.

RealtimeOpenAISemanticVAD

Semantyczna konfiguracja vaD interfejsu OpenAI, która używa modelu do określenia, kiedy użytkownik zakończył pracę. Dostępne tylko dla gpt-realtime modeli i gpt-realtime-mini .

RealtimeAzureSemanticVAD

Semantyczna usługa VAD platformy Azure, która określa, kiedy użytkownik rozpoczyna korzystanie z semantycznego modelu mowy, zapewniając bardziej niezawodne wykrywanie w hałaśliwych środowiskach.

RealtimeAzureSemanticVADMultilingual

Semantyczna usługa VAD platformy Azure (wariant domyślny).

RealtimeEOUDetection

End-of-Utterance (EOU) platformy Azure może wskazywać, kiedy użytkownik końcowy przestał mówić, umożliwiając naturalne wstrzymanie. Wykrywanie końca wypowiedzi może znacznie zmniejszyć przedwczesne sygnały końca tury bez dodawania wykrywalnych przez użytkownika opóźnień.

Konfiguracja awatara

RealtimeAvatarConfig

Konfiguracja przesyłania strumieniowego i zachowania awatara.

RealtimeIceServer

Konfiguracja serwera ICE na potrzeby negocjacji połączenia WebRTC.

RealtimeVideoParams

Parametry przesyłania strumieniowego wideo dla awatara.

RealtimeVideoCrop

Definicja prostokąta przycinania wideo.

RealtimeVideoResolution

Specyfikacja rozdzielczości wideo.

Konfiguracja animacji

RealtimeAnimation

Konfiguracja dla danych wyjściowych animacji, w tym blendshapes i visemes.

RealtimeAnimationOutputType

Typy danych animacji do danych wyjściowych.

Dozwolone wartości:

• blendshapes - Dane mieszania twarzy
• viseme_id - Dane identyfikatora viseme

Konfiguracja sesji

RealtimeRequestSession

Obiekt konfiguracji sesji używany w session.update zdarzeniach.

Tryb rzeczywisty

Obsługiwane modalności sesji.

Dozwolone wartości:

• text - Wprowadzanie tekstu/dane wyjściowe
• audio - Wejście/wyjście audio
• animation - Dane wyjściowe animacji
• avatar - Dane wyjściowe wideo awatara

RealtimeAudioTimestampType

Typy sygnatur czasowych danych wyjściowych obsługiwane w zawartości odpowiedzi audio.

Dozwolone wartości:

• word - Znaczniki czasu na słowo w wyjściowym dźwięku

Konfiguracja narzędzia

Obsługujemy dwa typy narzędzi: wywoływanie funkcji i narzędzia MCP, które umożliwiają nawiązywanie połączenia z serwerem mcp.

Narzędzia czasu rzeczywistego

Definicja narzędzia do wywoływania funkcji.

RealtimeToolChoice

Strategia wyboru narzędzi.

Może to być:

• "auto" - Pozwól modelowi wybrać
• "none" — Nie używaj narzędzi
• "required" - Musi używać narzędzia
• { "type": "function", "name": "function_name" } - Korzystanie z określonej funkcji

McPTool

Konfiguracja narzędzia MCP.

RealtimeConversationResponseItem

Jest to typ unii, który może być jednym z następujących:

RealtimeConversationUserMessageItem

Element wiadomości użytkownika.

RealtimeConversationAssistantMessageItem

Element komunikatu asystenta.

RealtimeConversationSystemMessageItem

Element komunikatu systemowego.

RealtimeConversationFunctionCallItem

Element żądania wywołania funkcji.

RealtimeConversationFunctionCallOutputItem

Element odpowiedzi wywołania funkcji.

RealtimeConversationMCPListToolsItem

Element odpowiedzi narzędzi listy MCP.

RealtimeConversationMCPCallItem

Element odpowiedzi wywołania MCP.

RealtimeConversationMCPApprovalRequestItem

Element żądania zatwierdzenia MCP.

RealtimeItemStatus

Stan elementów konwersacji.

Dozwolone wartości:

• in_progress - Obecnie przetwarzane
• completed — Ukończono pomyślnie
• incomplete — Niekompletne (przerwane lub zakończone niepowodzeniem)

RealtimeContentPart

Część zawartości w wiadomości.

RealtimeInputTextContentPart

Część zawartości tekstowej.

RealtimeOutputTextContentPart

Część zawartości tekstowej.

RealtimeInputAudioContentPart

Część zawartości audio.

RealtimeOutputAudioContentPart

Część zawartości audio.

Obiekty odpowiedzi

Czas rzeczywistyResponse

Obiekt odpowiedzi reprezentujący odpowiedź wnioskowania modelu.

RealtimeResponseStatus

Wartości stanu odpowiedzi.

Dozwolone wartości:

• in_progress - Odpowiedź jest generowana
• completed — Odpowiedź została ukończona pomyślnie
• cancelled — Odpowiedź została anulowana
• incomplete — Niekompletna odpowiedź (przerwana)
• failed — Odpowiedź nie powiodła się z powodu błędu

Czas rzeczywistyUsage

Statystyki użycia tokenu.

TokenDetails

Szczegółowy podział użycia tokenu.

Obsługa błędów

RealtimeErrorDetails

Obiekt informacji o błędzie.

RealtimeConversationRequestItem

Obiekt służy RealtimeConversationRequestItem do tworzenia nowego elementu w konwersacji za pośrednictwem zdarzenia conversation.item.create .

Jest to typ unii, który może być jednym z następujących:

RealtimeSystemMessageItem

Element komunikatu systemowego.

RealtimeUserMessageItem

Element komunikatu użytkownika.

RealtimeAssistantMessageItem

Element komunikatu asystenta.

RealtimeFunctionCallItem

Element wywołania funkcji.

RealtimeFunctionCallOutputItem

Element wyjściowy wywołania funkcji.

RealtimeMCPApprovalResponseItem

Element odpowiedzi na zatwierdzenie MCP.

RealtimeFunctionTool

Definicja narzędzia funkcji używanego przez punkt końcowy czasu rzeczywistego.

RealtimeItemStatus

Dozwolone wartości:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

Obiekt RealtimeResponseSession reprezentuje sesję w interfejsie API czasu rzeczywistego. Jest on używany w niektórych zdarzeniach serwera, takich jak:

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Powiązane zasoby

• Wypróbuj Voice live quickstart
• Wypróbuj agentów głosowych na żywo — szybki start
• Dowiedz się więcej o sposobie korzystania z interfejsu API na żywo voice