Referência da API de conversa por voz em tempo real
Server events for Qwen-Audio Realtime API
Referência de eventos do servidor para a Qwen-Audio Realtime API. Todos os eventos do servidor incluem os campos event_id (gerado automaticamente pelo servidor) e type (tipo de evento).
Descrição: Retornado quando uma solicitação falha ou ocorre um erro de service. Erros de cliente (invalid_request_error) mantêm a conexão aberta. Erros de servidor (server_error) encerram a conexão.
event_idstringIdentificador exclusivo deste evento.
Copy
{ "event_id": "event_xxx", "type": "error", "error": { "type": "invalid_request_error", "code": "invalid_value", "message": "Cannot create response while another response is in progress.", "param": "response.create" }}
typestringTipo de evento. Sempre error.
errorobjectDetalhes do erro.
Properties
typestringTipo de erro, como invalid_request_error (erro de cliente) ou server_error (erro de servidor).codestringCódigo do erro.messagestringMensagem de erro.paramstringParâmetro associado ao erro.
objectstringSempre realtime.session.modelstringNome do modelo.modalitiesarrayModalidades de saída do modelo.voicestringVoz usada para geração de áudio. Pode ser um nome de voz do sistema ou o voice_id de uma voz clonada.input_audio_transcriptionobjectConfiguração de transcrição de áudio.
Properties
modelstringModelo de transcrição, como fun-asr.
turn_detectionobjectConfiguração de detecção de turno (VAD).idstringIdentificador exclusivo da sessão.
Descrição: Retornado após o processamento bem-sucedido de uma solicitação session.update. Contém a configuração completa e atualizada da sessão. Se a solicitação falhar, um evento error será retornado no lugar.
event_idstringIdentificador exclusivo deste evento.
typestringTipo de evento. Sempre input_audio_buffer.speech_stopped.
audio_end_msintegerTimestamp em milissegundos indicando o fim da fala.
item_idstringID do item de mensagem do usuário a ser criado.
reasonstringRetornado apenas no modo smart_turn. Quando definido como turn_invalid, indica que o turno atual foi classificado como inválido (sem conteúdo semântico) e a inferência não será acionada. Este campo está ausente para turnos válidos.
Descrição: Um novo item de conversa foi criado. Acionado quando o áudio do usuário é confirmado, quando o cliente cria manualmente um item ou quando uma resposta do assistente é iniciada.
event_idstringIdentificador exclusivo deste evento.
typestringTipo de evento. Sempre conversation.item.created.
previous_item_idstringID do item de conversa anterior.
itemobjectItem de conversa criado.
Properties
idstringIdentificador exclusivo do item de conversa.objectstringSempre realtime.item.typestringTipo de item: message (mensagem padrão) ou function_call (chamada de função).statusstringStatus do item, como in_progress ou completed.rolestringFunção da mensagem, como user ou assistant. Presente apenas para itens do tipo message.contentarrayLista de conteúdo da mensagem. Presente apenas para itens do tipo message.
Descrição: Um item de conversa foi recuperado com sucesso. Retornado após o cliente enviar um evento conversation.item.retrieve. Para conteúdo do tipo áudio, apenas o texto transcrito é incluído; os dados brutos de áudio não são retornados.
event_idstringIdentificador exclusivo deste evento.
typestringTipo de evento. Sempre conversation.item.retrieved.
itemobjectItem de conversa recuperado.
Properties
idstringIdentificador exclusivo do item de conversa.objectstringSempre realtime.item.typestringTipo de item: message (mensagem padrão) ou function_call (chamada de função).rolestringFunção da mensagem, como user ou assistant. Presente apenas para itens do tipo message.contentarrayLista de conteúdo da mensagem. Para conteúdo do tipo áudio, apenas o texto transcrito é incluído; os dados brutos de áudio não são retornados.
Descrição: Resultado incremental de transcrição ASR (Reconhecimento Automático de Fala), transmitido em fluxo durante o reconhecimento. Inclui informações de detecção de emoção e idioma.
event_idstringIdentificador exclusivo deste evento.
Descrição: Apenas modo smart_turn. Resultado incremental de transcrição para áudio ambiente. Quando o VAD detecta atividade de voz, mas a análise semântica classifica o turno como inválido (por exemplo, ruído de fundo ou palavras de preenchimento como "hmm" ou "uh"), o resultado do ASR é encaminhado ao cliente como um evento de ambiente. Este evento não está vinculado a nenhum item de conversa. O item_id é um ID temporário independente.
event_idstringIdentificador exclusivo deste evento.
Descrição: Apenas modo smart_turn. Resultado final da transcrição para áudio ambiente. Combinado com o evento delta correspondente para marcar o fim de um segmento de transcrição de áudio ambiente. Este resultado não é gravado no contexto da conversa.
event_idstringIdentificador exclusivo deste evento.
typestringTipo de evento. Sempre response.created.
responseobjectObjeto de resposta.
Properties
idstringIdentificador exclusivo da resposta.objectstringSempre realtime.response.statusstringStatus da resposta, como in_progress.modalitiesarrayModalidades de saída do modelo.voicestringVoz usada para geração de áudio. Pode ser um nome de voz do sistema ou o voice_id de uma voz clonada.outputarrayItens de saída da resposta. Inicialmente um array vazio.
Descrição: Um novo item de saída foi adicionado à resposta. O tipo de item de saída é message para respostas padrão ou function_call para Function Calling.
event_idstringIdentificador exclusivo deste evento.
Exemplo de item de saída de Function Calling:Quando o item de saída é uma chamada de função, os eventos response.output_item.added / conversation.item.created / response.output_item.done contêm a seguinte estrutura de item:
Uma única resposta pode incluir vários itens function_call e também pode conter saída message padrão junto com a saída function_call. A parte de Function Calling não é enviada ao TTS para reprodução de áudio.
typestringTipo de evento. Sempre response.output_item.added.
response_idstringID da resposta associada.
output_indexintegerÍndice do item de saída dentro da resposta.
itemobjectItem de saída adicionado.
Properties
idstringIdentificador exclusivo do item de saída.objectstringSempre realtime.item.typestringTipo de item de saída: message (mensagem padrão) ou function_call (chamada de função).statusstringStatus do item de saída, como in_progress.rolestringFunção da mensagem. Sempre assistant. Presente apenas para itens do tipo message.contentarrayLista de conteúdo da mensagem. Presente apenas para itens do tipo message.
Descrição: Evento de conclusão de saída de texto no modo somente texto.
event_idstringIdentificador exclusivo deste evento.
Copy
{ "event_id": "event_xxx", "type": "response.text.done", "response_id": "resp_xxx", "item_id": "item_xxx", "output_index": 0, "content_index": 0, "text": "Hello, how can I help you?"}
typestringTipo de evento. Sempre response.text.done.
response_idstringID da resposta associada.
item_idstringID do item de saída associado.
output_indexintegerÍndice do item de saída dentro da resposta.
content_indexintegerÍndice da parte de conteúdo dentro do item de saída.
Descrição: Evento de conclusão de saída de transcrição no modo de áudio.
event_idstringIdentificador exclusivo deste evento.
Copy
{ "event_id": "event_xxx", "type": "response.audio_transcript.done", "response_id": "resp_xxx", "item_id": "item_xxx", "output_index": 0, "content_index": 0, "transcript": "Hello, how can I help you?"}
typestringTipo de evento. Sempre response.audio_transcript.done.
response_idstringID da resposta associada.
item_idstringID do item de saída associado.
output_indexintegerÍndice do item de saída dentro da resposta.
content_indexintegerÍndice da parte de conteúdo dentro do item de saída.
Descrição: Um item de saída dentro da resposta foi concluído.
event_idstringIdentificador exclusivo deste evento.
Copy
{ "event_id": "event_xxx", "type": "response.output_item.done", "response_id": "resp_xxx", "output_index": 0, "item": { "id": "item_xxx", "object": "realtime.item", "type": "message", "status": "completed", "role": "assistant", "content": [ { "type": "text", "text": "Hello, how can I help you?" } ] }}
typestringTipo de evento. Sempre response.output_item.done.
response_idstringID da resposta associada.
output_indexintegerÍndice do item de saída dentro da resposta.
itemobjectItem de saída concluído com detalhes completos.
Properties
idstringIdentificador exclusivo do item de saída.objectstringSempre realtime.item.typestringTipo de item de saída: message (mensagem padrão) ou function_call (chamada de função).statusstringStatus do item de saída, como completed.rolestringFunção da mensagem. Sempre assistant. Presente apenas para itens do tipo message.contentarrayLista de conteúdo da mensagem. Presente apenas para itens do tipo message.
Descrição: Delta de argumentos de Function Calling. Quando o modelo decide invocar uma ferramenta, o servidor envia primeiro response.output_item.added (com item.type=function_call) e conversation.item.created, e então transmite fragmentos de argumentos por meio deste evento.
event_idstringIdentificador exclusivo deste evento.
Descrição: Enviado quando a saída de argumentos de Function Calling é concluída. Após receber este evento, o cliente deve: executar a ferramenta correspondente, gravar o resultado na conversa via conversation.item.create com um item function_call_output e, em seguida, enviar response.create para acionar uma nova rodada de inferência.
event_idstringIdentificador exclusivo deste evento.
idstringIdentificador exclusivo da resposta.objectstringSempre realtime.response.statusstringStatus de conclusão da resposta. Valores válidos:
completed: Concluído normalmente.
cancelled: Interrompido e cancelado. status_details.reason é turn_detected (interrupção por VAD) ou client_cancelled (cancelamento iniciado pelo cliente).
failed: Erro de LLM ou TTS.
status_detailsobjectDetalhes do status. Presente apenas quando o status é cancelled ou failed.
Properties
typestringTipo de status, como cancelled.reasonstringMotivo do cancelamento: turn_detected (interrupção por VAD) ou client_cancelled (cancelamento iniciado pelo cliente).
modalitiesarrayModalidades de saída do modelo.voicestringVoz usada para geração de áudio. Pode ser um nome de voz do sistema ou o voice_id de uma voz clonada.outputarrayLista de itens de saída na resposta, contendo objetos de item completos.
