Referência da API Voice Live 2025-10-01

A API Voice Live fornece comunicação bidirecional em tempo real para aplicações com voz que utilizam ligaçõ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).

Key Features

• 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
• Gestão Flexível de Sessões: Modalidades de saída, instruções e parâmetros de resposta configuráveis

Client Events

A API Voice Live suporta os seguintes eventos do cliente que podem ser enviados do cliente para o servidor:

session.update

Atualize a configuração da sessão. Este evento pode ser enviado a qualquer momento para modificar definições como voz, modalidades de saída, deteção de curvas, 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.

Event Structure

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Properties

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

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

Event Structure

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

Properties

input_audio_buffer.append

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

Event Structure

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

Properties

input_audio_buffer.commit

Confirme o buffer de áudio de entrada para processamento.

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

Limpe o buffer de áudio de entrada.

Event Structure

{
  "type": "input_audio_buffer.clear"
}

Properties

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.

Event Structure

{
  "type": "conversation.item.create",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Properties

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 saída de chamada de função

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

Exemplo com resposta de aprovação do MCP

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

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

Event Structure

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

Properties

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.

Event Structure

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

Properties

conversation.item.delete

Remova um item do histórico de conversas.

Event Structure

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

Properties

response.create

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.

Event Structure

{
  "type": "response.create",
  "response": {
    "modalities": ["text", "audio"],
    "instructions": "Be extra helpful and detailed.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "output_audio_format": "pcm16",
    "temperature": 0.7,
    "max_response_output_tokens": 1000
  }
}

Properties

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

response.cancel

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

Event Structure

{
  "type": "response.cancel"
}

Properties

input_audio_buffer.append

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 .

Event structure

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

Properties

input_audio_buffer.clear

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.

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

input_audio_buffer.commit

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.

Event structure

{
  "type": "input_audio_buffer.commit"
}

Properties

Server Events

A API Voice Live envia os seguintes eventos do servidor para comunicar estado, respostas e dados ao cliente:

session.created

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

Event Structure

{
  "type": "session.created",
  "session": {
    "id": "sess_ABC123DEF456",
    "object": "realtime.session",
    "model": "gpt-realtime",
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful assistant.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Properties

session.updated

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

Event Structure

{
  "type": "session.updated",
  "session": {
    "id": "sess_ABC123DEF456",
    "voice": {
      "type": "azure-custom",
      "name": "my-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012"
    },
    "temperature": 0.7,
    "avatar": {
      "character": "lisa",
      "customized": false
    }
  }
}

Properties

session.avatar.connecting

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

Event Structure

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

Properties

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

Event Structure

{
  "type": "conversation.item.created",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Properties

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 do cliente, fornecendo o item de conversa solicitado.

Event Structure

{
  "type": "conversation.item.retrieved",
  "item": {
    "id": "item_ABC123",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
      }
    ]
  }
}

Properties

conversation.item.truncated

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.

Event structure

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

Properties

conversation.item.deleted

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

Event Structure

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

Properties

response.created

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

Event Structure

{
  "type": "response.created",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "in_progress",
    "status_details": null,
    "output": [],
    "usage": {
      "total_tokens": 0,
      "input_tokens": 0,
      "output_tokens": 0
    }
  }
}

Properties

response.done

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.

Event Structure

{
  "type": "response.done",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "completed",
    "status_details": null,
    "output": [
      {
        "id": "item_DEF456",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
          }
        ]
      }
    ],
    "usage": {
      "total_tokens": 87,
      "input_tokens": 52,
      "output_tokens": 35,
      "input_token_details": {
        "cached_tokens": 0,
        "text_tokens": 45,
        "audio_tokens": 7
      },
      "output_token_details": {
        "text_tokens": 15,
        "audio_tokens": 20
      }
    }
  }
}

Properties

response.output_item.added

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

Event Structure

{
  "type": "response.output_item.added",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "assistant",
    "content": []
  }
}

Properties

response.output_item.done

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

Event Structure

{
  "type": "response.output_item.done",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm doing well, thank you for asking."
      }
    ]
  }
}

Properties

response.content_part.added

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.

Event Structure

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

Properties

response.content_part.done

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.

Event Structure

{
  "type": "response.content_part.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": "Hello! I'm doing well, thank you for asking."
  }
}

Properties

response.text.delta

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

Event Structure

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

Properties

response.text.done

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

Event Structure

