Voice Live 2025-10-01 API-Referenz

Die Voice Live API bietet Echtzeit-bidirektionale Kommunikation für sprachgestützte Anwendungen über WebSocket-Verbindungen. Diese API unterstützt fortschrittliche Funktionen wie Spracherkennung, Text-zu-Sprach-Synthese, Avatar-Streaming, Animationsdaten und umfassende Audioverarbeitungsfunktionen.

Die API verwendet JSON-formatierte Ereignisse, die über WebSocket-Verbindungen gesendet werden, um Gespräche, Audiostreams, Avatar-Interaktionen und Echtzeitantworten zu verwalten. Ereignisse werden in Client-Events (vom Client zum Server gesendet) und Server-Events (vom Server zu Client gesendet) unterteilt.

Key Features

• Echtzeit-Audioverarbeitung: Unterstützung für mehrere Audioformate, einschließlich PCM16 bei unterschiedlichen Abtastraten und G.711-Codecs
• Erweiterte Sprachoptionen: OpenAI-Stimmen, Azure benutzerdefinierte Stimmen, Azure Standardstimmen und Azure persönliche Stimmen
• Avatar-Integration: WebRTC-basiertes Avatar-Streaming mit Video, Animation und Blendshapes
• Intelligente Dreherkennung: Mehrere VAD-Optionen, darunter Azure semantisches VAD und serverseitige Erkennung
• Audio-Verbesserung: Eingebaute Rauschunterdrückung und Echounterdrückung
• Function Calling: Tool-Integration für verbesserte Konversationsmöglichkeiten
• Flexible Sitzungsverwaltung: Konfigurierbare Ausgabemodalitäten, Anweisungen und Antwortparameter

Client Events

Die Voice Live API unterstützt folgende Client-Events, die vom Client an den Server gesendet werden können:

session.update

Aktualisieren Sie die Konfiguration der Sitzung. Dieses Ereignis kann jederzeit gesendet werden, um Einstellungen wie Sprache, Ausgabemodalitäten, Zugerkennung, Werkzeuge und andere Sitzungsparameter zu ändern. Beachte, dass eine Sitzung, sobald sie mit einem bestimmten Modell initialisiert wurde, nicht mehr in ein anderes Modell geändert werden kann.

Event Structure

{
  "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"
  }
}

Properties

Beispiel mit 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

Stellen Sie eine Avatarverbindung her, indem Sie das SDP-Angebot (Session Description Protocol) des Kunden für WebRTC-Medienverhandlungen bereitstellen. Dieses Ereignis ist erforderlich, wenn Avatar-Funktionen verwendet werden.

Event Structure

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

Properties

input_audio_buffer.append

Fügen Sie Audiobytes dem Eingabe-Audiopuffer hinzu.

Event Structure

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

Properties

input_audio_buffer.commit

Committen Sie den Eingangs-Audiopuffer zur Verarbeitung.

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

Lösche den Eingangs-Audiopuffer.

Event Structure

{
  "type": "input_audio_buffer.clear"
}

Properties

conversation.item.create

Füge einen neuen Gegenstand zum Gesprächskontext hinzu. Dies kann Nachrichten, Funktionsaufrufe und Funktionsaufrufantworten umfassen. Punkte können an bestimmten Stellen im Gesprächsverlauf eingefügt werden.

Event Structure

{
  "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?"
      }
    ]
  }
}

Properties

Beispiel mit Audio-Inhalten

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

Beispiel mit Function Call-Ausgabe

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_123",
    "output": "{\"location\": \"San Francisco\", \"temperature\": \"70\"}"
  }
}

Beispiel mit MCP-Genehmigungsantwort

{
  "type": "conversation.item.create",
  "item": {
    "type": "mcp_approval_response",
    "approval_request_id": "mcp_approval_req_456",
    "approve": true,
  }
}

conversation.item.retrieve

Rufen Sie einen bestimmten Gegenstand aus dem Gesprächsverlauf ab. Dies ist nützlich, um verarbeitete Audioaufnahmen nach Rauschunterdrückung und VAD zu inspizieren.

