Referência da API ao vivo de voz

A API dinâmica do Voice fornece comunicação bidirecional em tempo real para aplicativos habilitados para voz usando conexões WebSocket. Essa API dá suporte a recursos avançados, incluindo reconhecimento de fala, síntese de texto em fala, streaming de avatar, dados de animação e recursos abrangentes de processamento de áudio.

A API usa eventos formatados em JSON enviados por conexões WebSocket para gerenciar conversas, fluxos de áudio, interações de avatar e respostas em tempo real. Os eventos são categorizados em eventos de cliente (enviados de cliente para servidor) e eventos de servidor (enviados de servidor para cliente).

Principais características

• Processamento de áudio em tempo real: suporte para vários formatos de áudio, incluindo PCM16 a várias taxas de exemplo e codecs G.711
• Opções avançadas de voz: vozes OpenAI, vozes personalizadas do Azure, vozes padrão do Azure e vozes pessoais do Azure
• Integração de Avatar: streaming de avatar baseado em WebRTC com vídeo, animação e blendshapes
• Detecção de Turno Inteligente: Várias opções de VAD, incluindo VAD semântico do Azure e detecção do lado do servidor
• Aprimoramento de áudio: redução de ruído interna e cancelamento de eco
• Chamada de função: integração de ferramentas para recursos de conversação aprimorados
• Gerenciamento de Sessão Flexível: modalidades configuráveis, instruções e parâmetros de resposta

Eventos do cliente

A API ao vivo do Voice dá suporte aos seguintes eventos de cliente que podem ser enviados do cliente para o servidor:

session.update

Atualize a configuração da sessão. Esse evento pode ser enviado a qualquer momento para modificar configurações como voz, modalidades, detecção de turnos, ferramentas e outros parâmetros de sessão. Observe que uma vez que uma sessão é inicializada com um modelo específico, ela não pode ser alterada para outro modelo.

Estrutura de eventos

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

Propriedades

Exemplo com a Voz Personalizada do Azure

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

Estabeleça uma conexão de avatar fornecendo a oferta SDP (Protocolo de Descrição da Sessão) do cliente para negociação de mídia webRTC. Esse evento é necessário ao usar recursos de avatar.

Estrutura de eventos

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

Propriedades

input_audio_buffer.append

Acrescente bytes de áudio ao buffer de áudio de entrada.

Estrutura de eventos

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

Propriedades

input_audio_buffer.commit

Confirme o buffer de áudio de entrada para processamento.

Estrutura de eventos

{
  "type": "input_audio_buffer.commit"
}

Propriedades

input_audio_buffer.clear

Desmarque o buffer de áudio de entrada.

Estrutura de eventos

{
  "type": "input_audio_buffer.clear"
}

Propriedades

conversation.item.create

Adicione um novo item ao contexto da conversa. Isso pode incluir mensagens, chamadas de função e respostas de chamada de função. Os itens podem ser inseridos em posições específicas no histórico de conversas.

Estrutura de eventos

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

Propriedades

Exemplo com conteúdo de áudio

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

Exemplo com chamada de função

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

Exemplo com chamada 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

Recupere um item específico do histórico de conversas. Isso é útil para inspecionar o áudio processado após o cancelamento de ruído e o VAD.

Estrutura de eventos

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

Propriedades

conversation.item.truncate

Truncar o conteúdo de áudio de uma mensagem de assistente. Isso é útil para interromper a reprodução em um ponto específico e sincronizar o entendimento do servidor com o estado do cliente.

Estrutura de eventos

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

Propriedades

conversation.item.delete

Remova um item do histórico de conversas.

Estrutura de eventos

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

Propriedades

response.create

Instrua o servidor a criar uma resposta por meio de inferência de modelo. Esse evento pode especificar a configuração específica da resposta que substitui os padrões de sessão.

Estrutura de eventos

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

Propriedades

Exemplo com a opção de ferramenta

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

Exemplo com animação

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

Cancele uma resposta em andamento. Isso interrompe imediatamente a geração de resposta e a saída de áudio relacionada.

Estrutura de eventos

{
  "type": "response.cancel"
}

Propriedades

Propriedades

RealtimeClientEventConversationItemTruncate

