Voice Live-API-Referenz 2025-10-01

Die Voice Live-API bietet eine bidirektionale Echtzeitkommunikation für Sprachfähige Anwendungen mithilfe von WebSocket-Verbindungen. Diese API unterstützt erweiterte Features wie Spracherkennung, Text-zu-Sprache-Synthese, Avatarstreaming, Animationsdaten und umfassende Audioverarbeitungsfunktionen.

Die API verwendet JSON-formatierte Ereignisse, die über WebSocket-Verbindungen gesendet werden, um Unterhaltungen, Audiodatenströme, Avatarinteraktionen und Echtzeitantworten zu verwalten. Ereignisse werden in Clientereignisse (gesendet von Client an Server) und Serverereignisse (vom Server an den Client gesendet) kategorisiert.

Key Features

• Echtzeit-Audioverarbeitung: Unterstützung für mehrere Audioformate, einschließlich PCM16 bei verschiedenen Sampleraten und G.711-Codecs
• Erweiterte Sprachoptionen: OpenAI-Stimmen, benutzerdefinierte Azure-Stimmen, Azure-Standardstimme und Azure-persönliche Stimmen
• Avatarintegration: WebRTC-basiertes Avatarstreaming mit Video, Animation und Blendshapes
• Intelligente Turnerkennung: Mehrere VAD-Optionen, einschließlich azure-semantischer VAD und serverseitiger Erkennung
• Audioverbesserung: Integrierte Rauschreduzierung und Echounterdrückung
• Funktionsaufrufe: Toolintegration für erweiterte Unterhaltungsfunktionen
• Flexible Sitzungsverwaltung: Konfigurierbare Ausgabemodalitäten, Anweisungen und Antwortparameter

Client Events

Die Voice Live-API unterstützt die folgenden Clientereignisse, 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, Erkennung, Tools und andere Sitzungsparameter zu ändern. Beachten Sie, dass eine Sitzung nach dem Initialisieren einer Sitzung mit einem bestimmten Modell 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 benutzerdefinierter Azure 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

Richten Sie eine Avatarverbindung ein, indem Sie das SDP-Angebot (Session Description Protocol) des Clients für die WebRTC-Medienverhandlung bereitstellen. Dieses Ereignis ist erforderlich, wenn Avatarfeatures verwendet werden.

Event Structure

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

Properties

input_audio_buffer.append

Fügen Sie Audiobytes an den Eingabeaudiopuffer an.

Event Structure

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

Properties

input_audio_buffer.commit

Übernehmen Sie den Eingabeaudiopuffer für die Verarbeitung.

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

Löschen Sie den Eingabeaudiopuffer.

Event Structure

{
  "type": "input_audio_buffer.clear"
}

Properties

conversation.item.create

Fügen Sie dem Unterhaltungskontext ein neues Element hinzu. Dazu können Nachrichten, Funktionsaufrufe und Funktionsaufrufantworten gehören. Elemente können an bestimmten Positionen im Unterhaltungsverlauf 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 für Audioinhalte

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

Beispiel mit Funktionsaufrufausgabe

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

Dient zum Abrufen eines bestimmten Elements aus dem Unterhaltungsverlauf. Dies ist nützlich, um verarbeitete Audiodaten nach der Rauschunterdrückung und VAD zu prüfen.

Event Structure

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

Properties

conversation.item.truncate

Kürzen Sie den Audioinhalt einer Assistentennachricht. Dies ist nützlich, um die Wiedergabe an einem bestimmten Punkt zu beenden und das Verständnis des Servers mit dem Clientstatus zu synchronisieren.

Event Structure

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

Properties

conversation.item.delete

Entfernen Sie ein Element aus dem Unterhaltungsverlauf.

Event Structure

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

Properties

response.create

Weisen Sie den Server an, eine Antwort über Modellleitungen zu erstellen. Dieses Ereignis kann antwortspezifische Konfiguration angeben, die die Sitzungsstandardwerte ü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 Toolauswahl

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

