Informations de référence sur l’API live vocale

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).

Principales fonctionnalités

• 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 configurables, instructions et paramètres de réponse

Événements clients

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, 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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

input_audio_buffer.append

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

Structure d’événements

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

Propriétés

input_audio_buffer.commit

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

Structure d’événements

{
  "type": "input_audio_buffer.commit"
}

Propriétés

input_audio_buffer.clear

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

Structure d’événements

{
  "type": "input_audio_buffer.clear"
}

Propriétés

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.

Structure d’événements

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

Propriétés

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 l’appel de fonction

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

Exemple avec l’appel MCP

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

conversation.item.retrieve

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

conversation.item.delete

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

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

{
  "type": "response.cancel"
}

Propriétés

Propriétés

RealtimeClientEventConversationItemTruncate

L’événement client conversation.item.truncate est utilisé pour tronquer l’audio d’un message assistant précédent. Le serveur produit de l’audio plus rapidement que en temps réel, de sorte que cet événement est utile lorsque l’utilisateur interrompt la troncation de l’audio qui a été envoyé au client mais qui n’a pas encore été lu. La compréhension du serveur de l’audio avec la lecture du client est synchronisée.

La troncation audio supprime la transcription de texte côté serveur pour s’assurer qu’il n’y a pas de texte dans le contexte auquel l’utilisateur ne sait pas.

Si l’événement client réussit, le serveur répond avec un conversation.item.truncated événement.

Structure d’événements

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

Propriétés

RealtimeClientEventInputAudioBufferAppend

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. Lorsque le serveur VAD 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 à partir du client peut permettre au VAD d’être plus réactif.

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

Structure d’événements

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

Propriétés

RealtimeClientEventInputAudioBufferClear

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 input_audio_buffer.cleared événement.

Structure d’événements

{
  "type": "input_audio_buffer.clear"
}

Propriétés

RealtimeClientEventInputAudioBufferCommit

L’événement client input_audio_buffer.commit est utilisé pour valider la mémoire tampon audio d’entrée utilisateur, ce qui crée un élément de message utilisateur dans la conversation. L’audio est transcrit s’il 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 du 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 input_audio_buffer.committed événement.

Structure d’événements

{
  "type": "input_audio_buffer.commit"
}

Propriétés

RealtimeClientEventResponseCancel

L’événement client response.cancel est utilisé pour annuler une réponse en cours.

Le serveur répond avec un response.done événement avec l’état response.status=cancelled.

Structure d’événements

{
  "type": "response.cancel"
}

Propriétés

RealtimeClientEventResponseCreate

L’événement client response.create est utilisé pour indiquer au serveur de créer une réponse via l’inférence du modèle. Lorsque la session est configurée en mode VAD du serveur, le serveur crée automatiquement des réponses.

Une réponse inclut au moins un item, et peut avoir deux, auquel cas le second est un appel de fonction. Ces éléments sont ajoutés à l’historique des conversations.

Le serveur répond avec un response.created événement, un ou plusieurs événements d’élément et de contenu (tels que conversation.item.created et response.content_part.added) et enfin un response.done événement pour indiquer que la réponse est terminée.

Structure d’événements

{
  "type": "response.create"
}

Propriétés

RealtimeClientEventSessionUpdate

L’événement client session.update est utilisé pour mettre à jour la configuration par défaut de la session. Le client peut envoyer cet événement à tout moment pour mettre à jour la configuration de session, et n’importe quel champ peut être mis à jour à tout moment, à l’exception de la voix.

Seuls les champs présents sont mis à jour. Pour effacer un champ (par exemple instructions), passez une chaîne vide.

Le serveur répond avec un session.updated événement qui contient la configuration effective complète.

Structure d’événements

{
  "type": "session.update"
}

Propriétés

Événements de serveur

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.

Structure d’événements

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

Propriétés

session.updated

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

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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é.

Propriétés

conversation.item.tronqué

L’événement serveur conversation.item.truncated est retourné lorsque le client tronque un élément de message audio assistant antérieur avec un conversation.item.truncate événement. 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 de texte côté serveur pour s’assurer qu’il n’y a pas de texte dans le contexte auquel l’utilisateur ne sait pas.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

response.output_item.added

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

