Informations de référence sur l’API Voice Live 2025-10-01

L’API Voice Live fournit une communication bidirectionnelle en temps réel pour les applications compatibles vocales à l’aide de connexions WebSocket. Cette API prend en charge les fonctionnalités avancées, notamment la reconnaissance vocale, la synthèse vocale, la diffusion d’avatars, les données d’animation et les fonctionnalités complètes de traitement audio.

L’API utilise des événements au format JSON envoyés via des connexions WebSocket pour gérer les conversations, les flux audio, les interactions d’avatar et les réponses en temps réel. Les événements sont classés en événements clients (envoyés du client au serveur) et des événements serveur (envoyés du serveur au client).

Key Features

• Traitement audio en temps réel : prise en charge de plusieurs formats audio, y compris PCM16 à différents taux d’échantillonnage et codecs G.711
• Options vocales avancées : voix OpenAI, voix personnalisées Azure, voix standard Azure et voix personnelles Azure
• Intégration d’avatar : diffusion en continu d’avatars webRTC avec vidéo, animation et blendshapes
• Détection intelligente de tour : plusieurs options VAD, notamment la détection sémantique Azure et la détection côté serveur
• Amélioration audio : réduction du bruit intégrée et annulation d’écho
• Appel de fonction : Intégration d’outils pour des fonctionnalités conversationnelles améliorées
• Gestion de session flexible : modalités de sortie configurables, instructions et paramètres de réponse

Client Events

L’API Voice Live prend en charge les événements clients suivants qui peuvent être envoyés du client au serveur :

session.update

Mettez à jour la configuration de la session. Cet événement peut être envoyé à tout moment pour modifier des paramètres tels que la voix, les modalités de sortie, la détection de tour, les outils et d’autres paramètres de session. Notez qu’une fois qu’une session est initialisée avec un modèle particulier, elle ne peut pas être modifiée en un autre modèle.

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

Exemple avec 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

Établissez une connexion d’avatar en fournissant l’offre SDP (Protocole de description de session) du client pour la négociation multimédia WebRTC. Cet événement est requis lors de l’utilisation des fonctionnalités d’avatar.

Event Structure

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

Properties

input_audio_buffer.append

Ajoutez des octets audio à la mémoire tampon audio d’entrée.

Event Structure

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

Properties

input_audio_buffer.commit

Validez la mémoire tampon audio d’entrée pour le traitement.

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

Effacez la mémoire tampon audio d’entrée.

Event Structure

{
  "type": "input_audio_buffer.clear"
}

Properties

conversation.item.create

Ajoutez un nouvel élément au contexte de conversation. Cela peut inclure des messages, des appels de fonction et des réponses d’appel de fonction. Les éléments peuvent être insérés à des positions spécifiques dans l’historique des conversations.

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

Exemple avec du contenu audio

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

Exemple avec la sortie de l’appel de fonction

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

Exemple avec la réponse d’approbation MCP

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

conversation.item.retrieve

Récupérez un élément spécifique à partir de l’historique des conversations. Cela est utile pour inspecter l’audio traité après l’annulation du bruit et VAD.

Event Structure

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

Properties

conversation.item.truncate

Tronquer le contenu audio d’un message assistant. Cela est utile pour arrêter la lecture à un point spécifique et synchroniser la compréhension du serveur avec l’état du client.

Event Structure

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

Properties

conversation.item.delete

Supprimez un élément de l’historique des conversations.

Event Structure

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

Properties

response.create

Demandez au serveur de créer une réponse via l’inférence du modèle. Cet événement peut spécifier une configuration spécifique à la réponse qui remplace les valeurs par défaut de session.

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

Exemple avec le choix de l’outil

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

Exemple avec 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

Annulez une réponse en cours. Cela arrête immédiatement la génération de réponse et la sortie audio associée.

Event Structure

{
  "type": "response.cancel"
}

Properties

input_audio_buffer.append

L’événement client input_audio_buffer.append est utilisé pour ajouter des octets audio à la mémoire tampon audio d’entrée. La mémoire tampon audio est un stockage temporaire que vous pouvez écrire dans et valider ultérieurement.

En mode VAD du serveur (détection d’activité vocale), la mémoire tampon audio est utilisée pour détecter la voix et le serveur décide de la validation. Quand le VAD serveur est désactivé, le client peut choisir la quantité d’audio à placer dans chaque événement, jusqu’à un maximum de 15 Mio. Par exemple, la diffusion en continu de blocs plus petits depuis le client peut permettre au VAD d’être plus réactif.