O evento cliente conversation.item.truncate é usado para truncar o áudio de uma mensagem de assistente anterior. O servidor produz áudio mais rápido do que em tempo real, portanto, esse evento é útil quando o usuário interrompe para truncar o áudio que foi enviado ao cliente, mas ainda não reproduzido. A compreensão do áudio pelo servidor com a reprodução do cliente é sincronizada.

Truncar o áudio exclui a transcrição do texto do lado do servidor para garantir que não haja texto no contexto que o usuário não conheça.

Se o evento do cliente for bem-sucedido, o servidor responderá com um conversation.item.truncated evento.

Estrutura de eventos

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

Propriedades

RealtimeClientEventInputAudioBufferAppend

O evento cliente input_audio_buffer.append é usado para acrescentar bytes de áudio ao buffer de áudio de entrada. O buffer de áudio é um armazenamento temporário para o qual você pode gravar e confirmar posteriormente.

No modo VAD do servidor (Detecção de Atividade de Voz), o buffer de áudio é usado para detectar fala e o servidor decide quando fazer commit. Quando o VAD do servidor é desabilitado, o cliente pode escolher quanto áudio colocar em cada evento até um máximo de 15 MiB. Por exemplo, transmitir partes menores do cliente pode permitir que o VAD seja mais responsivo.

Ao contrário da maioria dos outros eventos do cliente, o servidor não envia uma resposta de confirmação ao evento do cliente input_audio_buffer.append .

Estrutura de eventos

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

Propriedades

RealtimeClientEventInputAudioBufferClear

O evento cliente input_audio_buffer.clear é usado para limpar os bytes de áudio no buffer.

O servidor responde com um input_audio_buffer.cleared evento.

Estrutura de eventos

{
  "type": "input_audio_buffer.clear"
}

Propriedades

RealtimeClientEventInputAudioBufferCommit

O evento do cliente input_audio_buffer.commit é usado para confirmar o buffer de áudio de entrada do usuário, que cria um novo item de mensagem de usuário na conversa. O áudio será transcrito se input_audio_transcription estiver configurado para a sessão.

Quando no modo VAD do servidor, o cliente não precisa enviar esse evento, o servidor confirma o buffer de áudio automaticamente. Sem o VAD do servidor, o cliente deve confirmar o buffer de áudio para criar um item de mensagem do usuário. Esse evento cliente produzirá um erro se o buffer de áudio de entrada estiver vazio.

A confirmação do buffer de áudio de entrada não cria uma resposta do modelo.

O servidor responde com um input_audio_buffer.committed evento.

Estrutura de eventos

{
  "type": "input_audio_buffer.commit"
}

Propriedades

RealtimeClientEventResponseCancel

O evento response.cancel de cliente é usado para cancelar uma resposta em andamento.

O servidor responderá com um response.done evento com um status de response.status=cancelled.

Estrutura de eventos

{
  "type": "response.cancel"
}

Propriedades

RealtimeClientEventResponseCreate

O evento cliente response.create é usado para instruir o servidor a criar uma resposta por meio de inferência de modelo. Quando a sessão é configurada no modo VAD do servidor, o servidor cria respostas automaticamente.

Uma resposta inclui pelo menos uma iteme pode ter duas, nesse caso, a segunda é uma chamada de função. Esses itens são acrescentados ao histórico de conversas.

O servidor responde com um evento, um response.created ou mais eventos de conteúdo e um item (como conversation.item.created e response.content_part.added), e, por fim, um response.done evento para indicar que a resposta está concluída.

Estrutura de eventos

{
  "type": "response.create"
}

Propriedades

RealtimeClientEventSessionUpdate

O evento cliente session.update é usado para atualizar a configuração padrão da sessão. O cliente pode enviar esse evento a qualquer momento para atualizar a configuração da sessão e qualquer campo pode ser atualizado a qualquer momento, exceto por voz.

Somente os campos presentes são atualizados. Para limpar um campo (como instructions), passe uma cadeia de caracteres vazia.

O servidor responde com um session.updated evento que contém a configuração efetiva completa.

Estrutura de eventos

{
  "type": "session.update"
}

Propriedades

Eventos do servidor

A API ao vivo do Voice envia os seguintes eventos de servidor para comunicar status, respostas e dados ao cliente:

session.created

Enviado quando uma nova sessão é estabelecida com êxito. Esse é o primeiro evento recebido depois de se conectar à API.