Event Structure

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

Properties

conversation.item.truncate

Kürze den Audioinhalt einer Assistentennachricht. Dies ist nützlich, um die Wiedergabe an einem bestimmten Punkt zu stoppen und das Verständnis des Servers mit dem Zustand des Clients zu synchronisieren.

Event Structure

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

Properties

conversation.item.delete

Entferne einen Punkt aus dem Gesprächsverlauf.

Event Structure

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

Properties

response.create

Weist den Server an, eine Antwort über Modellinferenz zu erstellen. Dieses Ereignis kann eine reaktionsspezifische Konfiguration spezifizieren, die die Sitzungsstandardeinstellungen überschreibt.

Event Structure

{
  "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
  }
}

Properties

Beispiel mit Tool Choice

{
  "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
  }
}

Beispiel mit Animation

{
  "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

Stornieren Sie eine laufende Antwort. Dadurch wird sofort die Antwortgenerierung und die zugehörige Audioausgabe gestoppt.

Event Structure

{
  "type": "response.cancel"
}

Properties

input_audio_buffer.append

Das Client-Event input_audio_buffer.append wird verwendet, um Audiobytes an den Eingabe-Audiopuffer anzuhängen. Der Audiopuffer ist ein temporärer Speicher, auf den du schreiben und später committen kannst.

Im Server VAD (Voice Activity Detection)-Modus wird der Audiopuffer verwendet, um Sprache zu erkennen, und der Server entscheidet, wann er commitet. Wenn das Server-VAD deaktiviert ist, kann der Client wählen, wie viel Audio in jedem Ereignis bis zu maximal 15 MiB eingefügt werden soll. Zum Beispiel kann das Streamen kleinerer Abschnitte vom Client das VAD ermöglichen, reaktionsschneller zu werden.

Im Gegensatz zu den meisten anderen Client-Events sendet der Server keine Bestätigungsantwort an das Client-Event input_audio_buffer.append .

Event structure

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

Properties

input_audio_buffer.clear

Das Client-Event input_audio_buffer.clear wird verwendet, um die Audiobytes im Puffer zu löschen.

Der Server antwortet mit einem input_audio_buffer.cleared Ereignis.

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

input_audio_buffer.commit

Das Client-Event input_audio_buffer.commit wird verwendet, um den Audiopuffer der Benutzereingabe zu committen, der ein neues Benutzernachrichtenelement in der Konversation erstellt. Audio wird transkribiert, wenn input_audio_transcription es für die Sitzung konfiguriert ist.

Im Server-VAD-Modus muss der Client dieses Ereignis nicht senden, sondern der Server comminiert automatisch den Audiopuffer. Ohne Server-VAD muss der Client den Audiopuffer committen, um ein Benutzernachrichtenelement zu erstellen. Dieses Client-Ereignis erzeugt einen Fehler, wenn der Eingangs-Audiopuffer leer ist.

Das Committing des Eingangs-Audiopuffers erzeugt keine Reaktion vom Modell.

Der Server antwortet mit einem input_audio_buffer.committed Ereignis.

Event structure

{
  "type": "input_audio_buffer.commit"
}

Properties

Server Events

Die Voice Live API sendet folgende Serverereignisse, um Status, Antworten und Daten an den Client zu kommunizieren:

session.created

Gesendet, wenn eine neue Sitzung erfolgreich eingerichtet wurde. Dies ist das erste Ereignis, das nach der Verbindung zur API empfangen wird.

Event Structure

{
  "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"
  }
}

Properties

session.updated

Gesendet, wenn die Sitzungskonfiguration als Reaktion auf ein session.update Client-Ereignis erfolgreich aktualisiert wurde.

Event Structure

{
  "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
    }
  }
}

Properties

session.avatar.connecting

Zeigt an, dass eine Avatar-WebRTC-Verbindung hergestellt wird. Dieses Ereignis wird als Antwort auf ein session.avatar.connect Kundenereignis gesendet.

Event Structure

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

Properties

conversation.item.created