Contrairement à la plupart des événements clients, le serveur n’envoie pas de réponse de confirmation à l’événement client input_audio_buffer.append.

Event structure

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

Properties

input_audio_buffer.clear

L’événement client input_audio_buffer.clear est utilisé pour effacer les octets audio dans la mémoire tampon.

Le serveur répond avec un événement input_audio_buffer.cleared.

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

input_audio_buffer.commit

L’événement client input_audio_buffer.commit est utilisé pour valider la mémoire tampon audio d’entrée utilisateur, qui crée un élément de message utilisateur dans la conversation. L’audio est transcrit si input_audio_transcription est configuré pour la session.

Lorsqu’il est en mode VAD du serveur, le client n’a pas besoin d’envoyer cet événement, le serveur valide automatiquement la mémoire tampon audio. Sans VAD serveur, le client doit valider la mémoire tampon audio pour créer un élément de message utilisateur. Cet événement client génère une erreur si la mémoire tampon audio d’entrée est vide.

La validation de la mémoire tampon audio d’entrée ne crée pas de réponse à partir du modèle.

Le serveur répond avec un événement input_audio_buffer.committed.

Event structure

{
  "type": "input_audio_buffer.commit"
}

Properties

Server Events

L’API Voice Live envoie les événements de serveur suivants pour communiquer l’état, les réponses et les données au client :

session.created

Envoyé lorsqu’une nouvelle session est correctement établie. Il s’agit du premier événement reçu après la connexion à l’API.

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

Envoyé lorsque la configuration de session est correctement mise à jour en réponse à un session.update événement client.

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

Indique qu’une connexion WebRTC d’avatar est établie. Cet événement est envoyé en réponse à un session.avatar.connect événement client.

Event Structure

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

Properties

conversation.item.created

Envoyé lorsqu’un nouvel élément est ajouté à la conversation, via un événement client conversation.item.create ou automatiquement pendant la génération de réponse.

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

Exemple avec l’élément 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

Envoyé en réponse à un conversation.item.retrieve événement client, en fournissant l’élément de conversation demandé.

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

L’événement serveur conversation.item.truncated est retourné quand le client tronque un élément de message audio antérieur de l’assistant avec un événement conversation.item.truncate. Cet événement est utilisé pour synchroniser la compréhension du serveur de l’audio avec la lecture du client.

Cet événement tronque l’audio et supprime la transcription en texte du côté serveur pour faire en sorte qu’il n’y ait pas de texte dans le contexte dont l’utilisateur ne sait rien.

Event structure

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

Properties

conversation.item.deleted

Envoyé en réponse à un conversation.item.delete événement client, confirmant que l’élément spécifié a été supprimé de la conversation.

Event Structure

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

Properties

response.created

Envoyé lorsqu’une nouvelle génération de réponse commence. Il s’agit du premier événement d’une séquence de réponse.

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

Envoyé lorsque la génération de réponse est terminée. Cet événement contient la réponse finale avec tous les éléments de sortie et les statistiques d’utilisation.

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

Envoyé lorsqu’un nouvel élément de sortie est ajouté à la réponse pendant la génération.

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

Envoyé lorsqu’un élément de sortie est terminé.

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

L’événement serveur response.content_part.added est retourné quand une nouvelle partie de contenu est ajoutée à un élément de message de l’assistant pendant la génération de la réponse.

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

L’événement serveur response.content_part.done est retourné quand une partie de contenu a fait l’objet d’une diffusion en continu dans un élément de message de l’assistant.

Cet événement est également retourné quand une réponse est interrompue, incomplète ou annulée.

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

Diffusion en continu du contenu texte à partir du modèle. Envoyé de façon incrémentielle à mesure que le modèle génère du texte.

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

Envoyé lorsque la génération de contenu de texte est terminée.

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

Diffusion en continu du contenu audio à partir du modèle. L’audio est fourni en tant que données encodées en base64.

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

Envoyé lorsque la génération de contenu audio est terminée.

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

Transcription de streaming du contenu audio généré.

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

Envoyé lorsque la génération de transcription audio est terminée.

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

L’événement serveur conversation.item.input_audio_transcription.completed est le résultat de la transcription audio pour le message écrit dans la mémoire tampon audio.