Abbrechen einer laufenden Antwort. Dadurch wird die Antwortgenerierung und die zugehörige Audioausgabe sofort beendet.

Event Structure

{
  "type": "response.cancel"
}

Properties

input_audio_buffer.append

Das Clientereignis input_audio_buffer.append wird verwendet, um Audiobytes an den Eingabeaudiopuffer anzufügen. Der Audiopuffer ist temporärer Speicher, in den Sie Daten schreiben und später committen können.

Im Server-VAD-Modus (Voice Activity Detection, Sprechaktivitätserkennung) wird der Audiopuffer verwendet, um die Sprache zu erkennen, und der Server entscheidet, wann ein Commit ausgeführt werden soll. Wenn die Server-VAD deaktiviert ist, kann der Client auswählen, wie viele Audiodaten in jedem Ereignis platziert werden sollen (maximal 15 MiB). Beispielsweise könnte die VAD durch das Streaming kleinerer Blöcke vom Client reaktionsfähiger sein.

Im Gegensatz zu den meisten Clientereignissen sendet der Server keine Bestätigungsantwort auf das Clientereignis input_audio_buffer.append.

Event structure

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

Properties

input_audio_buffer.clear

Das Clientereignis 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 Clientereignis input_audio_buffer.commit wird verwendet, um den Benutzereingabeaudiopuffer zu committen. Dadurch wird ein neues Benutzernachrichtenelement in der Unterhaltung erstellt. Die Audioinhalte werden transkribiert, wenn für die Sitzung input_audio_transcription konfiguriert wurde.

Im Server-VAD-Modus muss der Client dieses Ereignis nicht senden, da der Server den Audiopuffer automatisch committet. Ohne Server-VAD muss der Client den Audiopuffer committen, um ein Benutzernachrichtenelement zu erstellen. Dieses Clientereignis generiert einen Fehler, wenn der Eingabeaudiopuffer leer ist.

Beim Committen des Eingabeaudiopuffers wird vom Modell keine Antwort erstellt.

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 die folgenden 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 dem Herstellen einer Verbindung mit der 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 Clientereignis erfolgreich aktualisiert wird.

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

Gibt an, dass eine Avatar-WebRTC-Verbindung hergestellt wird. Dieses Ereignis wird als Reaktion auf ein session.avatar.connect Clientereignis gesendet.

Event Structure

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

Properties

conversation.item.created

Gesendet, wenn der Unterhaltung ein neues Element hinzugefügt wird, entweder über ein Clientereignis 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 Audioelement

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

Wird als Reaktion auf ein conversation.item.retrieve Clientereignis gesendet und stellt das angeforderte Unterhaltungselement bereit.

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 Serverereignis conversation.item.truncated wird zurückgegeben, wenn der Client ein früheres Audionachrichtenelement des Assistenten mit einem conversation.item.truncate-Ereignis abschneidet. Dieses Ereignis wird verwendet, um das Verständnis des Audios durch den Server mit der Wiedergabe des Clients zu synchronisieren.

Durch dieses Ereignis werden die Audioinhalte abgeschnitten und die serverseitige Texttranskription gelöscht, um sicherzustellen, dass kein Text im Kontext vorhanden ist, den Benutzende nicht kennen.

Event structure

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

Properties

conversation.item.deleted

Wird als Reaktion auf ein conversation.item.delete Clientereignis gesendet und bestätigt, dass das angegebene Element aus der Unterhaltung 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 Antwortsequenz.

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 Ausgabeelementen 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

Wird gesendet, wenn der Antwort während der Generierung ein neues Ausgabeelement 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 Ausgabeelement 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 Serverereignis response.content_part.added wird zurückgegeben, wenn während der Antwortgenerierung ein neues Inhaltsteil einem Nachrichtenelement des Assistenten 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 Serverereignis response.content_part.done wird zurückgegeben, wenn das Streamen eines Inhaltsteils in einem Nachrichtenelement des Assistenten abgeschlossen ist.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen wird, unvollständig ist 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

