Referência da API de voz ao vivo

A API de voz ao vivo fornece comunicação bidirecional em tempo real para aplicativos habilitados para voz usando conexões WebSocket. Esta API suporta recursos avançados, incluindo reconhecimento de fala, síntese de texto para 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 em várias taxas de amostragem 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
• Deteção inteligente de turnos: várias opções de VAD, incluindo VAD semântica do Azure e deteção do lado do servidor
• Aprimoramento de áudio: Built-in redução de ruído e cancelamento de eco
• Chamada de funções: integração de ferramentas para recursos de conversação aprimorados
• Gerenciamento flexível de sessões: modalidades, instruções e parâmetros de resposta configuráveis

Eventos do Cliente

A API de voz ao vivo suporta os 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, deteção de turnos, ferramentas e outros parâmetros da 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 do Evento

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

sessão.avatar.connect

Estabeleça uma conexão avatar fornecendo a oferta SDP (Session Description Protocol) do cliente para negociação de mídia WebRTC. Este evento é necessário ao usar recursos de avatar.

Estrutura do Evento

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

Propriedades

input_audio_buffer.append

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

Estrutura do Evento

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

Propriedades

input_audio_buffer.Commit

Confirme o buffer de áudio de entrada para processamento.

Estrutura do Evento

{
  "type": "input_audio_buffer.commit"
}

Propriedades

input_audio_buffer.clear

Limpe o buffer de áudio de entrada.

Estrutura do Evento

{
  "type": "input_audio_buffer.clear"
}

Propriedades

conversa.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 do Evento

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

conversa.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 VAD.

Estrutura do Evento

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

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

Propriedades

conversa.item.delete

Remova um item do histórico de conversas.

Estrutura do Evento

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

Propriedades

resposta.criar

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

Estrutura do Evento

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

resposta.cancelar

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

Estrutura do Evento

{
  "type": "response.cancel"
}

Propriedades

Propriedades

RealtimeClientEventConversationItemTruncate

O evento client 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 para o cliente, mas ainda não foi reproduzido. A compreensão do servidor do áudio com a reprodução do cliente é sincronizada.

Truncar o áudio exclui a transcrição de 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 do evento

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

Propriedades

RealtimeClientEventInputAudioBufferAppend

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

No modo VAD (Deteção de Atividade de Voz) do servidor, o buffer de áudio é usado para detetar fala e o servidor decide quando confirmar. Quando o VAD do servidor está desativado, o cliente pode escolher a quantidade de áudio a colocar em cada evento até um máximo de 15 MiB. Por exemplo, o streaming de partes menores do cliente pode permitir que o VAD seja mais responsivo.

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

Estrutura do evento

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

Propriedades

RealtimeClientEventInputAudioBufferClear

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

O servidor responde com um input_audio_buffer.cleared evento.

Estrutura do evento

{
  "type": "input_audio_buffer.clear"
}

Propriedades

RealtimeClientEventInputAudioBufferCommit

O evento client input_audio_buffer.commit é usado para confirmar o buffer de áudio de entrada do usuário, que cria um novo item de mensagem do usuário na conversa. O áudio é 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 de cliente produz um erro se o buffer de áudio de entrada estiver vazio.

Confirmar o buffer de áudio de entrada não cria uma resposta do modelo.

O servidor responde com um input_audio_buffer.committed evento.

Estrutura do evento

{
  "type": "input_audio_buffer.commit"
}

Propriedades

RealtimeClientEventResponseCancel

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

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

Estrutura do evento

{
  "type": "response.cancel"
}

Propriedades

RealtimeClientEventResponseCriar

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

Uma resposta inclui pelo menos um item, e pode ter dois, caso em que o segundo é uma chamada de função. Esses itens são anexados ao histórico de conversas.

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

Estrutura do evento

{
  "type": "response.create"
}

Propriedades

RealtimeClientEventSessionUpdate

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

Apenas 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 do evento

{
  "type": "session.update"
}

Propriedades

Eventos do servidor

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

sessão.criado

Enviado quando uma nova sessão é estabelecida com êxito. Este é o primeiro evento recebido após a conexão com a API.

Estrutura do Evento

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

Estrutura do Evento

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

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

Estrutura do Evento

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

Propriedades

conversa.item.created

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

Estrutura do Evento

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

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

Propriedades

conversation.item.truncado

O evento server conversation.item.truncated é retornado quando o cliente trunca um item de mensagem de áudio do assistente anterior com um conversation.item.truncate evento. Este 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 texto no contexto que o usuário não conheça.

Estrutura do evento

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

Propriedades

conversa.item.deleted

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