Structure d’événements

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

Propriétés

response.output_item.done

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

Structure d’événements

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

Propriétés

response.content_part.added

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

Structure d’événements

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

Propriétés

response.content_part.done

L’événement de serveur response.content_part.done est retourné lorsqu’une partie de contenu est effectuée en continu dans un élément de message assistant.

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

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

response.text.done

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

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

response.audio.done

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

Structure d’événements

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

Propriétés

response.audio_transcript.delta

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

Structure d’événements

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

Propriétés

response.audio_transcript.done

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

Structure d’événements

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

Propriétés

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 la reconnaissance vocale écrite 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 server_vad mode). 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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

conversation.item.input_audio_transcription.failed

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

Structure d’événements

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

Propriétés

Propriétés de l’erreur

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

response.audio_timestamp.done

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

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

erreur

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

Structure d’événements

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

Propriétés

Propriétés de l’erreur

input_audio_buffer.cleared

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

Structure d’événements

{
  "type": "input_audio_buffer.cleared"
}

Propriétés

input_audio_buffer.commit

L’événement de serveur input_audio_buffer.committed est retourné lorsqu’une mémoire tampon audio d’entrée est validée par le client ou automatiquement en mode VAD du serveur. La item_id propriété 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.

Structure d’événements

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

Propriétés

input_audio_buffer.speech_started

L’événement de serveur input_audio_buffer.speech_started est retourné en server_vad mode lorsque la reconnaissance vocale est détectée 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 input_audio_buffer.speech_stopped événement lorsque la reconnaissance vocale s’arrête. La item_id propriété est l’ID de l’élément de message utilisateur créé lors de l’arrêt de la reconnaissance vocale. Il 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 vaD.

Structure d’événements

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

Propriétés

input_audio_buffer.speech_stop

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

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

Structure d’événements

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

Propriétés

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.

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

Structure d’événements

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

Propriétés

response.audio.delta

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

Structure d’événements

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

Propriétés

response.audio.done

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

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

Structure d’événements

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

Propriétés

response.audio_transcript.delta

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

Structure d’événements

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

Propriétés

response.audio_transcript.done

L’événement de serveur response.audio_transcript.done est retourné lorsque la transcription générée par le modèle de sortie audio est effectuée en streaming.

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

Structure d’événements

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

Propriétés

response.function_call_arguments.delta

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

Structure d’événements

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

Propriétés

response.function_call_arguments.done

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

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

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

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.

Structure d’événements

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

Propriétés

response.mcp_call.completed

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

Structure d’événements

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

Propriétés

response.mcp_call.failed

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

Structure d’événements

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

Propriétés

response.output_item.added

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

Structure d’événements

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

Propriétés

response.output_item.done

L’événement de serveur response.output_item.done est retourné lorsqu’un élément est terminé en streaming.

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

Structure d’événements

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

Propriétés

response.text.delta

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

Structure d’événements

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

Propriétés

response.text.done

L’événement de serveur response.text.done est retourné lorsque le texte généré par le modèle est terminé en streaming. Le texte correspond à la text partie de contenu d’un élément de message assistant.

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

Structure d’événements

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

Propriétés

Components

Audio Formats

RealtimeAudioFormat

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

Valeurs autorisées :

• 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.

Valeurs autorisées :

• 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.

Configuration vocale

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).

Exemple :

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

Détection de tour

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.

RealtimeAzureSemanticVADMultilinguel

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.

Configuration d’Avatar

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.

Configuration de l’animation

RealtimeAnimation

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

RealtimeAnimationOutputType

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

Valeurs autorisées :

• 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 session prises en charge.

Valeurs autorisées :

• text - Entrée/sortie de texte
• audio - Entrée/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.

Valeurs autorisées :

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

Configuration de l’outil

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.

Valeurs autorisées :

• 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.

Objets response

RealtimeResponse

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

RealtimeResponseStatus

Valeurs d’état de la réponse.

Valeurs autorisées :

• 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.

Gestion des erreurs

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

Valeurs autorisées :

• 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

Ressources associées

• Essayer le démarrage rapide de Voice live
• Essayez le Démarrage rapide des assistants vocaux en direct
• En savoir plus sur l’utilisation de l’API voice live