Streamen von Textinhalten aus dem Modell. Wird inkrementell gesendet, wenn das Modell Text generiert.

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 Textinhaltsgenerierung 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

Streamen von Audioinhalten aus dem Modell. Audio wird als base64-codierte 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 Generierung von Audioinhalten 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

Streamingtranskript 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 Serverereignis conversation.item.input_audio_transcription.completed ist das Ergebnis der Audiotranskription für die in den Audiopuffer geschriebene Sprache.

Die Transkription beginnt, wenn der Eingabeaudiopuffer vom Client oder vom Server (im server_vad-Modus) committet wird. Die Transkription wird asynchron mit der Antworterstellung ausgeführt, sodass dieses Ereignis vor oder nach den Antwortereignissen auftreten kann.

Realtime-API-Modelle akzeptieren Audio nativ, und somit ist die Eingabetranskription ein separater Prozess, der auf einem separaten Spracherkennungsmodell wie zum Beispiel whisper-1 ausgeführt wird. So kann das Transkript etwas von der Interpretation des Modells abweichen und sollte als grobe Anleitung 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 Audiotranskription für die Eingabe konfiguriert ist und eine Transkriptionsanforderung für eine Benutzernachricht ausgeführt wird. Dieses Ereignis stellt teilweise Transkriptionsergebnisse bereit, 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 Audiotranskription konfiguriert ist und ein Fehler bei einer Transkriptionsanforderung für eine Benutzernachricht auftrat. Dieses Ereignis ist von anderen error-Ereignissen getrennt, sodass der Client 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 Serverereignis response.animation_blendshapes.delta wird zurückgegeben, wenn das Modell Animationsmischungsdaten als Teil einer Antwort generiert. Dieses Ereignis stellt daten inkrementelle Blendshapes bereit, sobald es verfügbar wird.

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 das Generieren von Animationsmischungsdaten als Teil einer Antwort abgeschlossen 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 Audiozeitstempeldaten als Teil einer Antwort generiert. Dieses Ereignis stellt inkrementelle Zeitstempeldaten für die Ausgabeaudio- und Textausrichtung bereit, sobald es verfügbar wird.

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 Audiozeitstempelgenerierung 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 Animationsdaten als Teil einer Antwort generiert. Dieses Ereignis stellt inkrementelle Viseme-Daten bereit, sobald es verfügbar wird.

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 das Generieren von Animationsdaten 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. Dabei kann es sich um ein Client- oder ein Serverproblem handeln. Die meisten Fehler können behoben werden, und die Sitzung bleibt geöffnet.

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 Unterhaltungsfluss nicht unterbricht. Warnungen sind Informationsinformationen, und die Sitzung wird normal fortgesetzt.

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 Eingabeaudiopuffer mit einem input_audio_buffer.clear-Ereignis löscht.

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

input_audio_buffer.committed

Das Serverereignis input_audio_buffer.committed wird zurückgegeben, wenn ein Eingabeaudiopuffer vom Client oder automatisch im Server-VAD-Modus committet wird. Die item_id-Eigenschaft ist die ID des erstellten Benutzernachrichtenelements. Daher wird auch ein conversation.item.created-Ereignis an den Client 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 im Audiopuffer Sprache erkannt wird. Dieses Ereignis kann jederzeit auftreten, wenn dem Puffer Audio hinzugefügt wird (es sei denn, es wurde bereits Sprache erkannt).

Der Client sollte erwarten, dass ein input_audio_buffer.speech_stopped-Ereignis empfangen wird, wenn die Sprachausgabe beendet wird. Die item_id-Eigenschaft ist die ID des Benutzernachrichtenelements, das beim Beenden der Sprache erstellt wird. Die item_id ist auch im input_audio_buffer.speech_stopped-Ereignis enthalten, es sei denn, der Client committet 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 wurde.

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 am Anfang einer Antwort ausgegeben, um die aktualisierten Ratengrenzwerte anzugeben.

