Assistente de Voz Multimodal
Nesta página
Atualizado a 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos:
tts-1,tts-1-hdegpt-4o-mini-ttsdeixarão de funcionar a 6 de janeiro de 2027 (a substituição indicada égpt-realtime-2.1-mini, que o guia TTS da OpenAI afirma não ser suportado por/v1/audio/speech: a migração da síntese de fala deve ocorrer através da API Realtime);gpt-realtime,gpt-4o-realtimee modelos de áudio legados a 20 de janeiro de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsa 26 de fevereiro de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para voz em full-duplex, o GPT-Live 1 está disponível na API desde 10 de setembro de 2026.
Corrigido a 3 de novembro de 2026. Para analisar uma imagem, a lição anterior fazia uma chamada separada à API de Respostas e injetava a descrição como uma mensagem de assistente com conteúdo
input_text, um tipo reservado a mensagens de utilizador ou de sistema. No entanto,gpt-realtime-2.1egpt-realtime-2aceitam imagens como entrada: a imagem é anexada diretamente, comoinput_image, a uma mensagem de utilizador. O eventoresponse.text.deltada antiga versão beta passou a chamar-seresponse.output_text.delta. Formatos de eventos verificados com os tipos do SDKopenai3.42.1. Fontes: Conversas em tempo real, Entradas de imagem · gpt-realtime-2.1.
Assistente de Voz Multimodal
Um assistente de voz multimodal combina a voz com outras modalidades: texto, imagens, vídeo e dados estruturados. O utilizador fala, mas o agente também pode exibir informações visuais, analisar imagens enviadas pelo utilizador ou combinar múltiplas fontes de dados. Este é o futuro da interação humano-computador.
Texto e Áudio em Paralelo
A API Realtime suporta nativamente as modalidades de texto e áudio simultaneamente. Pode injetar texto na conversa enquanto mantém a troca de voz:
async def inject_text_context(ws, context: str):
"""Adiciona contexto de texto à conversa de voz."""
await ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": context
}
]
}
}))
# Aciona uma resposta de voz com base neste contexto
await ws.send(json.dumps({"type": "response.create"}))
# O utilizador pede verbalmente "Lê-me o meu e-mail mais recente"
# Injeta o conteúdo do e-mail como texto
await inject_text_context(ws, """
Aqui está o e-mail mais recente recebido:
De: [email protected]
Assunto: Pedido de Orçamento
Conteúdo: Olá, gostaria de solicitar um orçamento para
integrar um agente de voz no nosso call center.
""")
Mostrar uma Imagem ao Agente de Voz
gpt-realtime-2.1 e gpt-realtime-2 aceitam texto, áudio e imagens como entrada. Uma imagem é anexada como uma parte input_image de uma mensagem de utilizador, usando um URI de dados Base64, tanto via WebSocket como através do canal de dados WebRTC. O modelo considera isto na sua resposta de voz, sem chamar outra API:
import base64
import json
async def mostrar_imagem(ws, caminho_imagem: str, pergunta: str) -> None:
"""Anexa uma imagem e uma pergunta à conversa e solicita uma resposta de voz."""
with open(caminho_imagem, "rb") as f:
image_b64 = base64.b64encode(f.read()).decode()
await ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [
{"type": "input_image", "image_url": f"data:image/jpeg;base64,{image_b64}"},
{"type": "input_text", "text": pergunta},
],
},
}))
await ws.send(json.dumps({"type": "response.create"}))
await mostrar_imagem(ws, "factura.jpg", "O que preciso de pagar e até que data?")
As imagens são faturadas como tokens de imagem, a uma taxa específica listada no cartão do modelo. Para análises pesadas ou para um modelo de visão mais capaz, pode ainda consultar a API de Respostas separadamente e passar o resultado para a sessão: faça-o através de uma mensagem system ou user (com conteúdo input_text), nunca através de uma mensagem de assistente falsa, que o modelo interpretaria como sendo as suas próprias palavras.
Interface Web Multimodal
Para uma aplicação web, combine o WebSocket Realtime com uma interface visual:
from fastapi import FastAPI, WebSocket
from fastapi.staticfiles import StaticFiles
app = FastAPI()
@app.websocket("/ws/agent")
async def agente_multimodal(client_ws: WebSocket):
"""Agente multimodal com interface web."""
await client_ws.accept()
headers = {
"Authorization": f"Bearer {OPENAI_API_KEY}"
}
async with websockets.connect(REALTIME_URL, additional_headers=headers) as openai_ws:
await openai_ws.recv() # session.created
await openai_ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "Assistente multimodal. Responda em inglês.",
"audio": {"output": {"voice": "marin"}}
}
}))
await openai_ws.recv()
async def cliente_para_openai():
async for message in client_ws.iter_text():
data = json.loads(message)
if data["type"] == "audio":
# Retransmite o áudio
await openai_ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": data["audio"]
}))
elif data["type"] == "text":
# Mensagem de texto (chat)
await openai_ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [{
"type": "input_text",
"text": data["text"]
}]
}
}))
await openai_ws.send(json.dumps({
"type": "response.create"
}))
async def openai_para_cliente():
async for message in openai_ws:
event = json.loads(message)
t = event["type"]
if t == "response.output_audio.delta":
await client_ws.send_json({
"type": "audio",
"delta": event["delta"]
})
elif t == "response.output_audio_transcript.delta":
await client_ws.send_json({
"type": "transcript",
"delta": event["delta"]
})
elif t == "response.output_text.delta":
await client_ws.send_json({
"type": "text",
"delta": event["delta"]
})
await asyncio.gather(cliente_para_openai(), openai_para_cliente())
Casos de Uso Multimodal
Eis como um agente multimodal lida com diferentes cenários numa ferramenta de chamada de funções:
tools = [
{
"type": "function",
"name": "show_chart",
"description": "Exibe um gráfico de dados ao utilizador",
"parameters": {
"type": "object",
"properties": {
"chart_type": {"type": "string", "enum": ["bar", "line", "pie"]},
"title": {"type": "string"},
"data": {"type": "object"}
},
"required": ["chart_type", "title", "data"]
}
},
{
"type": "function",
"name": "send_document",
"description": "Envia um documento ao cliente por e-mail",
"parameters": {
"type": "object",
"properties": {
"document_type": {"type": "string"},
"recipient": {"type": "string"}
},
"required": ["document_type", "recipient"]
}
}
]
O utilizador diz verbalmente: «Mostra-me as vendas do último trimestre num gráfico». O agente chama show_chart, o seu frontend exibe o gráfico e o agente comenta verbalmente os resultados.
Pontos-chave
- A API Realtime suporta modalidades de texto e áudio simultaneamente na mesma sessão
- Injetar texto via
conversation.item.createpermite enriquecer o contexto de voz - Os modelos Realtime aceitam imagens: anexe-as como
input_imagea uma mensagem de utilizador - Ferramentas (chamada de funções) permitem exibir elementos visuais enquanto responde verbalmente
- A arquitetura WebSocket do lado do cliente permite misturar áudio, texto e dados estruturados