Gesendet, wenn ein neuer Punkt zur Konversation hinzugefügt wird, entweder über ein Kundenereignis conversation.item.create oder automatisch während der Antwortgenerierung.

Event Structure

{
  "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?"
      }
    ]
  }
}

Properties

Beispiel mit Audio-Item

{
  "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

Gesendet als Antwort auf ein conversation.item.retrieve Kundenereignis und liefert das gewünschte Gesprächsobjekt.

Event Structure

{
  "type": "conversation.item.retrieved",
  "item": {
    "id": "item_ABC123",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
      }
    ]
  }
}

Properties

conversation.item.truncated

Das Server-Event conversation.item.truncated wird zurückgegeben, wenn der Client ein früheres Assistant-Audio-Message-Element mit einem Ereignis abschneidet conversation.item.truncate . Dieses Ereignis wird verwendet, um das Verständnis des Tons durch den Server mit der Wiedergabe des Clients zu synchronisieren.

Dieses Ereignis kürzt das Audio und entfernt das serverseitige Texttranskript, um sicherzustellen, dass kein Text im Kontext vorhanden ist, von dem der Nutzer nichts weiß.

Event structure

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

Properties

conversation.item.deleted

Gesendet als Antwort auf ein conversation.item.delete Kundenereignis, das bestätigt, dass der angegebene Punkt aus dem Gespräch entfernt wurde.

Event Structure

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

Properties

response.created

Gesendet, wenn eine neue Antwortgenerierung beginnt. Dies ist das erste Ereignis in einer Reaktionssequenz.

Event Structure

{
  "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
    }
  }
}

Properties

response.done

Gesendet, wenn die Antwortgenerierung abgeschlossen ist. Dieses Ereignis enthält die endgültige Antwort mit allen Ausgabeeinträgen und Nutzungsstatistiken.

Event Structure

{
  "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
      }
    }
  }
}

Properties

response.output_item.added

Gesendet, wenn während der Generierung ein neues Ausgabeelement zur Antwort hinzugefügt wird.

Event Structure

{
  "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": []
  }
}

Properties

response.output_item.done

Gesendet, wenn ein Ausgabepunkt abgeschlossen ist.

Event Structure

{
  "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."
      }
    ]
  }
}

Properties

response.content_part.added

Das Server-Ereignis response.content_part.added wird zurückgegeben, wenn während der Antwortgenerierung ein neuer Inhaltsteil zu einem Assistant-Nachrichtenelement hinzugefügt wird.

Event Structure

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

Properties

response.content_part.done

Das Server-Event response.content_part.done wird zurückgegeben, wenn ein Inhaltsteil in einem Assistant-Nachrichtenelement gestreamt wird.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen, unvollständig oder abgebrochen wird.

Event Structure

{
  "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."
  }
}

Properties

response.text.delta

Streamende Textinhalte vom Modell. Wird schrittweise gesendet, während das Modell Text erzeugt.

Event Structure

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

Properties

response.text.done

Gesendet, wenn die Textinhaltserstellung abgeschlossen ist.

Event Structure

{
  "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?"
}

Properties

response.audio.delta

Audio-Inhalte vom Modell werden gestreamt. Audio wird als base64-kodierte Daten bereitgestellt.

Event Structure

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

Properties

response.audio.done

Gesendet, wenn die Audio-Generierung abgeschlossen ist.

Event Structure

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

Properties

response.audio_transcript.delta

Streaming-Transkript der generierten Audioinhalte.

Event Structure

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

Properties

response.audio_transcript.done

Gesendet, wenn die Audiotranskripterstellung abgeschlossen ist.

Event Structure

{
  "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?"
}

Properties

conversation.item.input_audio_transcription.completed

Das Server-Event conversation.item.input_audio_transcription.completed ist das Ergebnis der Audiotranskription für Sprache, die in den Audiopuffer geschrieben wurde.

Die Transkription beginnt, wenn der Eingabe-Audiopuffer vom Client oder Server (im Modus server_vad ) ausgeführt wird. Die Transkription läuft asynchron mit der Antworterstellung ab, sodass dieses Ereignis vor oder nach den Reaktionsereignissen auftreten kann.