Wenn eine Antwort erstellt wird, sind einige Token für die Ausgabetoken reserviert. Die hier gezeigten Ratengrenzwerte spiegeln diese Reservierung wider, die dann nach Abschluss der Antwort entsprechend angepasst wird.

Event structure

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

Properties

response.audio.delta

Das Serverereignis response.audio.delta wird zurückgegeben, wenn die vom Modell generierten Audioinhalte aktualisiert werden.

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 die vom Modell generierten Audioinhalte fertig sind.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen wird, unvollständig ist 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 vom Modell generierte 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 das Streaming der vom Modell generierten Transkription der Audioausgabe abgeschlossen ist.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen wird, unvollständig ist 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 Serverereignis response.function_call_arguments.delta wird zurückgegeben, wenn die vom Modell generierten Funktionsaufrufargumente 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 das Streaming der vom Modell generierten Funktionsaufrufargumente abgeschlossen ist.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen wird, unvollständig ist 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 Serverereignis mcp_list_tools.in_progress wird zurückgegeben, wenn der Dienst beginnt, verfügbare Tools 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 Serverereignis mcp_list_tools.completed wird zurückgegeben, wenn der Dienst die Auflistung der verfügbaren Tools von einem Mcp-Server abgeschlossen hat.

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 keine verfügbaren Tools von einem Mcp-Server 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-Toolaufrufargumente 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 das vom Modell generierte Mcp-Toolaufrufargumente streamingt werden.

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-Toolaufruf die Verarbeitung startet.

Event structure

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

Properties

response.mcp_call.completed

Das Serverereignis response.mcp_call.completed wird zurückgegeben, wenn ein MCP-Toolaufruf erfolgreich abgeschlossen wird.

Event structure

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

Properties

response.mcp_call.failed

Das Serverereignis response.mcp_call.failed wird zurückgegeben, wenn ein MCP-Toolaufruf fehlschlägt.

Event structure

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

Properties

response.output_item.added

Das Serverereignis 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 Serverereignis response.output_item.done wird zurückgegeben, wenn das Streamen eines Elements abgeschlossen ist.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen wird, unvollständig ist 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 vom Modell generierte Text aktualisiert wird. Der Text entspricht dem Inhaltsteil text eines Nachrichtenelements des Assistenten.

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 Serverereignis response.text.done wird zurückgegeben, wenn das Streamen des vom Modell generierten Texts abgeschlossen ist. Der Text entspricht dem Inhaltsteil text eines Nachrichtenelements des Assistenten.

Dieses Ereignis wird auch zurückgegeben, wenn eine Antwort unterbrochen wird, unvollständig ist 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

Basisaudioformat, das für Eingabeaudio verwendet wird.

Allowed Values:

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

RealtimeOutputAudioFormat

Audioformat, das für die Ausgabe von Audio mit bestimmten Samplingraten verwendet wird.

Allowed Values:

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

RealtimeAudioInputTranscriptionSettings

Konfiguration für die Eingabeaudiotranskription.

RealtimeInputAudioNoiseReductionSettings

Dies kann folgendes sein:

• Ein RealtimeOpenAINoiseReduction-Objekt
• Ein RealtimeAzureDeepNoiseSuppression-Objekt

RealtimeOpenAINoiseReduction

OpenAI-Rauschreduzierungskonfiguration mit expliziten Typfeld, nur für gpt-realtime und gpt-realtime-mini Modelle verfügbar.

RealtimeAzureDeepNoiseSuppression

Konfiguration zur Rauschunterdrückung bei Audioeingang.

RealtimeInputAudioEchoCancellationSettings

Echounterdrückungskonfiguration für die serverseitige Audioverarbeitung.