Estrutura de eventos

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

Propriedades

session.updated

Enviado quando a configuração da sessão é atualizada com êxito em resposta a um session.update evento cliente.

Estrutura de eventos

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

Propriedades

session.avatar.connecting

Indica que uma conexão WebRTC de avatar está sendo estabelecida. Esse evento é enviado em resposta a um session.avatar.connect evento cliente.

Estrutura de eventos

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

Propriedades

conversation.item.created

Enviado quando um novo item é adicionado à conversa, por meio de um evento cliente conversation.item.create ou automaticamente durante a geração de resposta.

Estrutura de eventos

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

Propriedades

Exemplo com Item de Áudio

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

Enviado em resposta a um conversation.item.retrieve evento de cliente, fornecendo o item de conversa solicitado.

Propriedades

conversation.item.truncated

O evento do servidor conversation.item.truncated é retornado quando o cliente trunca um item de mensagem de áudio do assistente anterior com um conversation.item.truncate evento. Esse evento é usado para sincronizar a compreensão do servidor do áudio com a reprodução do cliente.

Esse evento trunca o áudio e remove a transcrição de texto do lado do servidor para garantir que não haja nenhum texto no contexto que o usuário não saiba.

Estrutura de eventos

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

Propriedades

conversation.item.deleted

Enviado em resposta a um conversation.item.delete evento de cliente, confirmando que o item especificado foi removido da conversa.

Estrutura de eventos

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

Propriedades

response.created

Enviado quando uma nova geração de resposta começa. Este é o primeiro evento em uma sequência de resposta.

Estrutura de eventos

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

Propriedades

response.done

Enviado quando a geração de resposta é concluída. Esse evento contém a resposta final com todos os itens de saída e estatísticas de uso.

Estrutura de eventos

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

Propriedades

response.output_item.adicionado

Enviado quando um novo item de saída é adicionado à resposta durante a geração.

Estrutura de eventos

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

Propriedades

response.output_item.done

Enviado quando um item de saída é concluído.

Estrutura de eventos

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

Propriedades

response.content_part.adicionado

O evento do servidor response.content_part.added é retornado quando uma nova parte de conteúdo é adicionada a um item de mensagem do assistente durante a geração de resposta.

Estrutura de eventos

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

Propriedades

response.content_part.done

O evento do servidor response.content_part.done é retornado quando uma parte de conteúdo é feita em streaming em um item de mensagem do assistente.

Esse evento também é retornado quando uma resposta é interrompida, incompleta ou cancelada.

Estrutura de eventos

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

Propriedades

response.text.delta

Streaming de conteúdo de texto do modelo. Enviado incrementalmente à medida que o modelo gera texto.

Estrutura de eventos

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

Propriedades

response.text.done

Enviado quando a geração de conteúdo de texto é concluída.

Estrutura de eventos

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

Propriedades

response.audio.delta

Streaming de conteúdo de áudio do modelo. O áudio é fornecido como dados codificados em base64.

Estrutura de eventos

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

Propriedades

response.audio.done

Enviado quando a geração de conteúdo de áudio é concluída.

Estrutura de eventos

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

Propriedades

response.audio_transcript.delta

Transcrição de streaming do conteúdo de áudio gerado.

Estrutura de eventos

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

Propriedades

response.audio_transcript.done

Enviado quando a geração de transcrição de áudio é concluída.

Estrutura de eventos

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

Propriedades

conversation.item.input_audio_transcription.completed

O evento do servidor conversation.item.input_audio_transcription.completed é o resultado da transcrição de áudio da fala gravada no buffer de áudio.

A transcrição começa quando o buffer de áudio de entrada é confirmado pelo cliente ou servidor (no server_vad modo). A transcrição é executada de forma assíncrona com a criação da resposta, portanto, esse evento pode vir antes ou depois dos eventos de resposta.

Os modelos de API em tempo real aceitam áudio nativamente e, portanto, a transcrição de entrada é um processo separado executado em um modelo de reconhecimento de fala separado, como whisper-1. Portanto, a transcrição pode divergir um pouco da interpretação do modelo e deve ser tratada como um guia aproximado.

Estrutura de eventos

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

Propriedades

conversation.item.input_audio_transcription.delta

