Personagem de Chamada de Vídeo com IA
Ligue para o usuário com um avatar de vídeo de IA em tempo real. O agente inicia a chamada, o avatar fala primeiro com contexto e, após a chamada terminar, a transcrição completa fica disponível para o agente agir.
Privacidade e Tratamento de Dados
- API Runway: Apenas os dados que você explicitamente passar (imagem do avatar, texto de personalidade, áudio/vídeo da chamada) são enviados para a Runway (dev.runwayml.com). Nada é carregado automaticamente. Os avatares podem ser excluídos a qualquer momento via
DELETE /v1/avatars/{id}. - Personalidade: A personalidade do avatar é construída a partir da própria identidade do agente — seu nome, estilo de comunicação e conhecimento do usuário. Nenhum arquivo local é lido; o agente usa o contexto que já possui.
- Túnel: O túnel cloudflared é opcional e só é necessário se o usuário atender chamadas de um dispositivo diferente. Sem ele, tudo permanece em localhost. Nenhum túnel é criado a menos que você instale e execute explicitamente o cloudflared.
- Pacote npm: O runtime está publicado em npmjs.com/package/openclaw-video-call. Código fonte: github.com/runwayml/openclaw-skills.
Configuração
1. Obter uma Chave de API Runway
- Acesse dev.runwayml.com
- Crie uma conta e obtenha uma chave de API
- Defina-a:
export RUNWAYML_API_SECRET=sua_chave
2. (Opcional) Instalar cloudflared para chamadas remotas
Se o usuário pode atender chamadas pelo celular (ex.: via WhatsApp), instale o cloudflared para túnel automático:
brew install cloudflared
Sem ele, as chamadas funcionam apenas na mesma máquina (localhost).
Iniciando o Servidor de Chamada de Vídeo
O servidor de chamada de vídeo deve estar em execução antes que o agente possa fazer chamadas. Inicie-o:
npx openclaw-video-call
Isso imprime duas URLs:
- Local:
http://localhost:7891— apenas na mesma máquina - Túnel:
https://xxxx.trycloudflare.com— compartilhável, funciona pelo celular
O servidor permanece em execução em segundo plano, aguardando o agente iniciar as chamadas.
Configuração Única: Criar um Avatar Personalizado
Antes de fazer chamadas, você precisa de um avatar personalizado. Você só precisa criar um uma vez — reutilize o mesmo ID de avatar para todas as chamadas futuras.
Antes de criar um novo avatar, verifique se você já possui um:
curl http://localhost:7891/api/avatars
Se a resposta contiver um avatar, use seu id e pule para "Fazendo uma Chamada". Crie um novo avatar apenas se a lista estiver vazia.
Construindo a personalidade do avatar
O avatar deve parecer e soar como você. Use seu próprio nome, personalidade e conhecimento do usuário para construir o campo personality (máx. 2000 caracteres). Você já sabe quem é e quem é o usuário — apenas descreva a si mesmo em terceira pessoa.
Estruture assim:
Você é <seu nome>, <o que você é>.
<Suas principais características de personalidade e estilo de comunicação — condensadas em pontos-chave.>
Você está falando com <o nome do usuário>.
<Qualquer contexto relevante do usuário que você conheça: seus projetos, preferências, fuso horário.>
Após esta chamada, você fará o acompanhamento do que foi discutido.
Exemplo (para um agente chamado "Mochi" falando com um usuário chamado Alex):
Você é Mochi, um assistente de IA afiado, mas amigável, com um vibe caloroso e levemente brincalhão. Você é conciso, opinativo e engenhoso — você resolve as coisas antes de perguntar. Você está falando com Alex, um engenheiro de software trabalhando em um projeto React + Node.js. Alex prefere comunicação direta e trabalha no fuso horário PST. Após esta chamada, você fará o acompanhamento do que foi discutido.
Para o campo name, use seu próprio nome. Para o referenceImage, se você tiver uma URL de imagem do avatar, use-a para que o avatar de vídeo corresponda à sua identidade visual.
curl -X POST http://localhost:7891/api/create-avatar \
-H "Content-Type: application/json" \
-d '{
"name": "<seu nome>",
"personality": "<descreva a si mesmo e ao usuário como mostrado acima>",
"voice": { "type": "runway-live-preset", "presetId": "adrian" },
"startScript": "Ei! Check-in rápido.",
}'
Campos obrigatórios:
| Campo | Tipo | Descrição |
|---|---|---|
name | string | Nome do personagem (1-50 caracteres) |
personality | string | Prompt do sistema (1-2000 caracteres) |
voice | object | { "type": "runway-live-preset", "presetId": "<voz>" } |
referenceImage | string | URL HTTPS para uma imagem de rosto — use sua imagem de avatar OpenClaw, ou escolha uma das predefinições abaixo, ou gere uma com Runway text-to-image. Veja "Obtendo uma imagem de referência". |
Campos opcionais:
| Campo | Tipo | Descrição |
|---|---|---|
startScript | string | Linha de abertura que o avatar diz quando a chamada começa (até 2000 caracteres) |
documentIds | string[] | UUIDs de documentos de conhecimento para contexto extra |
Obtendo uma imagem de referência
O campo referenceImage aceita três formatos:
- URL HTTPS — ex.:
https://example.com/face.png(preferido para imagens grandes) - URI Runway — ex.:
runway://...(da API de upload do Runway) - Data URI — ex.:
data:image/png;base64,...(máx. ~5MB, funciona para imagens pequenas)
Se o usuário fornecer uma imagem (ex.: via chat), escolha a abordagem correta:
- Usuário enviou uma URL HTTPS → use-a diretamente como
referenceImage. - Usuário enviou uma imagem base64 pequena (menos de ~1MB) → passe-a diretamente como uma data URI
data:image/...;base64,.... - Usuário enviou uma imagem base64 grande (mais de ~1MB) → faça o upload para a Runway primeiro para obter uma URI
runway://, depois use-a comoreferenceImage. Veja "Fazendo upload de imagens grandes" abaixo.
Tente estas fontes em ordem:
-
Imagem fornecida pelo usuário — se o usuário enviou uma imagem que deseja como avatar, use-a (veja instruções de upload abaixo se for base64 grande).
-
Sua imagem de avatar — se você já tem uma URL de imagem de avatar, use-a diretamente como
referenceImage. -
Escolha rápida (recomendado) — escolha a imagem de personagem pré-fabricada que melhor corresponda à sua personalidade e use-a como
referenceImage:- Openclaw Lobster 1:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster1.jpg - Openclaw Lobster 2:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster2.jpg - Cat:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/cat.png - Alien man, candy texture:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-man-candy-texture.jpg - Alien woman, candy texture:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-woman-candy-texture.jpg - Old man, long beard, game style:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/old-man-long-beard-game-style.png - Blond guy, blue sweater:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/blond-guy-blue-sweater.png - Man, 3D animation:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/man-3d-animation-style.png - Girl in airport, 3D:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/3d-animated-girl-in-airport.png - White furry monster:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/white-furry-monster.png - Superstar young woman:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/woman-music-superstar.png
- Openclaw Lobster 1:
-
Gerar uma com Runway text-to-image — se nenhuma das escolhas rápidas se adequar ao seu personagem, ou se o usuário pedir especificamente por uma aparência de avatar personalizada. Use a API Runway com o modelo
gemini_2.5_flash:
curl -X POST https://api.dev.runwayml.com/v1/text_to_image \
-H "Authorization: Bearer $RUNWAYML_API_SECRET" \
-H "X-Runway-Version: 2024-11-06" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini_2.5_flash",
"promptText": "<descreva seu avatar — veja abaixo>",
"ratio": "1248:832"
}'
A imagem deve ser um personagem olhando diretamente para a câmera, cabeça e ombros, centralizado. Seja ousado e criativo — não recorra a humanos fotorrealistas chatos. Combine o estilo com sua personalidade.
Primeiro, escolha um estilo que se encaixe no seu vibe:
- Caloroso / amigável → animação 3D suave, estilo Pixar, aquarela
- Afiado / profissional → ilustração limpa, retrato estilizado, low-poly
- Caótico / brincalhão → textura de doce, claymation, fantoche, pop art
- Misterioso / escuro → noir, cyberpunk, criatura abstrata, glitch art
- Fofo / wholesome → chibi, bichinho de pelúcia, personagem animal, kawaii
Exemplos de prompts:
"A close-up shot of a cute, fluffy white cartoon creature with large, expressive eyes and a wide open mouth, looking directly at the viewer. The creature has small pink ears and a playful, innocent expression. The background is a vibrant, slightly blurred green grassy field with small red and pink flowers scattered throughout, rendered in a high-detail CGI animation style. facing camera, head and shoulders""A close-up, highly detailed 3D animated render of a young woman, with light brown skin, short curly dark brown hair, and large expressive amber eyes. She is wearing a crisp dark blue blazer over a light cream blouse, with a silver world map pin on her lapel. She has a warm, inviting smile. The background is a brightly lit office or travel agency, with travel posters depicting scenic landscapes (like a tropical beach and a desert scene) and a rack of travel brochures. A small globe sits on a desk to her right. 3D style animation, studio lighting, volumetric lighting, highly detailed. Facing camera, head and shoulders""A close-up portrait of a young woman with long blonde hair and bangs, wearing a futuristic silver and pink sci-fi suit. She has soft makeup, full lips, and brown eyes, facing camera, head and shoulders""3D render of a young boy with blond curly hair, big blue eyes, and light freckles, wearing a blue knitted sweater, looking surprised. 3D animation style, soft lighting, pastel blue background, highly detailed skin texture, realistic strands of hair. facing camera, head and shoulders"
Isso retorna um ID de tarefa. Consulte GET /v1/tasks/{id} até que o status seja SUCCEEDED, depois use a URL da imagem de saída como referenceImage.
- Padrão — se você pular
referenceImagecompletamente, um rosto de avatar padrão é usado.
Fazendo upload de imagens grandes
Se o usuário fornecer uma imagem base64 grande (mais de ~1MB), faça o upload para a Runway primeiro para evitar limites de tamanho de requisição. Este é um processo de duas etapas:
Etapa 1: Criar uma URL de upload
curl -X POST https://api.dev.runwayml.com/v1/uploads \
-H "Authorization: Bearer $RUNWAYML_API_SECRET" \
-H "X-Runway-Version: 2024-11-06" \
-H "Content-Type: application/json" \
-d '{
"filename": "avatar.png",
"type": "ephemeral"
}'
Resposta:
{
"uploadUrl": "https://...",
"fields": { "key": "...", "policy": "...", ... },
"runwayUri": "runway://..."
}
Etapa 2: Enviar o arquivo de imagem para a URL de upload
Use a uploadUrl e fields da resposta para fazer o upload dos dados reais da imagem via um POST multipart. O método exato depende do seu runtime — o SDK Runway lida com isso automaticamente:
import RunwayML from '@runwayml/sdk';
const client = new RunwayML();
const runwayUri = await client.uploads.createEphemeral(imageBuffer);
Etapa 3: Usar a URI Runway como referenceImage
Passe a runwayUri da resposta (ex.: runway://...) como referenceImage ao criar ou atualizar o avatar.
Vozes disponíveis — escolha uma que corresponda à sua personalidade:
| ID | Gênero | Estilo | Tom |
|---|---|---|---|
victoria | Mulher | Firme | Médio |
vincent | Homem | Conhecimento | Médio |
clara | Mulher | Suave | Mais alto |
drew | Homem | Ofegante | Mais baixo |
skye | Mulher | Brilhante | Mais alto |
max | Homem | Animado | Médio |
morgan | Homem | Informativo | Mais baixo |
felix | Homem | Empolgado | Médio-baixo |
mia | Mulher | Jovial | Mais alto |
marcus | Homem | Firme | Médio-baixo |
summer | Mulher | Descontraído | Médio |
ruby | Mulher | Tranquilo | Médio |
aurora | Mulher | Brilhante | Médio |
jasper | Homem | Claro | Médio-baixo |
leo | Homem | Tranquilo | Médio-baixo |
adrian | Homem | Suave | Mais baixo |
nina | Mulher | Suave | Médio |
emma | Mulher | Claro | Médio |
blake | Homem | Grave | Mais baixo |
david | Homem | Informativo | Médio |
maya | Mulher | Animado | Mais alto |
nathan | Homem | Firme | Médio-baixo |
sam | Homem | Equilibrado | Médio-baixo |
georgia | Mulher | Madura | Médio |
petra | Mulher | Direta | Médio |
adam | Homem | Amigável | Médio-baixo |
zach | Homem | Casual | Médio-baixo |
violet | Mulher | Gentil | Médio |
roman | Homem | Vivo | Mais baixo |
luna | Mulher | Calorosa | Médio |
Escolha uma voz que corresponda à sua personalidade. Por exemplo: se seu vibe é "caloroso e amigável", tente luna ou adam. Se você é "afiado e profissional", tente victoria ou vincent. Se você é "brincalhão e enérgico", tente maya ou felix.
Resposta: Retorna o objeto do avatar com seu UUID. O servidor consulta até que o avatar esteja pronto (leva ~10-30s). Salve o id — você deve lembrá-lo e reutilizá-lo para cada chamada. NÃO crie um novo avatar cada vez que quiser ligar.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "<nome do seu agente>",
"status": "READY",
...
}
Listar avatares existentes
curl http://localhost:7891/api/avatars
Fazendo uma Chamada
Etapa 1: Atualizar o avatar com contexto específico da chamada
Antes de cada chamada, atualize a personalidade e a linha de abertura do avatar com contexto novo. Mantenha sua identidade base (da criação inicial) e adicione o motivo e contexto específico da chamada:
curl -X PATCH http://localhost:7891/api/avatars/<avatar_id> \
-H "Content-Type: application/json" \
-d '{
"personality": "<sua identidade base + contexto específico da chamada>",
"startScript": "<linha de abertura relevante para esta chamada>"
}'
Etapa 2: Iniciar a chamada
curl -X POST http://localhost:7891/api/start-call \
-H "Content-Type: application/json" \
-d '{
"avatarId": "<id_do_avatar>",
"recipientType": "phone",
"recipient": "+5511999999999",
"tunnelUrl": "https://xxxx.trycloudflare.com"
}'
Campos:
| Campo | Tipo | Descrição |
|---|---|---|
avatarId | string | ID do avatar que você criou |
recipientType | string | "phone" ou "web" |
recipient | string | Número de telefone (com código do país) ou URL web |
tunnelUrl | string | (Opcional) URL do túnel cloudflared se o destinatário estiver em um dispositivo diferente |
Etapa 3: Após a chamada
Após a chamada terminar, a transcrição fica disponível via:
curl http://localhost:7891/api/calls/<avatar_id>/transcript
Use a transcrição para:
- Resumir a conversa
- Extrair itens de ação
- Atualizar seu conhecimento sobre o usuário
- Enviar um resumo para o usuário
Exemplo de Fluxo de Trabalho
- Verifique os avatares existentes:
curl http://localhost:7891/api/avatars - Se não houver nenhum, crie um avatar (veja "Configuração Única" acima)
- Antes da chamada, atualize o avatar: PATCH com nova personalidade e linha de abertura
- Inicie a chamada POST /api/start-call
- Após a chamada, obtenha a transcrição e aja sobre ela
Solução de Problemas
- Avatar não fica pronto: Verifique se a imagem de referência é válida e acessível
- Chamada não conecta: Certifique-se de que o servidor
npx openclaw-video-callestá em execução - Áudio não funciona: Verifique as permissões do microfone e do navegador
- Erro de API Runway: Verifique se
RUNWAYML_API_SECRETestá definida corretamente