La transcription commence lorsque la mémoire tampon audio d’entrée est validée par le client ou le serveur (en mode server_vad). La transcription s’exécute de façon asynchrone avec la création de la réponse, ce qui permet à cet événement de se présenter avant ou après les événements de réponse.

Les modèles d’API en temps réel acceptent l’audio en mode natif, et par conséquent, la transcription d’entrée est un processus distinct exécuté sur un modèle de reconnaissance vocale distinct tel que whisper-1. Ainsi, la transcription peut différer un peu de l’interprétation du modèle et doit être traitée comme un guide brut.

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

L’événement serveur conversation.item.input_audio_transcription.delta est retourné lorsque la transcription audio d’entrée est configurée et qu’une demande de transcription pour un message utilisateur est en cours. Cet événement fournit des résultats de transcription partielles dès qu’ils deviennent disponibles.

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

L’événement serveur conversation.item.input_audio_transcription.failed est retourné quand la transcription audio de l’entrée est configurée et qu’une demande de transcription pour un message utilisateur a échoué. Cet événement est distinct des autres événements error, pour que le client puisse identifier l’élément associé.

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

L’événement de serveur response.animation_blendshapes.delta est retourné lorsque le modèle génère des données blendshapes d’animation dans le cadre d’une réponse. Cet événement fournit des données blendshapes incrémentielles au fur et à mesure qu’il devient disponible.

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

L’événement de serveur response.animation_blendshapes.done est retourné lorsque le modèle a terminé la génération de données blendshapes d’animation dans le cadre d’une réponse.

Event structure

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

Properties

response.audio_timestamp.delta

L’événement serveur response.audio_timestamp.delta est retourné lorsque le modèle génère des données d’horodatage audio dans le cadre d’une réponse. Cet événement fournit des données d’horodatage incrémentielles pour l’alignement audio et texte de sortie au fur et à mesure qu’il devient disponible.

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

Envoyé lorsque la génération d’horodatage audio est terminée.

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

L’événement de serveur response.animation_viseme.delta est retourné lorsque le modèle génère des données de viseme d’animation dans le cadre d’une réponse. Cet événement fournit des données de viseme incrémentielles au fur et à mesure qu’il devient disponible.

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

L’événement de serveur response.animation_viseme.done est retourné lorsque le modèle a fini de générer des données de viseme d’animation dans le cadre d’une réponse.

Event Structure

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

Properties

error

L’événement serveur error est retourné quand une erreur se produit, qui peut être un problème client ou un problème serveur. La plupart des erreurs sont récupérables et la session reste ouverte.

Event structure

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

Properties

Error properties

warning

L’événement serveur warning est retourné lorsqu’un avertissement se produit qui n’interrompt pas le flux de conversation. Les avertissements sont informationnels et la session se poursuit normalement.

Event structure

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

Properties

Warning properties

input_audio_buffer.cleared

L’événement serveur input_audio_buffer.cleared est retourné quand le client efface la mémoire tampon audio d’entrée avec un événement input_audio_buffer.clear.

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

input_audio_buffer.committed

L’événement serveur input_audio_buffer.committed est retourné quand une mémoire tampon audio d’entrée est validée par le client ou automatiquement en mode VAD serveur. La propriété item_id est l’ID de l’élément de message utilisateur créé. Par conséquent, un conversation.item.created événement est également envoyé au client.

Event structure

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

Properties

input_audio_buffer.speech_started

L’événement serveur input_audio_buffer.speech_started est retourné en mode server_vad quand un message est détecté dans la mémoire tampon audio. Cet événement peut se produire chaque fois que l’audio est ajouté à la mémoire tampon (sauf si la voix est déjà détectée).

Le client doit s’attendre à recevoir un événement input_audio_buffer.speech_stopped lorsque la reconnaissance vocale s’arrête. La propriété item_id est l’ID de l’élément de message utilisateur créé quand le message s’arrête. Le item_id est également inclus dans l’événement input_audio_buffer.speech_stopped, sauf si le client valide manuellement la mémoire tampon audio lors de l’activation de VAD.

Event structure

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

Properties

input_audio_buffer.speech_stopped

L’événement serveur input_audio_buffer.speech_stopped est retourné en mode server_vad quand le serveur détecte la fin de du message dans la mémoire tampon audio.