O evento do servidor conversation.item.input_audio_transcription.delta é retornado quando a transcrição de áudio de entrada é configurada e uma solicitação de transcrição para uma mensagem de usuário está em andamento. Esse evento fornece resultados parciais de transcrição conforme eles ficam disponíveis.

Estrutura de eventos

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

Propriedades

conversation.item.input_audio_transcription.failed

O evento do servidor conversation.item.input_audio_transcription.failed é retornado quando a transcrição de áudio de entrada é configurada e uma solicitação de transcrição para uma mensagem de usuário falhou. Esse evento é separado de outros error eventos para que o cliente possa identificar o item relacionado.

Estrutura de eventos

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

Propriedades

Propriedades de erro

response.animation_blendshapes.delta

O evento do servidor response.animation_blendshapes.delta é retornado quando o modelo gera dados de blendshapes de animação como parte de uma resposta. Esse evento fornece dados de blendshapes incrementais à medida que ficam disponíveis.

Estrutura de eventos

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

Propriedades

response.animation_blendshapes.done

O evento do servidor response.animation_blendshapes.done é retornado quando o modelo termina de gerar dados de blendshapes de animação como parte de uma resposta.

Estrutura de eventos

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

Propriedades

response.audio_timestamp.delta

O evento do servidor response.audio_timestamp.delta é retornado quando o modelo gera dados de carimbo de data/hora de áudio como parte de uma resposta. Esse evento fornece dados incrementais de carimbo de data/hora para o alinhamento de áudio e texto de saída à medida que fica disponível.

Estrutura de eventos

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

Propriedades

response.audio_timestamp.done

Enviado quando a geração do carimbo de data/hora de áudio é concluída.

Estrutura de eventos

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

Propriedades

response.animation_viseme.delta

O evento do servidor response.animation_viseme.delta é retornado quando o modelo gera dados de viseme de animação como parte de uma resposta. Esse evento fornece dados incrementais do viseme à medida que ficam disponíveis.

Estrutura de eventos

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

Propriedades

response.animation_viseme.done

O evento do servidor response.animation_viseme.done é retornado quando o modelo termina de gerar dados de viseme de animação como parte de uma resposta.

Estrutura de eventos

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

Propriedades

O evento do servidor response.animation_viseme.delta é retornado quando o modelo gera dados de viseme de animação como parte de uma resposta. Esse evento fornece dados incrementais do viseme à medida que ficam disponíveis.

erro

O evento do servidor error é retornado quando ocorre um erro, o que pode ser um problema de cliente ou de servidor. A maioria dos erros é recuperável e a sessão permanece aberta.

Estrutura de eventos

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

Propriedades

Propriedades de erro

input_audio_buffer.cleared

O evento do servidor input_audio_buffer.cleared é retornado quando o cliente limpa o buffer de áudio de entrada com um input_audio_buffer.clear evento.

Estrutura de eventos

{
  "type": "input_audio_buffer.cleared"
}

Propriedades

input_audio_buffer.committed

O evento do servidor input_audio_buffer.committed é retornado quando um buffer de áudio de entrada é confirmado pelo cliente ou automaticamente no modo VAD do servidor. A item_id propriedade é a ID do item de mensagem do usuário criado. Portanto, um conversation.item.created evento também é enviado ao cliente.

Estrutura de eventos

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

Propriedades

input_audio_buffer.speech_started

O evento do servidor input_audio_buffer.speech_started é retornado no server_vad modo quando a fala é detectada no buffer de áudio. Esse evento pode acontecer sempre que o áudio for adicionado ao buffer (a menos que a fala já seja detectada).

O cliente deve esperar receber um input_audio_buffer.speech_stopped evento quando a fala for interrompida. A item_id propriedade é a ID do item de mensagem do usuário criado quando a fala é interrompida. O item_id também é incluído no evento, a input_audio_buffer.speech_stopped menos que o cliente confirme manualmente o buffer de áudio durante a ativação do VAD.

Estrutura de eventos

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

Propriedades

input_audio_buffer.speech_stopped

O evento do servidor input_audio_buffer.speech_stopped é retornado no server_vad modo quando o servidor detecta o fim da fala no buffer de áudio.

O servidor também envia um conversation.item.created evento com o item de mensagem do usuário criado a partir do buffer de áudio.

Estrutura de eventos

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

Propriedades

rate_limits.updated