Echtzeit-API-Modelle akzeptieren Audio nativ, sodass die Eingabetranskription ein separater Prozess ist, der auf einem separaten Spracherkennungsmodell wie whisper-1ausgeführt wird. Daher kann das Transkript etwas von der Interpretation des Modells abweichen und sollte als grobe Orientierung behandelt werden.

Event structure

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

Properties

conversation.item.input_audio_transcription.delta

Das Serverereignis conversation.item.input_audio_transcription.delta wird zurückgegeben, wenn die Eingabe-Audiotranskription konfiguriert wird und eine Transkriptionsanfrage für eine Benutzernachricht im Gange ist. Diese Veranstaltung liefert teilweise Transkriptionsergebnisse, sobald sie verfügbar sind.

Event structure

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

Properties

conversation.item.input_audio_transcription.failed

Das Serverereignis conversation.item.input_audio_transcription.failed wird zurückgegeben, wenn die Eingabe-Audiotranskription konfiguriert wird und eine Transkriptionsanfrage für eine Benutzernachricht fehlschlägt. Dieses Ereignis ist von anderen error Ereignissen getrennt, sodass der Kunde das zugehörige Element identifizieren kann.

Event structure

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

Properties

Error properties

response.animation_blendshapes.delta

Das Server-Event response.animation_blendshapes.delta wird zurückgegeben, wenn das Modell als Teil einer Antwort Animations-Blendshapes-Daten erzeugt. Dieses Ereignis liefert inkrementelle Blendshapes-Daten, sobald sie verfügbar sind.

Event structure

{
  "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]
    ...
  ]
}

Properties

response.animation_blendshapes.done

Das Serverereignis response.animation_blendshapes.done wird zurückgegeben, wenn das Modell die Animations-Blendshapes-Daten als Teil einer Antwort generiert hat.

Event structure

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

Properties

response.audio_timestamp.delta

Das Serverereignis response.audio_timestamp.delta wird zurückgegeben, wenn das Modell Audio-Zeitstempeldaten als Teil einer Antwort erzeugt. Dieses Ereignis liefert inkrementelle Zeitstempeldaten für die Ausrichtung von Audio und Text, sobald sie verfügbar sind.

Event structure

{
  "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"
}

Properties

response.audio_timestamp.done

Gesendet, wenn die Erstellung des Audio-Zeitstempels abgeschlossen ist.

Event Structure

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

Properties

response.animation_viseme.delta

Das Serverereignis response.animation_viseme.delta wird zurückgegeben, wenn das Modell Animationsviseme-Daten als Teil einer Antwort erzeugt. Dieses Ereignis liefert inkrementelle Visem-Daten, sobald sie verfügbar sind.

Event Structure

{
  "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
}

Properties

response.animation_viseme.done

Das Serverereignis response.animation_viseme.done wird zurückgegeben, wenn das Modell die Generierung von Animationsviseme-Daten als Teil einer Antwort abgeschlossen hat.

Event Structure

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

Properties

error

Das Serverereignis error wird zurückgegeben, wenn ein Fehler auftritt, was ein Client- oder Serverproblem sein kann. Die meisten Fehler sind wiederherstellbar und die Sitzung bleibt offen.

Event structure

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

Properties

Error properties

warning

Das Serverereignis warning wird zurückgegeben, wenn eine Warnung auftritt, die den Gesprächsfluss nicht unterbricht. Die Warnungen sind informativ und die Sitzung läuft wie gewohnt weiter.

Event structure

