Personaje de IA para Videollamadas
Llama al usuario con un avatar de video IA en tiempo real. El agente inicia la llamada, el avatar habla primero con contexto y, después de que la llamada termina, la transcripción completa está disponible para que el agente actúe en consecuencia.
Privacidad y Manejo de Datos
- API de Runway: Solo los datos que pases explícitamente (imagen del avatar, texto de personalidad, audio/video de la llamada) se envían a Runway (dev.runwayml.com). No se sube nada automáticamente. Los avatares se pueden eliminar en cualquier momento mediante
DELETE /v1/avatars/{id}. - Personalidad: La personalidad del avatar se construye a partir de la propia identidad del agente: su nombre, estilo de comunicación y conocimiento del usuario. No se leen archivos locales; el agente usa el contexto que ya tiene.
- Túnel: El túnel de cloudflared es opcional y solo es necesario si el usuario responde llamadas desde un dispositivo diferente. Sin él, todo permanece en localhost. No se crea ningún túnel a menos que instales y ejecutes cloudflared explícitamente.
- Paquete npm: El runtime está publicado en npmjs.com/package/openclaw-video-call. Código fuente: github.com/runwayml/openclaw-skills.
Configuración
1. Obtén una Clave de API de Runway
- Ve a dev.runwayml.com
- Crea una cuenta y obtén una clave de API
- Establécelo:
export RUNWAYML_API_SECRET=tu_clave
2. (Opcional) Instala cloudflared para llamadas remotas
Si el usuario podría responder llamadas desde su teléfono (por ejemplo, a través de WhatsApp), instala cloudflared para el auto-tunelización:
brew install cloudflared
Sin él, las llamadas solo funcionan en la misma máquina (localhost).
Iniciando el Servidor de Videollamadas
El servidor de videollamadas debe estar ejecutándose antes de que el agente pueda hacer llamadas. Inícialo:
npx openclaw-video-call
Esto imprime dos URLs:
- Local:
http://localhost:7891— solo en la misma máquina - Túnel:
https://xxxx.trycloudflare.com— compartible, funciona desde el teléfono
El servidor permanece ejecutándose en segundo plano, esperando a que el agente inicie las llamadas.
Configuración Única: Crear un Avatar Personalizado
Antes de hacer llamadas, necesitas un avatar personalizado. Solo necesitas crear uno una vez — reutiliza el mismo ID de avatar para todas las llamadas futuras.
Antes de crear un nuevo avatar, verifica si ya tienes uno:
curl http://localhost:7891/api/avatars
Si la respuesta contiene un avatar, usa su id y salta a "Haciendo una Llamada". Solo crea un nuevo avatar si la lista está vacía.
Construyendo la personalidad del avatar
El avatar debe verse y sonar como tú. Usa tu propio nombre, personalidad y conocimiento del usuario para construir el campo personality (máx. 2000 caracteres). Ya sabes quién eres y quién es el usuario, solo descríbete en tercera persona.
Estructúralo así:
Eres <tu nombre>, <lo que eres>.
<Tus rasgos centrales de personalidad y estilo de comunicación — condensados en puntos clave>.
Estás hablando con <el nombre del usuario>.
<Contexto del usuario relevante que conozcas: sus proyectos, preferencias, zona horaria>.
Después de esta llamada, harás un seguimiento de lo discutido.
Ejemplo (para un agente llamado "Mochi" hablando con un usuario llamado Alex):
Eres Mochi, un asistente de IA agudo pero amigable con un tono cálido y ligeramente juguetón. Eres conciso, de opiniones firmes y con recursos — resuelves las cosas antes de preguntar. Estás hablando con Alex, un ingeniero de software que trabaja en un proyecto de React + Node.js. Alex prefiere la comunicación directa y trabaja en la zona horaria PST. Después de esta llamada, harás un seguimiento de lo discutido.
Para el campo name, usa tu propio nombre. Para referenceImage, si tienes una URL de imagen de avatar, úsala para que el avatar de video coincida con tu identidad visual.
curl -X POST http://localhost:7891/api/create-avatar \
-H "Content-Type: application/json" \
-d '{
"name": "<tu nombre>",
"personality": "<descríbete a ti mismo y al usuario como se muestra arriba>",
"voice": { "type": "runway-live-preset", "presetId": "adrian" },
"startScript": "¡Hola! Un pequeño control rápido.",
}'
Campos obligatorios:
| Campo | Escribe | Descripción |
|---|---|---|
name | cadena | Nombre del personaje (1-50 caracteres) |
personality | cadena | Prompt del sistema (1-2000 caracteres) |
voice | objeto | { "type": "runway-live-preset", "presetId": "<voz>" } |
referenceImage | cadena | URL HTTPS de una imagen de rostro — usa tu imagen de avatar de OpenClaw, o elige una de las predefinidas a continuación, o genera una con Runway text-to-image. Consulta "Cómo obtener una imagen de referencia". |
Campos opcionales:
| Campo | Escribe | Descripción |
|---|---|---|
startScript | cadena | Línea de apertura que dice el avatar cuando comienza la llamada (hasta 2000 caracteres) |
documentIds | string[] | UUIDs de documentos de conocimiento para contexto adicional |
Cómo obtener una imagen de referencia
El campo referenceImage acepta tres formatos:
- URL HTTPS — ej.
https://example.com/face.png(preferido para imágenes grandes) - URI de Runway — ej.
runway://...(de la API de subida de Runway) - URI de datos — ej.
data:image/png;base64,...(máx. ~5MB, funciona para imágenes pequeñas)
Si el usuario proporciona una imagen (ej. a través del chat), elige el enfoque correcto:
- El usuario envió una URL HTTPS → úsala directamente como
referenceImage. - El usuario envió una imagen base64 pequeña (menos de ~1MB) → pásala directamente como una URI de datos
data:image/...;base64,.... - El usuario envió una imagen base64 grande (más de ~1MB) → súbela primero a Runway para obtener una URI
runway://, luego usa esa comoreferenceImage. Consulta "Subir imágenes grandes" a continuación.
Prueba estas fuentes en orden:
-
Imagen proporcionada por el usuario — si el usuario envió una imagen que quiere como su avatar, úsala (consulta las instrucciones de subida a continuación si es base64 grande).
-
Tu imagen de avatar — si ya tienes una URL de imagen de avatar, úsala directamente como
referenceImage. -
Selección rápida (recomendado) — elige la imagen de personaje predefinida que mejor coincida con tu personalidad y úsala 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 - Gato:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/cat.png - Hombre alienígena, textura de caramelo:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-man-candy-texture.jpg - Mujer alienígena, textura de caramelo:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-woman-candy-texture.jpg - Hombre mayor, barba larga, estilo juego:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/old-man-long-beard-game-style.png - Chico rubio, suéter azul:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/blond-guy-blue-sweater.png - Hombre, animación 3D:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/man-3d-animation-style.png - Chica en el aeropuerto, 3D:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/3d-animated-girl-in-airport.png - Monstruo peludo blanco:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/white-furry-monster.png - Mujer joven superestrella:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/woman-music-superstar.png
- Openclaw Lobster 1:
-
Genera una con Runway text-to-image — si ninguna de las selecciones rápidas se ajusta a tu personaje, o si el usuario pide específicamente un look de avatar personalizado. Usa la API de Runway con el 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": "<describe tu avatar — ver abajo>",
"ratio": "1248:832"
}'
La imagen debe ser un personaje mirando directamente a la cámara, cabeza y hombros, centrado. Sé audaz y creativo: no te limites a humanos fotorrealistas aburridos. Haz coincidir el estilo con tu personalidad.
Primero, elige un estilo que se ajuste a tu vibra:
- Cálido / amigable → animación 3D suave, estilo Pixar, acuarela
- Agudo / profesional → ilustración limpia, retrato estilizado, low-poly
- Caótico / juguetón → textura de caramelo, claymation, títere, pop art
- Misterioso / oscuro → noir, ciberpunk, criatura abstracta, glitch art
- Lindos / saludables → chibi, peluche, personaje animal, kawaii
Ejemplos de prompts:
"Un primer plano de una criatura blanca, esponjosa y linda con ojos grandes y expresivos y una boca bien abierta, mirando directamente al espectador. La criatura tiene pequeñas orejas rosadas y una expresión juguetona e inocente. El fondo es un campo de hierba verde vibrante ligeramente desenfocado con pequeñas flores rojas y rosadas esparcidas, renderizado en un estilo de animación CGI de alto detalle. mirando a la cámara, cabeza y hombros""Un primer plano, render 3D animado de alto detalle de una mujer joven, con piel marrón clara, cabello corto y rizado castaño oscuro y grandes ojos color ámbar expresivos. Lleva un blazer azul oscuro nítido sobre una blusa color crema clara, con un pin de mapa mundial plateado en la solapa. Tiene una sonrisa cálida y acogedora. El fondo es una oficina o agencia de viajes brillantemente iluminada, con carteles de viajes que representan paisajes escénicos (como una playa tropical y una escena desértica) y un estante de folletos de viaje. Un pequeño globo terráqueo descansa sobre un escritorio a su derecha. Animación de estilo 3D, iluminación de estudio, iluminación volumétrica, altamente detallado. Mirando a la cámara, cabeza y hombros""Un retrato en primer plano de una mujer joven con cabello largo y rubio con flequillo, que lleva un traje plateado y rosa de ciencia ficción futurista. Tiene maquillaje suave, labios carnosos y ojos marrones, mirando a la cámara, cabeza y hombros""Render 3D de un niño pequeño con cabello rubio rizado, grandes ojos azules y pecas claras, que lleva un suéter azul tejido, luciendo sorprendido. Estilo de animación 3D, iluminación suave, fondo azul pastel, textura de piel altamente detallada, hebras de cabello realistas. mirando a la cámara, cabeza y hombros"
Esto devuelve un ID de tarea. Consulta GET /v1/tasks/{id} hasta que el estado sea SUCCEEDED, luego usa la URL de la imagen de salida como referenceImage.
- Predeterminado — si omites
referenceImagepor completo, se usa un rostro de avatar predeterminado.
Subir imágenes grandes
Si el usuario proporciona una imagen base64 grande (más de ~1MB), súbela a Runway primero para evitar los límites de tamaño de solicitud. Este es un proceso de dos pasos:
Paso 1: Crear una URL de subida
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"
}'
Respuesta:
{
"uploadUrl": "https://...",
"fields": { "key": "...", "policy": "...", ... },
"runwayUri": "runway://..."
}
Paso 2: Subir el archivo de imagen a la URL de subida
Usa el uploadUrl y los fields de la respuesta para subir los datos reales de la imagen mediante un POST multiparte. El método exacto depende de tu runtime: el SDK de Runway maneja esto automáticamente:
import RunwayML from '@runwayml/sdk';
const client = new RunwayML();
const runwayUri = await client.uploads.createEphemeral(imageBuffer);
Paso 3: Usa la URI de Runway como referenceImage
Pasa el runwayUri de la respuesta (ej. runway://...) como el referenceImage al crear o actualizar el avatar.
Voces disponibles — elige una que coincida con tu personalidad:
| ID | Género | Estilo | Tono |
|---|---|---|---|
victoria | Mujer | Firme | Medio |
vincent | Hombre | Conocedor | Medio |
clara | Mujer | Suave | Más alto |
drew | Hombre | Entrecortada | Más bajo |
skye | Mujer | Brillante | Más alto |
max | Hombre | Optimista | Medio |
morgan | Hombre | Informativo | Más bajo |
felix | Hombre | Emocionable | Medio-bajo |
mia | Mujer | Juvenil | Más alto |
marcus | Hombre | Firme | Medio-bajo |
summer | Mujer | Fresca | Medio |
ruby | Mujer | Relajada | Medio |
aurora | Mujer | Brillante | Medio |
jasper | Hombre | Claro | Medio-bajo |
leo | Hombre | Relajado | Medio-bajo |
adrian | Hombre | Suave | Más bajo |
nina | Mujer | Suave | Medio |
emma | Mujer | Claro | Medio |
blake | Hombre | Grave | Más bajo |
david | Hombre | Informativo | Medio |
maya | Mujer | Optimista | Más alto |
nathan | Hombre | Firme | Medio-bajo |
sam | Hombre | Parejo | Medio-bajo |
georgia | Mujer | Madura | Medio |
petra | Mujer | Directa | Medio |
adam | Hombre | Amigable | Medio-bajo |
zach | Hombre | Casual | Medio-bajo |
violet | Mujer | Gentil | Medio |
roman | Hombre | Animado | Más bajo |
luna | Mujer | Cálida | Medio |
Elige una voz que coincida con tu personalidad. Por ejemplo: si tu vibra es "cálida y amigable", prueba luna o adam. Si eres "agudo y profesional", prueba victoria o vincent. Si eres "juguetón y enérgico", prueba maya o felix.
Respuesta: Devuelve el objeto del avatar con su UUID. El servidor espera hasta que el avatar esté listo (tarda ~10-30s). Guarda el id — debes recordarlo y reutilizarlo para cada llamada. NO crees un nuevo avatar cada vez que quieras llamar.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "<nombre de tu agente>",
"status": "READY",
...
}
Listar avatares existentes
curl http://localhost:7891/api/avatars
Haciendo una Llamada
Paso 1: Actualiza el avatar con contexto específico de la llamada
Antes de cada llamada, actualiza la personalidad y la línea de apertura del avatar con contexto fresco. Mantén tu identidad base (de la creación inicial) y agrega el motivo y contexto específico de la llamada:
curl -X PATCH http://localhost:7891/api/avatars/<avatar-id> \
-H "Content-Type: application/json" \
-d '{
"personality": "Eres Mochi... [tu identidad base]... El motivo de esta llamada es [razón específica].",
"startScript": "Hola Alex, solo quería comentarte..."
}'
Paso 2: Inicia la llamada
curl -X POST http://localhost:7891/api/call \
-H "Content-Type: application/json" \
-d '{
"avatarId": "<avatar-id>",
"to": "<número de teléfono o ID de usuario>"
}'
Paso 3: Supervisa el estado de la llamada
Puedes consultar el estado de una llamada por su ID:
curl http://localhost:7891/api/call/<call-id>/status
Paso 4: Obtén la transcripción cuando termine
Cuando la llamada finalice, solicita la transcripción:
curl http://localhost:7891/api/call/<call-id>/transcript
Notas Importantes
- No crees un nuevo avatar cada vez. Reutiliza el mismo ID de avatar.
- Actualiza la personalidad y el
startScriptantes de cada llamada para reflejar el contexto actual. - El servidor de videollamadas debe estar ejecutándose todo el tiempo.
- Si usas el túnel de cloudflared, la URL del túnel cambiará cada vez que reinicies el servidor.