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 funcionalidades avançadas, incluindo reconhecimento de voz, síntese de texto para fala, streaming de avatares, dados de animação e capacidades abrangentes de processamento áudio.

A API utiliza eventos em formato JSON enviados através de ligações WebSocket para gerir conversas, fluxos de áudio, interações com avatares 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 múltiplos formatos de áudio, incluindo PCM16 a várias taxas de amostragem e codecs G.711
• Opções Avançadas de Voz: Vozes OpenAI, vozes Azure personalizadas, vozes Azure padrão e vozes Azure pessoais
• Integração com Avatar: Streaming de avatares baseado em WebRTC com vídeo, animação e blendshapes
• Deteção Inteligente de Curvas: Múltiplas opções de VAD, incluindo Azure VAD semântica e deteção do lado do servidor
• Melhoria de Áudio: Redução de ruído e cancelamento de eco incorporados
• Chamada de Funções: Integração de ferramentas para capacidades conversacionais aprimoradas
• 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. Note que, uma vez que uma sessão é inicializada com um modelo em particular, 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 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 ligação avatar fornecendo a oferta SDP (Session Description Protocol) do cliente para negociação de media WebRTC. Este evento é obrigatório quando se utilizam as funcionalidades do avatar.

Event Structure

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

Properties

input_audio_buffer.append

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

Event Structure

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

Properties

input_audio_buffer.commit

Compromete o buffer de áudio de entrada para processamento.

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

Limpa 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. Isto pode incluir mensagens, chamadas de função e respostas de chamadas de função. Os itens podem ser inseridos em posições específicas no histórico da conversa.

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

Recupera um item específico do histórico da conversa. Isto é útil para inspecionar áudio processado após cancelamento de ruído e VAD.

Event Structure

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

Properties

conversation.item.truncate

Trunque o conteúdo áudio de uma mensagem de assistente. Isto é útil para interromper a reprodução num ponto específico e sincronizar a compreensão 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

Instruir o servidor a criar uma resposta através de inferência de modelo. Este evento pode especificar uma configuração específica de resposta que sobrepõe os valores predefinidos da 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 curso. Isto interrompe imediatamente a geração de respostas e a saída de áudio relacionada.

Event Structure

{
  "type": "response.cancel"
}

Properties

input_audio_buffer.append

O evento cliente input_audio_buffer.append é usado para adicionar bytes de áudio ao buffer de áudio de entrada. O buffer de áudio é um armazenamento temporário onde podes escrever e depois fazer commit.

No modo Server VAD (Deteção de Atividade de Voz), o buffer de áudio é usado para detetar a fala e o servidor decide quando comprometer. Quando o VAD do servidor está desativado, o cliente pode escolher quanto áudio colocar em cada evento até um máximo de 15 MiB. Por exemplo, transmitir pequenos blocos 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 .

Event structure

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

Properties

input_audio_buffer.clear

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.

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

input_audio_buffer.commit

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

Quando está em modo VAD de servidor, o cliente não precisa de enviar este evento, o servidor faz commit automático do buffer de áudio. Sem o VAD do servidor, o cliente tem de comprometer o buffer de áudio para criar um item de mensagem do utilizador. Este evento 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 sucesso. Este é o primeiro evento recebido após a ligação à 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 sucesso 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 está a ser estabelecida uma ligação avatar WebRTC. Este evento é enviado em resposta a um session.avatar.connect evento de um cliente.

Event Structure

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

Properties

conversation.item.created

Enviado quando um novo item é adicionado à conversa, seja através de um evento 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 de 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 servidor conversation.item.truncated é devolvido quando o cliente trunca um item de mensagem áudio assistente anterior com um conversation.item.truncate evento. Este evento é usado para sincronizar a compreensão do áudio pelo servidor com a reprodução do cliente.

Este evento trunca o áudio e remove a transcrição do texto do lado do servidor para garantir que não há texto no contexto que o utilizador desconheç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 começa uma nova geração de resposta. Este é o primeiro evento numa 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 utilização.

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 está completo.

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 do servidor response.content_part.added é devolvido quando uma nova parte de conteúdo é adicionada a um item de mensagem assistente durante a geração da 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 do servidor response.content_part.done é devolvido quando uma parte do conteúdo termina de ser transmitida num item de mensagem de assistente.

Este evento também é devolvido 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

Conteúdo de texto em streaming 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

Conteúdo áudio em streaming a partir 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 á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 em streaming do conteúdo á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 á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 a fala escrita no buffer de áudio.