Estrutura do Evento

{
  "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 de uma sequência de resposta.

Estrutura do Evento

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

resposta.feito

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

Estrutura do Evento

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

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

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

Estrutura do Evento

{
  "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 server response.content_part.added é retornado quando uma nova parte de conteúdo é adicionada a um item de mensagem assistente durante a geração de resposta.

Estrutura do Evento

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

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

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

Estrutura do Evento

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

resposta.text.delta

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

Estrutura do Evento

{
  "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 estiver concluída.

Estrutura do Evento

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

resposta.audio.delta

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

Estrutura do Evento

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

Propriedades

resposta.audio.done

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

Estrutura do Evento

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

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

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

Estrutura do Evento

{
  "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.concluída

O evento do servidor conversation.item.input_audio_transcription.completed é o resultado da transcrição de áudio para 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 de resposta, para que esse evento possa 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-1o . Assim, a transcrição pode divergir um pouco da interpretação do modelo, e deve ser tratada como um guia aproximado.

Estrutura do evento

{
  "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 server 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. Este evento fornece resultados de transcrição parcial à medida que ficam disponíveis.

Estrutura do evento

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

Propriedades

conversation.item.input_audio_transcription.falhou

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. Este evento é separado de outros error eventos para que o cliente possa identificar o item relacionado.

Estrutura do evento

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

Propriedades

Propriedades do erro

response.animation_blendshapes.delta

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

Estrutura do evento

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

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

Estrutura do evento

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

Propriedades

response.audio_timestamp.delta

O evento server 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 alinhamento de áudio e texto de saída à medida que fica disponível.

Estrutura do evento

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

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

Estrutura do Evento

{
  "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 server response.animation_viseme.delta é retornado quando o modelo gera dados viseme de animação como parte de uma resposta. Este evento fornece dados viseme incrementais à medida que se tornam disponíveis.

Estrutura do Evento

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

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

Estrutura do Evento

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

Propriedades

O evento server response.animation_viseme.delta é retornado quando o modelo gera dados viseme de animação como parte de uma resposta. Este evento fornece dados viseme incrementais à medida que se tornam disponíveis.

erro

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

Estrutura do evento

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

Propriedades

Propriedades do erro

input_audio_buffer.limpo

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 do evento

{
  "type": "input_audio_buffer.cleared"
}

Propriedades

input_audio_buffer.Comprometido

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. Assim, um conversation.item.created evento também é enviado para o cliente.

Estrutura do evento

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

Propriedades

input_audio_buffer.speech_iniciado

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

O cliente deve esperar receber um input_audio_buffer.speech_stopped evento quando a fala parar. A item_id propriedade é a ID do item de mensagem do usuário criado quando a fala é interrompida. O item_id também está 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 do evento

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

Propriedades

input_audio_buffer.speech_parou

O evento do servidor input_audio_buffer.speech_stopped é retornado no server_vad modo quando o servidor deteta 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 do evento

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

Propriedades

rate_limits.atualizado

O evento server 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 tarifa mostrados aqui refletem essa reserva, que é ajustada em conformidade assim que a resposta for concluída.

Estrutura do evento

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

Propriedades

resposta.audio.delta

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

Estrutura do evento

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

Propriedades

resposta.audio.done

O evento server response.audio.done é retornado quando o áudio gerado pelo modelo é concluído.

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

Estrutura do evento

{
  "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 server response.audio_transcript.delta é retornado quando a transcrição gerada pelo modelo da saída de áudio é atualizada.

Estrutura do evento

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

O evento server 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 do evento

{
  "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 server response.function_call_arguments.delta é retornado quando os argumentos de chamada de função gerados pelo modelo são atualizados.

Estrutura do evento

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

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

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

Estrutura do evento

{
  "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 é devolvido quando o serviço começa a listar as ferramentas disponíveis de um servidor mcp.

Estrutura do evento

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

Propriedades

mcp_list_tools.concluído

O evento do servidor mcp_list_tools.completed é devolvido quando o serviço completa de listar as ferramentas disponíveis de um servidor mcp.

Estrutura do evento

{
  "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 é devolvido quando o serviço não consegue listar as ferramentas disponíveis de um servidor mcp.

Estrutura do evento

{
  "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 é devolvido quando os argumentos de chamada à ferramenta mcp gerados pelo modelo são atualizados.

Estrutura do evento

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

Propriedades

response.mcp_call_arguments feito

O evento do servidor response.mcp_call_arguments.done é devolvido quando os argumentos da chamada à ferramenta mcp gerados pelo modelo terminam de ser transmitidos.

Estrutura do evento

{
  "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 é devolvido quando uma chamada de ferramenta MCP começa a ser processada.

Estrutura do evento

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

Propriedades

response.mcp_call.concluído

O evento do servidor response.mcp_call.completed é devolvido quando uma chamada de ferramenta MCP é concluída com sucesso.

Estrutura do evento

{
  "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 é devolvido quando uma chamada à ferramenta MCP falha.

Estrutura do evento

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

Propriedades

response.output_item.adicionado

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

Estrutura do evento

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

Propriedades

response.output_item.feito

O evento server response.output_item.done é retornado quando um item é feito streaming.

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

Estrutura do evento

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

Propriedades

resposta.text.delta

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

Estrutura do evento

{
  "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 server response.text.done é retornado quando o texto gerado pelo modelo é feito streaming. O texto corresponde à text parte de conteúdo de um item de mensagem do assistente.

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

Estrutura do evento

{
  "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 entrada de áudio.

Valores permitidos:

• pcm16 - Formato de áudio PCM de 16 bits
• g711_ulaw - G.711 formato de áudio μ-law
• g711_alaw - G.711 A-law formato de áudio

RealtimeOutputAudioFormat

Formato de áudio usado para saída de áudio 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 uma taxa de amostragem de 8 kHz
• pcm16_16000hz - Formato de áudio PCM de 16 bits a uma taxa de amostragem de 16 kHz
• g711_ulaw - Formato de áudio G.711 μ-law (mu-law) a uma taxa de amostragem de 8kHz
• g711_alaw - Formato de áudio G.711 A-law a uma taxa de amostragem de 8kHz

RealtimeAudioInputTranscriptionSettings

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

RealtimeInputAudioNoiseReductionSettings

Pode tratar-se de:

• 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 gpt-realtime e gpt-realtime-mini modelos.

RealtimeAzureDeepNoiseSuppression

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

RealtimeInputAudioEchoCancellationSettings

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

Configuração de voz

RealtimeVoice

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

Pode tratar-se de:

• 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. Esta é uma união discriminada com diferentes tipos:

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.

Deteção de turnos

RealtimeTurnDetection

Configuração para deteção de turnos. Esta é uma união discriminada que suporta vários tipos de DVA.

RealtimeServerVAD

Deteção de turnos baseada em VAD de base.

RealtimeOpenAISemanticVAD

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

RealtimeAzureSemanticVAD

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

RealtimeAzureSemanticVADMultilingual

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

RealtimeEOUDetection

O Azure End-of-Utterance (EOU) pode indicar quando o usuário final parou de falar enquanto permite pausas naturais. A deteção de fim de emissão pode reduzir significativamente os sinais prematuros de fim de turno sem adicionar latência percetível pelo 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.

VideoParams em tempo real

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 a serem produzidos.

Valores permitidos:

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

Configuração da sessão

RealtimeRequestSession

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

Modalidade em tempo real

Modalidades de sessão suportadas.

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 avatar

RealtimeAudioTimestampType

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

Valores permitidos:

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

Configuração da ferramenta

Suportamos dois tipos de ferramentas: chamada de funções e ferramentas MCP, que permitem ligar a um servidor mcp.

RealtimeTool

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

RealtimeToolChoice

Estratégia de seleção de ferramentas.

Pode tratar-se de:

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

MCPTool

Configuração da ferramenta MCP.

RealtimeConversationResponseItem

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

Lista de ferramentas MCP item de resposta.

RealtimeConversationMCPCallItem

Item de resposta de chamada MCP.

RealtimeConversationMCPApprovalRequestItem

Item do pedido de aprovação do MCP.

RealtimeItemStatus

Status dos itens de conversa.

Valores permitidos:

• in_progress - Atualmente em processamento
• completed - Concluído com sucesso
• incomplete - Incompleto (interrompido ou reprovado)

RealtimeContentPart

Parte de conteúdo dentro de uma mensagem.

RealtimeInputTextContentPart

Parte de conteúdo de texto.

RealtimeOutputTextContentPart

Parte de conteúdo de texto.

RealtimeInputAudioContentPart

Parte de conteúdo de áudio.

RealtimeOutputAudioContentPart

Parte de 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á a ser gerada
• completed - Resposta concluída com sucesso
• cancelled - Resposta cancelada
• incomplete - Resposta incompleta (interrompida)
• failed - Resposta falhou com erro

RealtimeUsage

Estatísticas de uso de tokens.

TokenDetails

Detalhamento detalhado 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 .

Este é 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 como usada 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 em tempo real. 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 guia de início rápido para agentes de voz ao vivo
• Saiba mais sobre como usar a API ao vivo do Voice