Voice Configuration

RealtimeVoice

Union aller unterstützten Sprachkonfigurationen.

Dies kann folgendes sein:

• Ein RealtimeOpenAIVoice-Objekt
• Ein RealtimeAzureVoice-Objekt

RealtimeOpenAIVoice

OpenAI-Sprachkonfiguration mit expliziten Typfeldern.

RealtimeAzureVoice

Basis für Azure-VoIP-Konfigurationen. Dies ist eine diskriminierte Vereinigung mit verschiedenen Typen:

RealtimeAzureStandardVoice

Azure-Standard-VoIP-Konfiguration.

RealtimeAzureCustomVoice

Benutzerdefinierte Azure-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 die Turnerkennung. Dies ist eine diskriminierte Vereinigung, die mehrere VAD-Typen unterstützt.

RealtimeServerVAD

Basis-VAD-basierte Dreherkennung.

RealtimeOpenAISemanticVAD

OpenAI-Semantik-VAD-Konfiguration, die ein Modell verwendet, um zu bestimmen, wann der Benutzer die Rede abgeschlossen hat. Nur für gpt-realtime und gpt-realtime-mini Modelle verfügbar.

RealtimeAzureSemanticVAD

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

RealtimeAzureSemanticVADMultilingual

Azure semantic VAD (Standardvariante).

RealtimeEOUDetection

Azure End-of-Utterance (EOU) könnte angeben, wann der Endbenutzer nicht mehr spricht, während natürliche Pausen möglich sind. Die Erkennung der Beendigung von Äußerungen kann vorzeitige Signale zu Sprecherwechseln erheblich reduzieren, ohne dass eine für die Benutzenden erkennbare Latenz auftritt.

Avatar Configuration

RealtimeAvatarConfig

Konfiguration für Avatarstreaming und -verhalten.

RealtimeIceServer

ICE-Serverkonfiguration für WebRTC-Verbindungsverhandlung.

RealtimeVideoParams

Videostreamingparameter für Avatar.

RealtimeVideoCrop

Definition des Videozuschneiderechtecks.

RealtimeVideoResolution

Spezifikation der Videoauflösung.

RealtimeAvatarScene

Konfiguration für Zoomfaktor, Position, Drehungs- und Bewegungsamplitude des Avatars im Videoframe.

Animation Configuration

RealtimeAnimation

Konfiguration für Animationsausgaben, einschließlich Blendformen und Visemes.

RealtimeAnimationOutputType

Arten von Animationsdaten, die ausgegeben werden sollen.

Allowed Values:

• blendshapes - Gesichts-Blendshapes-Daten
• viseme_id - Viseme-Bezeichnerdaten

Session Configuration

RealtimeRequestSession

Sitzungskonfigurationsobjekt, das in session.update Ereignissen verwendet wird.

RealtimeModality

Unterstützte Sitzungsausgabemodalitäten.

Allowed Values:

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

RealtimeAudioTimestampType

Ausgabezeitstempeltypen, die in Audioantwortinhalten unterstützt werden.

Allowed Values:

• word - Zeitstempel pro Wort im Ausgabeaudio

ReasoningEffort

Schränkt den Begründungsaufwand für Begründungsmodelle ein. Überprüfen Sie die Modelldokumentation auf unterstützte Werte für jedes Modell. Das Reduzieren von Begründungen kann zu schnelleren Antworten und weniger Token führen, die bei der Begründung in einer Antwort verwendet werden.

Allowed Values:

• none - Keine Begründungsaufwand
• minimal - Minimaler Grundaufwand
• low - Geringer Grundaufwand - schnellere Antworten mit weniger Gründen
• medium - Mittlere Begründungsanstrengung - ausgewogen zwischen Geschwindigkeit und Begründungstiefe
• high - Hoher Grundaufwand - gründlichere Begründung, kann länger dauern
• xhigh - Extra hoher Grundaufwand - maximale Grundtiefe