O evento do servidor rate_limits.updated é emitido no início de uma resposta para indicar os limites de taxa atualizados.

Quando uma resposta é criada, alguns tokens são reservados para os tokens de saída. Os limites de taxa mostrados aqui refletem essa reserva, que é ajustada de acordo quando a resposta é concluída.

Estrutura de eventos

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

Propriedades

response.audio.delta

O evento do servidor response.audio.delta é retornado quando o áudio gerado pelo modelo é atualizado.

Estrutura de eventos

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

Propriedades

response.audio.done

O evento do servidor response.audio.done é retornado quando o áudio gerado pelo modelo é feito.

Esse evento também é retornado quando uma resposta é interrompida, incompleta ou cancelada.

Estrutura de eventos

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

Propriedades

response.audio_transcript.delta

O evento do servidor response.audio_transcript.delta é retornado quando a transcrição gerada pelo modelo da saída de áudio é atualizada.

Estrutura de eventos

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

Propriedades

response.audio_transcript.done

O evento do servidor response.audio_transcript.done é retornado quando a transcrição gerada pelo modelo da saída de áudio é feita em streaming.

Esse evento também é retornado quando uma resposta é interrompida, incompleta ou cancelada.

Estrutura de eventos

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

Propriedades

response.function_call_arguments.delta

O evento do servidor response.function_call_arguments.delta é retornado quando os argumentos de chamada de função gerados pelo modelo são atualizados.

Estrutura de eventos

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

Propriedades

response.function_call_arguments.done

O evento do servidor response.function_call_arguments.done é retornado quando os argumentos de chamada de função gerados pelo modelo são feitos em streaming.

Esse evento também é retornado quando uma resposta é interrompida, incompleta ou cancelada.

Estrutura de eventos

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

Propriedades

mcp_list_tools.in_progress

O evento do servidor mcp_list_tools.in_progress é retornado quando o serviço inicia a listagem de ferramentas disponíveis de um servidor mcp.

Estrutura de eventos

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

Propriedades

mcp_list_tools.completed

O evento do servidor mcp_list_tools.completed é retornado quando o serviço conclui a listagem de ferramentas disponíveis de um servidor mcp.

Estrutura de eventos

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

Propriedades

mcp_list_tools.falhou

O evento do servidor mcp_list_tools.failed é retornado quando o serviço falha ao listar as ferramentas disponíveis de um servidor mcp.

Estrutura de eventos

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

Propriedades

response.mcp_call_arguments.delta

O evento do servidor response.mcp_call_arguments.delta é retornado quando os argumentos de chamada da ferramenta mcp gerados pelo modelo são atualizados.

Estrutura de eventos

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

Propriedades

response.mcp_call_arguments.done

O evento do servidor response.mcp_call_arguments.done é retornado quando os argumentos de chamada da ferramenta mcp gerados pelo modelo são feitos em streaming.

Estrutura de eventos

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

Propriedades

response.mcp_call.in_progress

O evento do servidor response.mcp_call.in_progress é retornado quando uma chamada de ferramenta MCP inicia o processamento.

Estrutura de eventos

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

Propriedades

response.mcp_call.completed

O evento do servidor response.mcp_call.completed é retornado quando uma chamada de ferramenta MCP é concluída com êxito.

Estrutura de eventos

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

Propriedades

response.mcp_call.falhou

O evento do servidor response.mcp_call.failed é retornado quando uma chamada de ferramenta MCP falha.

Estrutura de eventos

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

Propriedades

response.output_item.adicionado

O evento do servidor response.output_item.added é retornado quando um novo item é criado durante a geração de resposta.

Estrutura de eventos

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

Propriedades

response.output_item.done

O evento do servidor response.output_item.done é retornado quando um item é feito em streaming.

Esse evento também é retornado quando uma resposta é interrompida, incompleta ou cancelada.

Estrutura de eventos

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

Propriedades

response.text.delta

O evento do servidor response.text.delta é retornado quando o texto gerado pelo modelo é atualizado. O texto corresponde à parte de text conteúdo de um item de mensagem do assistente.

Estrutura de eventos

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

Propriedades

response.text.done

O evento do servidor response.text.done é retornado quando o texto gerado pelo modelo é feito em streaming. O texto corresponde à parte de text conteúdo de um item de mensagem do assistente.