{
  "type": "response.text.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Properties

response.audio.delta

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

Event Structure

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

Properties

response.audio.done

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

Event Structure

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

Properties

response.audio_transcript.delta

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

Event Structure

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

Properties

response.audio_transcript.done

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

Event Structure

{
  "type": "response.audio_transcript.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Properties

conversation.item.input_audio_transcription.completed

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 num modelo separado de reconhecimento de fala, como whisper-1. Assim, a transcrição pode divergir um pouco da interpretação do modelo, e deve ser tratada como um guia aproximado.

Event structure

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

Properties

conversation.item.input_audio_transcription.delta

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.

Event structure

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

Properties

conversation.item.input_audio_transcription.failed

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.

Event structure

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

Properties

Error properties

response.animation_blendshapes.delta

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.

Event structure

{
  "type": "response.animation_blendshapes.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "frame_index": 0,
  "frames": [
    [0.0, 0.1, 0.2, ..., 1.0]
    ...
  ]
}

Properties

response.animation_blendshapes.done

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.

Event structure

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

Properties

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.

Event structure

{
  "type": "response.audio_timestamp.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "audio_duration_ms": 500,
  "text": "Hello",
  "timestamp_type": "word"
}

Properties

response.audio_timestamp.done

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

Event Structure

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

Properties

response.animation_viseme.delta

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.

Event Structure

{
  "type": "response.animation_viseme.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "viseme_id": 1
}

Properties

response.animation_viseme.done

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

Event Structure

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

Properties

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.

Event structure

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

Properties

Error properties

aviso

O evento do servidor warning é devolvido quando ocorre um aviso que não interrompe o fluxo da conversa. Os avisos são informativos e a sessão continua normalmente.

Event structure

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

Properties

Warning properties

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.

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

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

Event structure

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

Properties

input_audio_buffer.speech_started

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.

Event structure

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

Properties

input_audio_buffer.speech_stopped

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.

Event structure

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

Properties

rate_limits.updated

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.

Event structure

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

Properties

response.audio.delta

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

Event structure

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

Properties

response.audio.done

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.

Event structure

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

Properties

response.audio_transcript.delta

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

Event structure

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

Properties

response.audio_transcript.done

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.

Event structure

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

Properties

response.function_call_arguments.delta

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

Event structure

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

Properties

response.function_call_arguments.done

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.

Event structure

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

Properties

mcp_list_tools.in_progress

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.

Event structure

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

Properties

mcp_list_tools.completed

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

Event structure

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

Properties

mcp_list_tools.failed

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.

Event structure

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

Properties

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.

Event structure

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

Properties

response.mcp_call_arguments.done

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

Event structure

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

Properties

response.mcp_call.in_progress

O evento do servidor response.mcp_call.in_progress é devolvido quando uma chamada de ferramenta MCP começa a ser processada.

Event structure

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

Properties

response.mcp_call.completed

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

Event structure

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

Properties

response.mcp_call.failed

O evento do servidor response.mcp_call.failed é devolvido quando uma chamada à ferramenta MCP falha.

Event structure

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

Properties

response.output_item.added

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

Event structure

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

Properties

response.output_item.done

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.

Event structure

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

Properties

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

Event structure

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

Properties

response.text.done

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.

Event structure

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

Properties

Components

Audio Formats

RealtimeAudioFormat

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

Allowed Values:

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

Allowed Values:

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

Voice Configuration

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

Example:

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

Turn Detection

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.

Avatar Configuration

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.

RealtimeAvatarScene

Configuração para o nível de zoom, posição, rotação e amplitude de movimento do avatar no quadro de vídeo.

Animation Configuration

RealtimeAnimation

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

RealtimeAnimationOutputType

Tipos de dados de animação a serem produzidos.

Allowed Values:

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

Session Configuration

RealtimeRequestSession

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

RealtimeModality

Suportava modalidades de saída de sessão.

Allowed Values:

• text - Saída de texto
• audio - 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.

Allowed Values:

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

ReasoningEffort

Restringe o esforço no raciocínio para modelos de raciocínio. Verifique a documentação dos modelos para valores suportados para cada modelo. Reduzir o esforço de raciocínio pode resultar em respostas mais rápidas e menos tokens usados no raciocínio em uma resposta.

Allowed Values:

• none - Sem esforço de raciocínio
• minimal - Esforço mínimo de raciocínio
• low - Baixo esforço de raciocínio - respostas mais rápidas com menos raciocínio
• medium - Esforço médio de raciocínio - equilibrado entre velocidade e profundidade de raciocínio
• high - Esforço de raciocínio elevado - raciocínio mais aprofundado, pode demorar mais tempo
• xhigh - Esforço de raciocínio extra elevado - profundidade máxima de raciocínio

Tool Configuration

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.

Allowed Values:

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

Response Objects

RealtimeResponse

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

RealtimeResponseStatus

Valores de status de resposta.

Allowed Values:

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

Error Handling

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

Allowed Values:

• 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

Related Resources

• Experimente o Início Rápido do Voice Live
• Experimente o início rápido dos agentes do Voice Live
• Saiba mais sobre como usar a API Voice Live