Tool Configuration

Wir unterstützen zwei Arten von Tools: Funktionsaufrufe und MCP-Tools, mit denen Sie eine Verbindung mit einem Mcp-Server herstellen können.

RealtimeTool

Tooldefinition für Funktionsaufrufe.

RealtimeToolChoice

Toolauswahlstrategie.

Dies kann folgendes sein:

• "auto" - Lassen Sie das Modell auswählen
• "none" - Verwenden Sie keine Tools
• "required" - Muss ein Tool verwenden
• { "type": "function", "name": "function_name" } - Bestimmte Funktion verwenden

MCPTool

MCP-Toolkonfiguration.

RealtimeConversationResponseItem

Dies ist ein Union-Typ, der eine der folgenden Sein kann:

RealtimeConversationUserMessageItem

Benutzernachrichtenelement.

RealtimeConversationAssistantMessageItem

Nachrichtenelement des Assistenten.

RealtimeConversationSystemMessageItem

Systemnachrichtenelement.

RealtimeConversationFunctionCallItem

Anforderungselement für Funktionsaufrufe.

RealtimeConversationFunctionCallOutputItem

Antwortelement für Funktionsaufrufe.

RealtimeConversationMCPListToolsItem

Antwortelement der MCP-Listentools.

RealtimeConversationMCPCallItem

MCP-Anrufantwortelement.

RealtimeConversationMCPApprovalRequestItem

MCP-Genehmigungsanforderungselement.

RealtimeItemStatus

Status von Unterhaltungselementen.

Allowed Values:

• in_progress - Wird zurzeit verarbeitet
• completed - Erfolgreich abgeschlossen
• incomplete - Unvollständig (unterbrochen oder fehlgeschlagen)

RealtimeContentPart

Inhaltsteil innerhalb einer Nachricht.

RealtimeInputTextContentPart

Textinhaltsteil.

RealtimeOutputTextContentPart

Textinhaltsteil.

RealtimeInputAudioContentPart

Audioinhaltsteil.

RealtimeOutputAudioContentPart

Audioinhaltsteil.

Response Objects

RealtimeResponse

Response-Objekt, das eine Modell-Ableitungsantwort darstellt.

RealtimeResponseStatus

Antwortstatuswerte.

Allowed Values:

• in_progress - Die Antwort wird generiert.
• completed - Antwort erfolgreich abgeschlossen
• cancelled - Antwort wurde abgebrochen
• incomplete - Antwort unvollständig (unterbrochen)
• failed – Fehler bei der Antwort

RealtimeUsage

Tokenverwendungsstatistiken.

TokenDetails

Detaillierte Aufschlüsselung der Tokenverwendung.

Error Handling

RealtimeErrorDetails

Fehlerinformationsobjekt.

RealtimeConversationRequestItem

Sie verwenden das Objekt RealtimeConversationRequestItem, um über das Element conversation.item.create ein neues Element in der Unterhaltung zu erstellen.

Dies ist ein Union-Typ, der eine der folgenden Sein kann:

RealtimeSystemMessageItem

Ein Systemnachrichtenelement.

RealtimeUserMessageItem

Ein Benutzernachrichtenelement.

RealtimeAssistantMessageItem

Ein Nachrichtenelement des Assistenten.

RealtimeFunctionCallItem

Ein Funktionsaufrufelement.

RealtimeFunctionCallOutputItem

Ein Funktionsaufrufausgabeelement.

RealtimeMCPApprovalResponseItem

Ein MCP-Genehmigungsantwortelement.

RealtimeFunctionTool

Die Definition eines Funktionstools, wie es vom Echtzeitendpunkt 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 der Serverereignisse verwendet, z. B.:

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Related Resources

• Probieren Sie den Voice Live-Schnellstart aus
• Testen der Voice Live-Agents – Schnellstart
• Weitere Informationen zur Verwendung der Voice Live-API