Esse evento também é retornado quando uma resposta é interrompida, incompleta ou cancelada.

Estrutura de eventos

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

Propriedades

Components

Formatos de áudio

RealtimeAudioFormat

Formato de áudio base usado para áudio de entrada.

Valores permitidos:

• pcm16 - Formato de áudio PCM de 16 bits
• g711_ulaw - Formato de áudio de lei do μ G.711
• g711_alaw – Formato de áudio da lei A.711 G.711

RealtimeOutputAudioFormat

Formato de áudio usado para áudio de saída com taxas de amostragem específicas.

Valores permitidos:

• pcm16 - Formato de áudio PCM de 16 bits com taxa de amostragem padrão (24kHz)
• pcm16_8000hz - Formato de áudio PCM de 16 bits a taxa de amostragem de 8kHz
• pcm16_16000hz – Formato de áudio PCM de 16 bits a taxa de amostragem de 16kHz
• g711_ulaw - Formato de áudio de lei de μ (mu-law) da G.711 a taxa de amostragem de 8kHz
• g711_alaw – G.711 Formato de áudio de lei A a taxa de amostragem de 8kHz

RealtimeAudioInputTranscriptionSettings

Configuração para transcrição de áudio de entrada.

RealtimeInputAudioNoiseReductionSettings

Isso pode ser:

• Um objeto RealtimeOpenAINoiseReduction
• Um objeto RealtimeAzureDeepNoiseSuppression

RealtimeOpenAINoiseReduction

Configuração de redução de ruído openAI com campo de tipo explícito, disponível apenas para modelos e para gpt-realtimegpt-realtime-mini .

RealtimeAzureDeepNoiseSuppression

Configuração para redução de ruído de áudio de entrada.

RealtimeInputAudioEchoCancellationSettings

Configuração de cancelamento de eco para processamento de áudio do lado do servidor.

Configuração de Voz

RealtimeVoice

União de todas as configurações de voz com suporte.

Isso pode ser:

• Um objeto RealtimeOpenAIVoice
• Um objeto RealtimeAzureVoice

RealtimeOpenAIVoice

Configuração de voz OpenAI com campo de tipo explícito.

RealtimeAzureVoice

Base para configurações de voz do Azure. Essa é uma união discriminada com tipos diferentes:

RealtimeAzureStandardVoice

Configuração de voz padrão do Azure.

RealtimeAzureCustomVoice

Configuração de voz personalizada do Azure (preferencial para vozes personalizadas).

Exemplo:

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

RealtimeAzurePersonalVoice

Configuração de voz pessoal do Azure.

Detecção de turnos

RealtimeTurnDetection

Configuração para detecção de turnos. Essa é uma união discriminada que dá suporte a vários tipos de VAD.

RealtimeServerVAD

Detecção de turno baseada em VAD base.

RealtimeOpenAISemanticVAD

Configuração de VAD semântica do OpenAI que usa um modelo para determinar quando o usuário terminou de falar. Disponível somente para modelos e gpt-realtime para gpt-realtime-mini modelos.

RealtimeAzureSemanticVAD

VAD semântico do Azure, que determina quando o usuário inicia e fala usando um modelo de fala semântica, fornecendo uma detecção mais robusta em ambientes barulhentos.

RealtimeAzureSemanticVADMultilingual

VAD semântico do Azure (variante padrão).

RealtimeEOUDetection

O EOU (Fim do Enunciado) do Azure pode indicar quando o usuário final parou de falar enquanto permitia pausas naturais. A detecção do fim do enunciado pode reduzir significativamente os sinais prematuros de fim de turno sem adicionar latência perceptível ao usuário.

Configuração do Avatar

RealtimeAvatarConfig

Configuração para streaming e comportamento de avatar.

RealtimeIceServer

Configuração do servidor ICE para negociação de conexão webRTC.

RealtimeVideoParams

Parâmetros de streaming de vídeo para avatar.

RealtimeVideoCrop

Definição de retângulo de corte de vídeo.

RealtimeVideoResolution

Especificação de resolução de vídeo.

Configuração de animação

RealtimeAnimation

Configuração para saídas de animação, incluindo blendshapes e visemes.

RealtimeAnimationOutputType

Tipos de dados de animação para saída.

Valores permitidos:

• blendshapes - Dados de blendshapes faciais
• viseme_id – Dados do identificador do Viseme

Configuração da sessão

RealtimeRequestSession

Objeto de configuração de sessão usado em session.update eventos.

RealtimeModality

Modalidades de sessão com suporte.

Valores permitidos:

• text - Entrada/saída de texto
• audio - Entrada/saída de áudio
• animation - Saída de animação
• avatar - Saída de vídeo do avatar

RealtimeAudioTimestampType

Tipos de carimbo de data/hora de saída com suporte no conteúdo de resposta de áudio.

Valores permitidos:

• word - Carimbos de data/hora por palavra no áudio de saída

Configuração da ferramenta

Oferecemos suporte a dois tipos de ferramentas: chamada de função e ferramentas MCP que permitem que você se conecte a um servidor mcp.

RealtimeTool

Definição de ferramenta para chamada de função.

RealtimeToolChoice

Estratégia de seleção de ferramentas.

Isso pode ser:

• "auto" - Deixe o modelo escolher
• "none" - Não use ferramentas
• "required" - Deve usar uma ferramenta
• { "type": "function", "name": "function_name" } – Usar uma função específica

MCPTool

Configuração da ferramenta MCP.

RealtimeConversationResponseItem

Esse é um tipo de união que pode ser um dos seguintes:

RealtimeConversationUserMessageItem

Item de mensagem do usuário.

RealtimeConversationAssistantMessageItem

Item de mensagem do assistente.

RealtimeConversationSystemMessageItem

Item de mensagem do sistema.

RealtimeConversationFunctionCallItem

Item de solicitação de chamada de função.

RealtimeConversationFunctionCallOutputItem

Item de resposta de chamada de função.

RealtimeConversationMCPListToolsItem

Item de resposta de ferramentas de lista MCP.

RealtimeConversationMCPCallItem

Item de resposta de chamada MCP.

RealtimeConversationMCPApprovalRequestItem

Item de solicitação de aprovação do MCP.

RealtimeItemStatus

Status dos itens de conversa.

Valores permitidos:

• in_progress - Atualmente sendo processado
• completed - Concluído com êxito
• incomplete - Incompleto (interrompido ou com falha)

RealtimeContentPart

Parte do conteúdo dentro de uma mensagem.

RealtimeInputTextContentPart

Parte do conteúdo do texto.

RealtimeOutputTextContentPart

Parte do conteúdo do texto.

RealtimeInputAudioContentPart

Parte do conteúdo de áudio.

RealtimeOutputAudioContentPart

Parte do conteúdo de áudio.

Objetos de resposta

RealtimeResponse

Objeto de resposta que representa uma resposta de inferência de modelo.

RealtimeResponseStatus

Valores de status de resposta.

Valores permitidos:

• in_progress - A resposta está sendo gerada
• completed - Resposta concluída com êxito
• cancelled - A resposta foi cancelada
• incomplete - Resposta incompleta (interrompida)
• failed - Falha na resposta com erro

RealtimeUsage

Estatísticas de uso de token.

TokenDetails

Detalhamento do uso do token.

Tratamento de erros

RealtimeErrorDetails

Objeto de informações de erro.

RealtimeConversationRequestItem

Use o RealtimeConversationRequestItem objeto para criar um novo item na conversa por meio do evento conversation.item.create .

Esse é um tipo de união que pode ser um dos seguintes:

RealtimeSystemMessageItem

Um item de mensagem do sistema.

RealtimeUserMessageItem

Um item de mensagem do usuário.

RealtimeAssistantMessageItem

Um item de mensagem do assistente.

RealtimeFunctionCallItem

Um item de chamada de função.

RealtimeFunctionCallOutputItem

Um item de saída de chamada de função.

RealtimeMCPApprovalResponseItem

Um item de resposta de aprovação do MCP.

RealtimeFunctionTool

A definição de uma ferramenta de função, conforme usado pelo ponto de extremidade em tempo real.

RealtimeItemStatus

Valores permitidos:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

O RealtimeResponseSession objeto representa uma sessão na API realtime. Ele é usado em alguns dos eventos do servidor, como:

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Recursos relacionados

• Experimente o início rápido ao vivo do Voice
• Experimente o início rápido de agentes de voz ao vivo
• Saiba mais sobre como usar a API ao vivo do Voice