Le serveur envoie également un événement conversation.item.created avec l’élément de message utilisateur créé à partir de la mémoire tampon audio.

Event structure

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

Properties

rate_limits.updated

L’événement serveur rate_limits.updated est émis au début d’une réponse pour indiquer les limites de débit mises à jour.

Quand une réponse est créée, certains jetons sont réservés aux jetons de sortie. Les limites de débit montrées ici reflètent cette réservation, qui est ensuite ajustée en conséquence une fois la réponse terminée.

Event structure

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

Properties

response.audio.delta

L’événement serveur response.audio.delta est retourné quand l’audio généré par le modèle est mis à jour.

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

L’événement serveur response.audio.done est retourné quand l’audio généré par le modèle est produit.

Cet événement est également retourné quand une réponse est interrompue, incomplète ou annulée.

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

L’événement serveur response.audio_transcript.delta est retourné quand la transcription générée par le modèle de la sortie audio est mise à jour.

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

L’événement serveur response.audio_transcript.done est retourné quand la transcription générée par le modèle de la sortie audio a fait l’objet d’une diffusion en continu.

Cet événement est également retourné quand une réponse est interrompue, incomplète ou annulée.

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

L’événement serveur response.function_call_arguments.delta est retourné quand les arguments d’appel de fonction générés par le modèle sont mis à jour.

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

L’événement serveur response.function_call_arguments.done est retourné quand les arguments d’appel de fonction générés par le modèle ont fait l’objet d’une diffusion en continu.

Cet événement est également retourné quand une réponse est interrompue, incomplète ou annulée.

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

L’événement de serveur mcp_list_tools.in_progress est retourné lorsque le service commence à répertorier les outils disponibles à partir d’un serveur mcp.

Event structure

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

Properties

mcp_list_tools.completed

L’événement de serveur mcp_list_tools.completed est retourné lorsque le service termine la liste des outils disponibles à partir d’un serveur mcp.

Event structure

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

Properties

mcp_list_tools.failed

L’événement de serveur mcp_list_tools.failed est retourné lorsque le service ne parvient pas à répertorier les outils disponibles à partir d’un serveur mcp.

Event structure

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

Properties

response.mcp_call_arguments.delta

L’événement de serveur response.mcp_call_arguments.delta est retourné lorsque les arguments d’appel de l’outil mcp générés par le modèle sont mis à jour.

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

L’événement de serveur response.mcp_call_arguments.done est retourné lorsque les arguments d’appel de l’outil mcp générés par le modèle sont terminés en streaming.

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

L’événement de serveur response.mcp_call.in_progress est retourné lorsqu’un appel d’outil MCP démarre le traitement.

Event structure

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

Properties

response.mcp_call.completed

L’événement de serveur response.mcp_call.completed est retourné lorsqu’un appel d’outil MCP se termine correctement.

Event structure

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

Properties

response.mcp_call.failed

L’événement de serveur response.mcp_call.failed est retourné lorsqu’un appel d’outil MCP échoue.

Event structure

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

Properties

response.output_item.added

L’événement serveur response.output_item.added est retourné quand un nouvel élément est créé lors de la génération de la réponse.

Event structure

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

Properties

response.output_item.done

L’événement serveur response.output_item.done est retourné quand un élément a fait l’objet d’une diffusion en continu.

Cet événement est également retourné quand une réponse est interrompue, incomplète ou annulée.

Event structure

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

Properties

response.text.delta

L’événement serveur response.text.delta est retourné quand le texte généré par le modèle est mis à jour. Le texte correspond à la partie de contenu text d’un élément de message de l’assistant.

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

L’événement serveur response.text.done est retourné quand le texte généré par le modèle a fait l’objet d’une diffusion en continu. Le texte correspond à la partie de contenu text d’un élément de message de l’assistant.

Cet événement est également retourné quand une réponse est interrompue, incomplète ou annulée.

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

Format audio de base utilisé pour l’audio d’entrée.

Allowed Values:

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

RealtimeOutputAudioFormat

Format audio utilisé pour l’audio de sortie avec des taux d’échantillonnage spécifiques.

Allowed Values:

• pcm16 - Format audio PCM 16 bits au taux d’échantillonnage par défaut (24 kHz)
• pcm16_8000hz - Format audio PCM 16 bits au taux d’échantillonnage 8kHz
• pcm16_16000hz - Format audio PCM 16 bits au taux d’échantillonnage 16kHz
• g711_ulaw - G.711 μ-law (mu-law) format audio au taux d’échantillonnage 8kHz
• g711_alaw - Format audio de loi A G.711 au taux d’échantillonnage de 8 kHz

RealtimeAudioInputTranscriptionSettings

Configuration de la transcription audio d’entrée.

RealtimeInputAudioNoiseReductionSettings

Il peut s’agir des suivants :

• Objet RealtimeOpenAINoiseReduction
• Un objet RealtimeAzureDeepNoiseSuppression

RealtimeOpenAINoiseReduction

Configuration de la réduction du bruit OpenAI avec un champ de type explicite, disponible uniquement pour et pour gpt-realtime les gpt-realtime-mini modèles.

RealtimeAzureDeepNoiseSuppression

Configuration de la réduction du bruit audio d’entrée.

RealtimeInputAudioEchoCancellationSettings

Configuration de l’annulation d’écho pour le traitement audio côté serveur.

Voice Configuration

RealtimeVoice

Union de toutes les configurations vocales prises en charge.

Il peut s’agir des suivants :

• Objet RealtimeOpenAIVoice
• Objet RealtimeAzureVoice

RealtimeOpenAIVoice

Configuration vocale OpenAI avec champ de type explicite.

RealtimeAzureVoice

Base pour les configurations vocales Azure. Il s’agit d’une union discriminatoire avec différents types :

RealtimeAzureStandardVoice

Configuration vocale standard Azure.

RealtimeAzureCustomVoice

Configuration vocale personnalisée Azure (par défaut pour les voix personnalisées).

Example:

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

RealtimeAzurePersonalVoice

Configuration vocale personnelle Azure.

Turn Detection

RealtimeTurnDetection

Configuration pour la détection de virage. Il s’agit d’une union discriminatoire qui prend en charge plusieurs types VAD.

RealtimeServerVAD

Détection de tour basée sur VAD de base.

RealtimeOpenAISemanticVAD

Configuration sémantique VAD OpenAI qui utilise un modèle pour déterminer quand l’utilisateur a fini de parler. Disponible uniquement pour et gpt-realtime les gpt-realtime-mini modèles.

RealtimeAzureSemanticVAD

VAD sémantique Azure, qui détermine quand l’utilisateur démarre et parle à l’aide d’un modèle de reconnaissance vocale sémantique, fournissant une détection plus robuste dans des environnements bruyants.

RealtimeAzureSemanticVADMultilingual

VAD sémantique Azure (variante par défaut).

RealtimeEOUDetection

Azure End-of-Utterance (EOU) peut indiquer quand l’utilisateur final a cessé de parler tout en autorisant des pauses naturelles. La détection de la fin d'énoncé peut réduire considérablement les signaux de fin de tour prématurés sans ajouter de latence perceptible par l'utilisateur.

Avatar Configuration

RealtimeAvatarConfig

Configuration pour le streaming et le comportement des avatars.

RealtimeIceServer

Configuration du serveur ICE pour la négociation de connexion WebRTC.

RealtimeVideoParams

Paramètres de streaming vidéo pour avatar.

RealtimeVideoCrop

Définition du rectangle de rognage vidéo.

RealtimeVideoResolution

Spécification de la résolution vidéo.

RealtimeAvatarScene

Configuration du niveau de zoom, de la position, de la rotation et de l’amplitude de mouvement de l’avatar dans l’image vidéo.

Animation Configuration

RealtimeAnimation

Configuration des sorties d’animation, notamment blendshapes et visemes.

RealtimeAnimationOutputType

Types de données d’animation à générer.

Allowed Values:

• blendshapes - Données blendshapes faciales
• viseme_id - Données d’identificateur Viseme

Session Configuration

RealtimeRequestSession

Objet de configuration de session utilisé dans session.update les événements.

RealtimeModality

Modalités de sortie de session prises en charge.

Allowed Values:

• text - Sortie de texte
• audio - Sortie audio
• animation - Sortie d’animation
• avatar - Sortie vidéo avatar

RealtimeAudioTimestampType

Types d’horodatages de sortie pris en charge dans le contenu de réponse audio.

Allowed Values:

• word - Horodatages par mot dans l’audio de sortie

ReasoningEffort