{
  "type": "warning",
  "warning": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

Properties

Warning properties

input_audio_buffer.cleared

Das Serverereignis input_audio_buffer.cleared wird zurückgegeben, wenn der Client den Eingabe-Audiopuffer mit einem Ereignis input_audio_buffer.clear löscht.

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

input_audio_buffer.committed

Das Server-Event input_audio_buffer.committed wird zurückgegeben, wenn ein Eingabe-Audiopuffer entweder vom Client oder automatisch im Server-VAD-Modus eingetragen wird. Die Eigenschaft item_id ist die ID des erstellten Benutzernachrichtenelements. So wird auch ein conversation.item.created Ereignis an den Kunden gesendet.

Event structure

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

Properties

input_audio_buffer.speech_started

Das Serverereignis input_audio_buffer.speech_started wird im server_vad Modus zurückgegeben, wenn Sprache im Audiopuffer erkannt wird. Dieses Ereignis kann jedes Mal auftreten, wenn Audio dem Puffer hinzugefügt wird (es sei denn, Sprache wird bereits erkannt).

Der Klient sollte damit rechnen, ein input_audio_buffer.speech_stopped Ereignis zu erhalten, wenn die Sprache stoppt. Die Eigenschaft item_id ist die ID des Benutzernachrichtenelements, das erstellt wird, wenn die Sprache stoppt. Dies item_id ist auch im input_audio_buffer.speech_stopped Ereignis enthalten, es sei denn, der Client committiert den Audiopuffer während der VAD-Aktivierung manuell.

Event structure

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

Properties

input_audio_buffer.speech_stopped

Das Serverereignis input_audio_buffer.speech_stopped wird im server_vad Modus zurückgegeben, wenn der Server das Ende der Sprache im Audiopuffer erkennt.

Der Server sendet außerdem ein conversation.item.created Ereignis mit dem Benutzernachrichtenelement, das aus dem Audiopuffer erstellt wird.

Event structure

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

Properties

rate_limits.updated

Das Serverereignis rate_limits.updated wird zu Beginn einer Antwort ausgesendet, um die aktualisierten Rate-Limits anzuzeigen.

Wenn eine Antwort erstellt wird, werden einige Token für die Ausgabetoken reserviert. Die hier gezeigten Tarifgrenzen spiegeln diese Reservierung wider, die dann entsprechend angepasst wird, sobald die Antwort abgeschlossen ist.

Event structure

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

Properties

response.audio.delta

Das Server-Event response.audio.delta wird zurückgegeben, wenn das modellgenerierte Audio aktualisiert wird.

Event structure

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

Properties

response.audio.done

Das Serverereignis response.audio.done wird zurückgegeben, wenn das modellgenerierte Audio abgeschlossen ist.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen, unvollständig oder abgebrochen wird.

Event structure

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

Properties

response.audio_transcript.delta

Das Serverereignis response.audio_transcript.delta wird zurückgegeben, wenn die modellgenerierte Transkription der Audioausgabe aktualisiert wird.

Event structure

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

Properties

response.audio_transcript.done

Das Serverereignis response.audio_transcript.done wird zurückgegeben, wenn die modellgenerierte Transkription der Audioausgabe gestreamt wurde.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen, unvollständig oder abgebrochen wird.

Event structure

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

Properties

response.function_call_arguments.delta

Das Server-Event response.function_call_arguments.delta wird zurückgegeben, wenn die modellgenerierten Funktionsaufruf-Argumente aktualisiert werden.

Event structure

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

Properties

response.function_call_arguments.done

Das Serverereignis response.function_call_arguments.done wird zurückgegeben, wenn die vom Modell generierten Funktionsaufruf-Argumente mit dem Streaming abgeschlossen sind.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen, unvollständig oder abgebrochen wird.

Event structure

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

Properties

mcp_list_tools.in_progress

Das Server-Event mcp_list_tools.in_progress wird zurückgegeben, wenn der Dienst beginnt, verfügbare Werkzeuge von einem MCP-Server aufzulisten.

Event structure

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

Properties

mcp_list_tools.completed

Das Server-Event mcp_list_tools.completed wird zurückgegeben, wenn der Dienst die verfügbaren Werkzeuge eines MCP-Servers auflistet.

Event structure

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

Properties

mcp_list_tools.failed

Das Serverereignis mcp_list_tools.failed wird zurückgegeben, wenn der Dienst nicht die verfügbaren Werkzeuge eines MCP-Servers auflistet.

Event structure

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

Properties

response.mcp_call_arguments.delta

Das Serverereignis response.mcp_call_arguments.delta wird zurückgegeben, wenn die vom Modell generierten MCP-Toolaufruf-Argumente aktualisiert werden.

Event structure

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

Properties

response.mcp_call_arguments.done

Das Serverereignis response.mcp_call_arguments.done wird zurückgegeben, wenn die vom Modell generierten MCP-Tool-Aufrufargumente mit dem Streaming abgeschlossen sind.

Event structure

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

Properties

response.mcp_call.in_progress

Das Serverereignis response.mcp_call.in_progress wird zurückgegeben, wenn ein MCP-Tool-Aufruf mit der Verarbeitung beginnt.

Event structure

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

Properties

response.mcp_call.completed

Das Server-Event response.mcp_call.completed wird zurückgegeben, wenn ein MCP-Tool-Aufruf erfolgreich abgeschlossen ist.

Event structure

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

Properties

response.mcp_call.failed

Das Server-Event response.mcp_call.failed wird zurückgegeben, wenn ein MCP-Tool-Aufruf fehlschlägt.

Event structure

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

Properties

response.output_item.added

Das Server-Event response.output_item.added wird zurückgegeben, wenn während der Antwortgenerierung ein neues Element erstellt wird.

Event structure

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

Properties

response.output_item.done

Das Server-Event response.output_item.done wird zurückgegeben, wenn ein Item das Streaming beendet hat.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen, unvollständig oder abgebrochen wird.

Event structure

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

Properties

response.text.delta

Das Serverereignis response.text.delta wird zurückgegeben, wenn der modellgenerierte Text aktualisiert wird. Der Text entspricht dem text Inhaltsteil eines Assistant-Nachrichtenelements.

Event structure

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

Properties

response.text.done

Das Server-Event response.text.done wird zurückgegeben, wenn der modellgenerierte Text mit dem Streaming abgeschlossen ist. Der Text entspricht dem text Inhaltsteil eines Assistant-Nachrichtenelements.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen, unvollständig oder abgebrochen wird.

Event structure

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

Properties

Components

Audio Formats

RealtimeAudioFormat

Basis-Audioformat, das für den Eingabeton verwendet wird.

Allowed Values:

• pcm16 - 16-Bit-PCM-Audioformat
• g711_ulaw - G.711 μ-Law Audioformat
• g711_alaw - G.711 A-Law Audioformat

RealtimeOutputAudioFormat

Das Audioformat wird für die Ausgabe von Audio mit bestimmten Abtastraten verwendet.

Allowed Values:

• pcm16 - 16-Bit-PCM-Audioformat mit Standardabtastrate (24 kHz)
• pcm16_8000hz - 16-Bit-PCM-Audioformat mit 8 kHz Abtastrate
• pcm16_16000hz - 16-Bit-PCM-Audioformat mit 16 kHz Abtastrate
• g711_ulaw - G.711 μ-Law (mu-law) Audioformat mit 8 kHz Abtastrate
• g711_alaw - G.711 A-Law Audioformat mit 8 kHz Abtastrate

RealtimeAudioInputTranscriptionSettings

Konfiguration für Eingabe-Audio-Transkription.

RealtimeInputAudioNoiseReductionSettings

Dies kann sein:

• Ein RealtimeOpenAINoiseReduction-Objekt
• Ein RealtimeAzureDeepNoiseSuppression-Objekt

RealtimeOpenAINoiseReduction

OpenAI Rauschunterdrückungskonfiguration mit explizitem Typfeld, nur verfügbar für gpt-realtime und gpt-realtime-mini Modelle.

RealtimeAzureDeepNoiseSuppression

Konfiguration zur Rauschreduktion des Eingangs-Audios.

RealtimeInputAudioEchoCancellationSettings

Echo-Unterdrückungskonfiguration für serverseitige Audioverarbeitung.

Voice Configuration

RealtimeVoice

Vereinigung aller unterstützten Sprachkonfigurationen.

Dies kann sein:

• Ein RealtimeOpenAIVoice-Objekt
• Ein RealtimeAzureVoice-Objekt

RealtimeOpenAIVoice

OpenAI-Sprachkonfiguration mit explizitem Typfeld.

RealtimeAzureVoice

Base für Azure Sprachkonfigurationen. Dies ist eine diskriminierte Vereinigung mit verschiedenen Typen:

RealtimeAzureStandardVoice

Azure Standard Voice Configuration.

RealtimeAzureCustomVoice

Azure benutzerdefinierte Sprachkonfiguration (bevorzugt für benutzerdefinierte Stimmen).

Example:

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

RealtimeAzurePersonalVoice

Azure Personal Voice Configuration.

Turn Detection

RealtimeTurnDetection

Konfiguration für Abbiegungserkennung. Dies ist eine diskriminierte Gewerkschaft, die mehrere VAD-Typen unterstützt.

RealtimeServerVAD

Basis-VAD-basierte Zugerkennung.

RealtimeOpenAISemanticVAD

OpenAI semantische VAD-Konfiguration, die ein Modell verwendet, um zu bestimmen, wann der Benutzer mit dem Sprechen fertig ist. Es gibt nur Modelle und gpt-realtimegpt-realtime-mini Modelle.

RealtimeAzureSemanticVAD

Azure semantisches VAD, das bestimmt, wann der Benutzer mit einem semantischen Sprachmodell beginnt und spricht, was eine robustere Erkennung in rauschen Umgebungen ermöglicht.

RealtimeAzureSemanticVADMultilingual

Azure semantic VAD (default variant).

RealtimeEOUDetection

Azure End-of-Utterance (EOU) konnte anzeigen, wann der Endnutzer aufhörte zu sprechen, während natürliche Pausen erlaubt wurden. Die End-of-Utterance-Erkennung kann vorzeitige End-of-Turn-Signale erheblich reduzieren, ohne benutzerwahrnehmbare Latenz hinzuzufügen.

Avatar Configuration

RealtimeAvatarConfig

Konfiguration für Avatar-Streaming und Verhalten.

RealtimeIceServer

ICE-Serverkonfiguration für WebRTC-Verbindungsverhandlung.

RealtimeVideoParams

Video-Streaming-Parameter für den Avatar.

RealtimeVideoCrop

Definition von Rechtecken im Videozuschnitt.

RealtimeVideoResolution

Videoauflösungsspezifikation.

RealtimeAvatarScene

Konfiguration für den Zoomlevel, die Position, die Rotation und die Bewegungsamplitude des Avatars im Videobild.

Animation Configuration

RealtimeAnimation

Konfiguration für Animationsausgaben, einschließlich Blendshapes und Vizeme.

RealtimeAnimationOutputType

Arten von Animationsdaten, die ausgegeben werden sollen.

Allowed Values:

• blendshapes - Daten zu Gesichtsmischungen
• viseme_id - Viseme-Identifikatordaten

Session Configuration

RealtimeRequestSession

Sitzungskonfigurationsobjekt, das in Events verwendet session.update wird.

RealtimeModality

Unterstützte Sitzungsausgabemodalitäten.

Allowed Values:

• text - Textausgabe
• audio - Audioausgabe
• animation - Animationsausgabe
• avatar - Avatar-Videoausgabe

RealtimeAudioTimestampType

Ausgabe-Zeitstempeltypen, die in Audio-Antwort-Inhalten unterstützt werden.

Allowed Values:

• word - Zeitstempel pro Wort im Ausgangsaudio

ReasoningEffort

Begrenzt den Aufwand beim Schließen bei Denkmustern. Überprüfen Sie die Modelldokumentation auf unterstützte Werte für jedes Modell. Eine Reduzierung des Schlussarbeitsaufwands kann zu schnelleren Antworten und weniger Token beim Schließen in einer Antwort führen.

Allowed Values:

• none - Kein Überlegungsaufwand
• minimal - Minimaler Schlussaufwand
• low - Geringer Schlussarbeit – schnellere Antworten mit weniger Argumentation
• medium - Mittlerer Schlussaufwand – ausgewogen zwischen Geschwindigkeit und Denktiefe
• high - Hoher Schlussfolgerungsaufwand – gründlicheres Schließen, kann länger dauern
• xhigh - Extra hoher Schlussarbeit – maximale Denktiefe

Tool Configuration

Wir unterstützen zwei Arten von Tools: Function Calling und MCP-Tools, mit denen Sie sich mit einem MCP-Server verbinden können.

RealtimeTool

Werkzeugdefinition für das Aufrufen von Funktionen.

RealtimeToolChoice

Werkzeugauswahlstrategie.

Dies kann sein:

• "auto" - Lass das Modell wählen
• "none" - Benutze keine Werkzeuge
• "required" - Muss ein Werkzeug benutzen
• { "type": "function", "name": "function_name" } - Verwendung spezifischer Funktion

MCPTool

MCP-Werkzeugkonfiguration.

RealtimeConversationResponseItem

Dies ist ein Union-Typ, der einer der folgenden sein kann:

RealtimeConversationUserMessageItem

Benutzernachrichtenelement.

RealtimeConversationAssistantMessageItem

Assistentennachricht.

RealtimeConversationSystemMessageItem

Systemnachrichtenelement.

RealtimeConversationFunctionCallItem

Funktionsaufruf-Anfrage-Item.

RealtimeConversationFunctionCallOutputItem

Funktionsaufruf-Antwort-Item.

RealtimeConversationMCPListToolsItem

Antwortpunkt für MCP-Listenwerkzeuge.

RealtimeConversationMCPCallItem

MCP-Anrufantwort-Item.

RealtimeConversationMCPApprovalRequestItem

Antrag auf MCP-Genehmigung.

RealtimeItemStatus

Status der Gesprächsthemen.

Allowed Values:

• in_progress - Derzeit in der Bearbeitung
• completed - Erfolgreich abgeschlossen
• incomplete - Unvollständig (unterbrochen oder fehlgeschlagen)

RealtimeContentPart

Inhaltsteil in einer Nachricht.

RealtimeInputTextContentPart

Textteil.

RealtimeOutputTextContentPart

Textteil.

RealtimeInputAudioContentPart

Audio-Content-Teil.

RealtimeOutputAudioContentPart

Audio-Content-Teil.

Response Objects

RealtimeResponse

Antwortobjekt, das eine Modellinferenzantwort darstellt.

RealtimeResponseStatus

Reaktionsstatuswerte.

Allowed Values:

• in_progress - Es wird eine Antwort generiert
• completed - Antwort erfolgreich abgeschlossen
• canceled - Die Antwort wurde abgesagt
• incomplete - Antwort unvollständig (unterbrochen)
• failed - Antwort fehlschlug mit Fehler auf

RealtimeUsage

Statistiken zur Token-Verwendung.

TokenDetails

Detaillierte Aufschlüsselung der Token-Verwendung.

Error Handling

RealtimeErrorDetails

Fehlerinformationsobjekt.

RealtimeConversationRequestItem

Du verwendest das Objekt, RealtimeConversationRequestItem um über das Ereignis conversation.item.create ein neues Element in der Diskussion zu erstellen.

Dies ist ein Union-Typ, der einer der folgenden sein kann:

RealtimeSystemMessageItem

Ein Systemnachrichtenelement.

RealtimeUserMessageItem

Ein Benutzernachrichtenelement.

RealtimeAssistantMessageItem

Ein Assistenten-Nachrichteneintrag.

RealtimeFunctionCallItem

Ein Funktionsaufruf-Item.

RealtimeFunctionCallOutputItem

Ein Funktionsaufruf für das Ausgabeobjekt.

RealtimeMCPApprovalResponseItem

Eine MCP-Genehmigungsantwort.

RealtimeFunctionTool

Die Definition eines Funktionswerkzeugs, wie es vom Echtzeit-Endpunkt verwendet wird.

RealtimeItemStatus

Allowed Values:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

Das Objekt RealtimeResponseSession stellt eine Sitzung in der Echtzeit-API dar. Es wird in einigen Server-Events verwendet, wie zum Beispiel:

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Related Resources

• Probier den Voice Live Quickstart
• Probier den Voice Live Agents Quickstart
• Weitere Informationen zur Verwendung der Voice Live-API