A transcrição começa quando o buffer de áudio de entrada é comprometido pelo cliente ou servidor (em server_vad modo). A transcrição corre de forma assíncrona com a criação de respostas, pelo que este evento pode ocorrer antes ou depois dos eventos de resposta.

Os modelos de API em tempo real aceitam áudio nativamente, e assim a transcrição de entrada é um processo separado executado num modelo de reconhecimento de voz distinto, 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 do servidor conversation.item.input_audio_transcription.delta é devolvido quando a transcrição áudio de entrada é configurada e está em curso um pedido de transcrição para uma mensagem de utilizador. Este evento fornece resultados parciais de transcrição à medida que se tornam 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 é devolvido quando a transcrição áudio de entrada é configurada e um pedido de transcrição para uma mensagem de utilizador falhou. Este evento é separado dos 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 do servidor response.animation_blendshapes.delta é devolvido quando o modelo gera dados de blendshapes de animação como parte de uma resposta. Este evento fornece dados incrementais de blendshapes à medida que se tornam 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 do servidor response.animation_blendshapes.done é devolvido quando o modelo termina de gerar dados de blendshapes 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 do servidor response.audio_timestamp.delta é devolvido quando o modelo gera dados de carimbo temporal de áudio como parte de uma resposta. Este evento fornece dados incrementais de carimbo temporal para o alinhamento de áudio e texto de saída à medida que se torna 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 do timestamp 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 do servidor response.animation_viseme.delta é devolvido quando o modelo gera dados de visema de animação como parte de uma resposta. Este evento fornece dados incrementais do visema à 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 do servidor response.animation_viseme.done é devolvido quando o modelo termina de gerar os dados do visema de animação 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 é devolvido quando ocorre um erro, que pode ser um problema do cliente ou do servidor. A maioria dos erros é recuperável e a sessão mantém-se 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 é devolvido 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 é devolvido quando um buffer de áudio de entrada é confirmado, seja pelo cliente ou automaticamente em modo VAD do servidor. A item_id propriedade é o ID do item de mensagem do utilizador criado. Assim, um conversation.item.created evento também é enviado ao 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 é devolvido em server_vad modo quando a fala é detetada no buffer de áudio. Este evento pode acontecer sempre que áudio é 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 cessar. A item_id propriedade é o ID do item de mensagem do utilizador criado quando a fala para. Também item_id é incluído no input_audio_buffer.speech_stopped evento, a menos que o cliente comprometa 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 é devolvido em 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 utilizador 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 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 aqui apresentados refletem essa reserva, que é então ajustada em conformidade assim que a resposta é 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 do servidor response.audio.delta é devolvido 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 do servidor response.audio.done é devolvido quando o áudio gerado pelo modelo termina.

Este evento também é devolvido 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 do servidor response.audio_transcript.delta é devolvido 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 do servidor response.audio_transcript.done é devolvido quando a transcrição gerada pelo modelo da saída de áudio termina o streaming.

Este evento também é devolvido 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 servidor response.function_call_arguments.delta é devolvido 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 do servidor response.function_call_arguments.done é devolvido quando os argumentos das chamadas de função gerados pelo modelo terminam de ser transmitidos.

Este evento também é devolvido 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 termina 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 do servidor response.output_item.added é devolvido quando um novo item é criado durante a geração da resposta.

Event structure

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

Properties

response.output_item.done

O evento do servidor response.output_item.done é devolvido quando um item termina de ser transmitido.

Este evento também é devolvido 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 do servidor response.text.delta é devolvido quando o texto gerado pelo modelo é atualizado. O texto corresponde à text parte de conteúdo de um item de mensagem 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 do servidor response.text.done é devolvido quando o texto gerado pelo modelo termina de ser transmitido. O texto corresponde à text parte de conteúdo de um item de mensagem assistente.

Este evento também é devolvido 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 base de áudio usado para áudio de entrada.

Allowed Values:

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

RealtimeOutputAudioFormat

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

Allowed Values:

• pcm16 - Formato de áudio PCM de 16 bits à taxa de amostragem padrão (24kHz)
• pcm16_8000hz - Formato de áudio PCM de 16 bits a uma taxa de amostragem de 8kHz
• pcm16_16000hz - Formato de áudio PCM de 16 bits a uma taxa de amostragem de 16kHz
• 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 com taxa de amostragem de 8kHz

RealtimeAudioInputTranscriptionSettings

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

RealtimeInputAudioNoiseReductionSettings

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

Voice Configuration

RealtimeVoice

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