Limite l’effort de raisonnement pour les modèles de raisonnement. Consultez la documentation du modèle pour connaître les valeurs prises en charge pour chaque modèle. La réduction de l’effort de raisonnement peut entraîner des réponses plus rapides et l’utilisation d’un nombre inférieur de jetons sur le raisonnement dans une réponse.

Allowed Values:

• none - Aucun effort de raisonnement
• minimal - Effort de raisonnement minimal
• low - Effort de raisonnement faible - réponses plus rapides avec moins de raisonnement
• medium - Effort de raisonnement moyen - équilibré entre la vitesse et la profondeur du raisonnement
• high - Effort de raisonnement élevé - raisonnement plus approfondi, peut prendre plus de temps
• xhigh - Effort de raisonnement très élevé - profondeur de raisonnement maximale

Tool Configuration

Nous prenons en charge deux types d’outils : les appels de fonction et les outils MCP qui vous permettent de vous connecter à un serveur mcp.

RealtimeTool

Définition de l’outil pour l’appel de fonction.

RealtimeToolChoice

Stratégie de sélection d’outils.

Il peut s’agir des suivants :

• "auto" - Laisser le modèle choisir
• "none" - N’utilisez pas d’outils
• "required" - Doit utiliser un outil
• { "type": "function", "name": "function_name" } - Utiliser une fonction spécifique

MCPTool

Configuration de l’outil MCP.

RealtimeConversationResponseItem

Il s’agit d’un type d’union qui peut être l’un des éléments suivants :

RealtimeConversationUserMessageItem

Élément de message utilisateur.

RealtimeConversationAssistantMessageItem

Élément de message assistant.

RealtimeConversationSystemMessageItem

Élément de message système.

RealtimeConversationFunctionCallItem

Élément de demande d’appel de fonction.

RealtimeConversationFunctionCallOutputItem

Élément de réponse d’appel de fonction.

RealtimeConversationMCPListToolsItem

Élément de réponse des outils de liste MCP.

RealtimeConversationMCPCallItem

Élément de réponse d’appel MCP.

RealtimeConversationMCPApprovalRequestItem

Élément de demande d’approbation MCP.

RealtimeItemStatus

État des éléments de conversation.

Allowed Values:

• in_progress - En cours de traitement
• completed -Réussi
• incomplete - Incomplet (interrompu ou défaillant)

RealtimeContentPart

Composant de contenu dans un message.

RealtimeInputTextContentPart

Composant de contenu texte.

RealtimeOutputTextContentPart

Composant de contenu texte.

RealtimeInputAudioContentPart

Composant contenu audio.

RealtimeOutputAudioContentPart

Composant contenu audio.

Response Objects

RealtimeResponse

Objet response représentant une réponse d’inférence de modèle.

RealtimeResponseStatus

Valeurs d’état de la réponse.

Allowed Values:

• in_progress - La réponse est générée
• completed - Réponse terminée avec succès
• cancelled - La réponse a été annulée
• incomplete - Réponse incomplète (interrompue)
• failed - Échec de la réponse avec une erreur

RealtimeUsage

Statistiques d’utilisation des jetons.

TokenDetails

Répartition détaillée de l’utilisation des jetons.

Error Handling

RealtimeErrorDetails

Objet d’informations d’erreur.

RealtimeConversationRequestItem

Vous utilisez l’objet RealtimeConversationRequestItem pour créer un élément dans la conversation via l’événement conversation.item.create.

Il s’agit d’un type d’union qui peut être l’un des éléments suivants :

RealtimeSystemMessageItem

Élément de message système.

RealtimeUserMessageItem

Élément de message utilisateur.

RealtimeAssistantMessageItem

Élément de message d’assistant.

RealtimeFunctionCallItem

Élément d’appel de fonction.

RealtimeFunctionCallOutputItem

Élément de sortie d’appel de fonction.

RealtimeMCPApprovalResponseItem

Élément de réponse d’approbation MCP.

RealtimeFunctionTool

Définition d’un outil de fonction tel qu’utilisé par le point de terminaison en temps réel.

RealtimeItemStatus

Allowed Values:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

L’objet RealtimeResponseSession représente une session dans l’API Realtime. Il est utilisé dans certains des événements de serveur, tels que :

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Related Resources

• Essayez le démarrage rapide Voice Live
• Essayer le démarrage rapide des agents Voice Live
• En savoir plus sur l’utilisation de l’API Voice Live