Isto 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. Trata-se de uma união discriminada com diferentes tipos:

RealtimeAzureStandardVoice

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

RealtimeAzureCustomVoice

Configuração de voz personalizada do Azure (preferida 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

Azure Personal Voice Configuration.

Turn Detection

RealtimeTurnDetection

Configuração para deteção de curvas. Trata-se de um sindicato discriminado que suporta múltiplos tipos de VAD.

RealtimeServerVAD

Deteção de curva baseada em VAD base.

RealtimeOpenAISemanticVAD

Configuração semântica de VAD OpenAI, que utiliza um modelo para determinar quando o utilizador terminou de falar. Disponível apenas para gpt-realtime modelos.gpt-realtime-mini

RealtimeAzureSemanticVAD

Azure Semantic VAD, que determina quando o utilizador começa a falar usando um modelo semântico de fala, proporcionando uma deteção mais robusta em ambientes ruidosos.

RealtimeAzureSemanticVADMultilingual

Azure semântic VAD (variante padrão).

RealtimeEOUDetection

O Azure End-of-Sentence (EOU) podia indicar quando o utilizador final parava de falar, permitindo pausas naturais. A deteção de fim de enunciação pode reduzir significativamente os sinais de fim de viragem prematuros sem adicionar latência percetível pelo utilizador.

Avatar Configuration

RealtimeAvatarConfig

Configuração para streaming de avatar e comportamento.

RealtimeIceServer

Configuração do servidor ICE para negociação de ligação WebRTC.

RealtimeVideoParams

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

RealtimeVideoCrop

Definição de retângulo de corte em 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 visemas.

RealtimeAnimationOutputType

Tipos de dados de animação a produzir.

Allowed Values:

• blendshapes - Dados de blendshapes 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 - Produção de animação
• avatar - Saída de vídeo Avatar

RealtimeAudioTimestampType

Tipos de carimbo temporal de saída suportados em conteúdos de resposta áudio.

Allowed Values:

• word - Timestamps por palavra no áudio de saída

ReasoningEffort

Limita o esforço de 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 numa 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ções.

RealtimeToolChoice

Estratégia de seleção de ferramentas.

Isto pode ser:

• "auto" - Deixe o modelo escolher
• "none" - Não uses ferramentas
• "required" - Deve usar uma ferramenta
• { "type": "function", "name": "function_name" } - Utilizar funções específicas

MCPTool

Configuração da ferramenta MCP.

RealtimeConversationResponseItem

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

RealtimeConversationUserMessageItem

Item de mensagem do utilizador.

RealtimeConversationAssistantMessageItem

Item da mensagem do assistente.

RealtimeConversationSystemMessageItem

Item da mensagem do sistema.

RealtimeConversationFunctionCallItem

Item de pedido de chamada de função.

RealtimeConversationFunctionCallOutputItem

Item de resposta de chamada funcional.

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

Estado dos pontos de conversa.

Allowed Values:

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

RealtimeContentPart

Parte de conteúdo dentro de uma mensagem.

RealtimeInputTextContentPart

Parte do conteúdo textual.

RealtimeOutputTextContentPart

Parte do conteúdo textual.

RealtimeInputAudioContentPart

Parte do conteúdo áudio.

RealtimeOutputAudioContentPart

Parte do conteúdo áudio.

Response Objects

RealtimeResponse

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

RealtimeResponseStatus

Valores de estado de resposta.

Allowed Values:

• in_progress - A resposta está a ser gerada
• completed - Resposta concluída com sucesso
• canceled - A resposta foi cancelada
• incomplete - Resposta incompleta (interrompida)
• failed - Resposta falhada com erro

RealtimeUsage

Estatísticas de utilização de tokens.

TokenDetails

Análise detalhada do uso do token.

Error Handling

RealtimeErrorDetails

Objeto de informação de erro.

RealtimeConversationRequestItem

Usas o RealtimeConversationRequestItem objeto para criar um novo item na conversa através 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 utilizador.

RealtimeAssistantMessageItem

Um item de mensagem de assistente.

RealtimeFunctionCallItem

Um item de chamada de função.

RealtimeFunctionCallOutputItem

Uma função chama item de saída.

RealtimeMCPApprovalResponseItem

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

RealtimeFunctionTool

A definição de uma ferramenta de função utilizada pelo endpoint em tempo real.

RealtimeItemStatus

Allowed Values:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

O RealtimeResponseSession objeto representa uma sessão na API de Tempo Real. É usado em alguns dos eventos do servidor, tais como:

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Related Resources

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