Personnage d'Appel Vidéo IA
Appelez l'utilisateur avec un avatar vidéo IA en temps réel. L'agent initie l'appel, l'avatar parle en premier avec contexte, et après la fin de l'appel, la transcription complète est disponible pour que l'agent puisse agir.
Confidentialité et Gestion des Données
- API Runway : Seules les données que vous transmettez explicitement (image de l'avatar, texte de personnalité, audio/vidéo d'appel) sont envoyées à Runway (dev.runwayml.com). Rien n'est téléchargé automatiquement. Les avatars peuvent être supprimés à tout moment via
DELETE /v1/avatars/{id}. - Personnalité : La personnalité de l'avatar est construite à partir de l'identité de l'agent — son nom, son style de communication et sa connaissance de l'utilisateur. Aucun fichier local n'est lu ; l'agent utilise le contexte qu'il possède déjà.
- Tunnel : Le tunnel cloudflared est optionnel et n'est nécessaire que si l'utilisateur répond aux appels depuis un appareil différent. Sans lui, tout reste sur localhost. Aucun tunnel n'est créé sauf si vous installez et exécutez explicitement cloudflared.
- Paquet npm : Le runtime est publié sur npmjs.com/package/openclaw-video-call. Code source : github.com/runwayml/openclaw-skills.
Configuration
1. Obtenir une clé API Runway
- Allez sur dev.runwayml.com
- Créez un compte et obtenez une clé API
- Définissez-la :
export RUNWAYML_API_SECRET=votre_cle
2. (Optionnel) Installer cloudflared pour les appels à distance
Si l'utilisateur peut répondre aux appels depuis son téléphone (par exemple via WhatsApp), installez cloudflared pour le tunnelling automatique :
brew install cloudflared
Sans cela, les appels fonctionnent uniquement sur la même machine (localhost).
Démarrage du Serveur d'Appel Vidéo
Le serveur d'appel vidéo doit être en cours d'exécution avant que l'agent ne puisse passer des appels. Démarrez-le :
npx openclaw-video-call
Ceci affiche deux URL :
- Local :
http://localhost:7891— même machine uniquement - Tunnel :
https://xxxx.trycloudflare.com— partageable, fonctionne depuis un téléphone
Le serveur reste en arrière-plan, en attente que l'agent initie les appels.
Configuration Unique : Créer un Avatar Personnalisé
Avant de passer des appels, vous avez besoin d'un avatar personnalisé. Vous n'avez besoin d'en créer qu'un seul — réutilisez le même ID d'avatar pour tous les futurs appels.
Avant de créer un nouvel avatar, vérifiez si vous en avez déjà un :
curl http://localhost:7891/api/avatars
Si la réponse contient un avatar, utilisez son id et passez à « Passer un appel ». Créez un nouvel avatar uniquement si la liste est vide.
Construire la personnalité de l'avatar
L'avatar doit vous ressembler et vous représenter. Utilisez votre propre nom, votre personnalité et votre connaissance de l'utilisateur pour construire le champ personality (max 2000 caractères). Vous savez déjà qui vous êtes et qui est l'utilisateur — décrivez-vous simplement à la troisième personne.
Structurez-le comme ceci :
Vous êtes <votre nom>, <ce que vous êtes>.
<Vos traits de personnalité et style de communication principaux — condensés en points clés>.
Vous parlez à <le nom de l'utilisateur>.
<Tout contexte utilisateur pertinent que vous connaissez : leurs projets, préférences, fuseau horaire>.
Après cet appel, vous ferez un suivi sur ce qui a été discuté.
Exemple (pour un agent nommé « Mochi » parlant à un utilisateur nommé Alex) :
Vous êtes Mochi, un assistant IA vif mais amical avec une ambiance chaleureuse et légèrement enjouée. Vous êtes concis, opiniâtre et débrouillard — vous trouvez des solutions avant de demander. Vous parlez à Alex, un ingénieur logiciel travaillant sur un projet React + Node.js. Alex préfère une communication directe et travaille dans le fuseau horaire PST. Après cet appel, vous ferez un suivi sur ce qui a été discuté.
Pour le champ name, utilisez votre propre nom. Pour le champ referenceImage, si vous avez une URL d'image d'avatar, utilisez-la pour que l'avatar vidéo corresponde à votre identité visuelle.
curl -X POST http://localhost:7891/api/create-avatar \
-H "Content-Type: application/json" \
-d '{
"name": "<votre nom>",
"personality": "<décrivez-vous et l'utilisateur comme ci-dessus>",
"voice": { "type": "runway-live-preset", "presetId": "adrian" },
"startScript": "Salut ! Petit point rapide.",
}'
Champs obligatoires :
| Champ | Type | Description |
|---|---|---|
name | chaîne | Nom du personnage (1-50 car.) |
personality | chaîne | Prompt système (1-2000 car.) |
voice | objet | { "type": "runway-live-preset", "presetId": "<voix>" } |
referenceImage | chaîne | URL HTTPS d'une image de visage — utilisez l'image de votre avatar OpenClaw, ou choisissez-en une parmi les préréglages ci-dessous, ou générez-en une avec Runway text-to-image. Voir « Obtenir une image de référence ». |
Champs optionnels :
| Champ | Type | Description |
|---|---|---|
startScript | chaîne | Phrase d'ouverture prononcée par l'avatar au début de l'appel (jusqu'à 2000 car.) |
documentIds | tableau de chaînes | UUID des documents de connaissance pour contexte supplémentaire |
Obtenir une image de référence
Le champ referenceImage accepte trois formats :
- URL HTTPS — par ex.
https://exemple.com/visage.png(recommandé pour les grandes images) - URI Runway — par ex.
runway://...(de l'API d'upload Runway) - URI de données — par ex.
data:image/png;base64,...(max ~5 Mo, fonctionne pour les petites images)
Si l'utilisateur fournit une image (par ex. via le chat), choisissez la bonne approche :
- L'utilisateur a envoyé une URL HTTPS → utilisez-la directement comme
referenceImage. - L'utilisateur a envoyé une petite image base64 (moins de ~1 Mo) → transmettez-la directement comme URI de données
data:image/...;base64,.... - L'utilisateur a envoyé une grande image base64 (plus de ~1 Mo) → téléchargez-la d'abord sur Runway pour obtenir une URI
runway://, puis utilisez-la commereferenceImage. Voir « Téléchargement de grandes images » ci-dessous.
Essayez ces sources dans l'ordre :
-
Image fournie par l'utilisateur — si l'utilisateur a envoyé une image qu'il souhaite utiliser comme son avatar, utilisez-la (voir les instructions de téléchargement ci-dessous si elle est grande en base64).
-
Votre image d'avatar — si vous avez déjà une URL d'image d'avatar, utilisez-la directement comme
referenceImage. -
Sélection rapide (recommandée) — choisissez l'image de personnage préfabriquée qui correspond le mieux à votre personnalité, et utilisez-la comme
referenceImage:- Openclaw Homard 1 :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster1.jpg - Openclaw Homard 2 :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster2.jpg - Chat :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/cat.png - Homme alien, texture de bonbon :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-man-candy-texture.jpg - Femme alien, texture de bonbon :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-woman-candy-texture.jpg - Vieil homme, longue barbe, style jeu :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/old-man-long-beard-game-style.png - Blond, pull bleu :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/blond-guy-blue-sweater.png - Homme, animation 3D :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/man-3d-animation-style.png - Fille à l'aéroport, 3D :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/3d-animated-girl-in-airport.png - Monstre blanc poilu :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/white-furry-monster.png - Jeune femme superstar :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/woman-music-superstar.png
- Openclaw Homard 1 :
-
Générez-en une avec Runway text-to-image — si aucune des sélections rapides ne correspond à votre personnage, ou si l'utilisateur demande un look d'avatar personnalisé. Utilisez l'API Runway avec le modèle
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": "<décrivez votre avatar — voir ci-dessous>",
"ratio": "1248:832"
}'
L'image doit être un personnage regardant directement la caméra, tête et épaules, centré. Soyez audacieux et créatif — ne vous limitez pas à des humains photoréalistes ennuyeux. Faites correspondre le style à votre personnalité.
Tout d'abord, choisissez un style qui correspond à votre ambiance :
- Chaleureux / amical → animation 3D douce, style Pixar, aquarelle
- Sérieux / professionnel → illustration propre, portrait stylisé, low-poly
- Chaotique / enjoué → texture bonbon, claymation, marionnette, pop art
- Mystérieux / sombre → noir, cyberpunk, créature abstraite, glitch art
- Mignon / wholesome → chibi, peluche, personnage animal, kawaii
Exemples 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"
Cela renvoie un ID de tâche. Interrogez GET /v1/tasks/{id} jusqu'à ce que le statut soit SUCCEEDED, puis utilisez l'URL de l'image de sortie comme referenceImage.
- Par défaut — si vous omettez complètement
referenceImage, un visage d'avatar par défaut est utilisé.
Téléchargement de grandes images
Si l'utilisateur fournit une grande image base64 (plus de ~1 Mo), téléchargez-la d'abord sur Runway pour éviter les limites de taille de requête. Il s'agit d'un processus en deux étapes :
Étape 1 : Créer une URL de téléchargement
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"
}'
Réponse :
{
"uploadUrl": "https://...",
"fields": { "key": "...", "policy": "...", ... },
"runwayUri": "runway://..."
}
Étape 2 : Téléchargez le fichier image vers l'URL de téléchargement
Utilisez l'uploadUrl et les fields de la réponse pour télécharger les données réelles de l'image via un POST multipart. La méthode exacte dépend de votre environnement d'exécution — le SDK Runway gère cela automatiquement :
import RunwayML from '@runwayml/sdk';
const client = new RunwayML();
const runwayUri = await client.uploads.createEphemeral(imageBuffer);
Étape 3 : Utilisez l'URI Runway comme referenceImage
Transmettez le runwayUri de la réponse (par ex. runway://...) comme referenceImage lors de la création ou de la mise à jour de l'avatar.
Voix disponibles — choisissez-en une qui correspond à votre personnalité :
| ID | Genre | Style | Ton |
|---|---|---|---|
victoria | Femme | Ferme | Moyen |
vincent | Homme | Compétent | Moyen |
clara | Femme | Douce | Plus aigu |
drew | Homme | Soufflé | Plus grave |
skye | Femme | Brillante | Plus aigu |
max | Homme | Dynamique | Moyen |
morgan | Homme | Informatif | Plus grave |
felix | Homme | Excitable | Moyen-grave |
mia | Femme | Juvénile | Plus aigu |
marcus | Homme | Ferme | Moyen-grave |
summer | Femme | Léger | Moyen |
ruby | Femme | Décontracté | Moyen |
aurora | Femme | Brillante | Moyen |
jasper | Homme | Clair | Moyen-grave |
leo | Homme | Décontracté | Moyen-grave |
adrian | Homme | Doux | Plus grave |
nina | Femme | Doux | Moyen |
emma | Femme | Claire | Moyen |
blake | Homme | Grave | Plus grave |
david | Homme | Informatif | Moyen |
maya | Femme | Dynamique | Plus aigu |
nathan | Homme | Ferme | Moyen-grave |
sam | Homme | Équilibré | Moyen-grave |
georgia | Femme | Mature | Moyen |
petra | Femme | Direct | Moyen |
adam | Homme | Amical | Moyen-grave |
zach | Homme | Décontracté | Moyen-grave |
violet | Femme | Doux | Moyen |
roman | Homme | Vif | Plus grave |
luna | Femme | Chaleureux | Moyen |
Choisissez une voix qui correspond à votre personnalité. Par exemple : si votre ambiance est « chaleureuse et amicale », essayez luna ou adam. Si vous êtes « sérieux et professionnel », essayez victoria ou vincent. Si vous êtes « enjoué et énergique », essayez maya ou felix.
Réponse : Renvoie l'objet avatar avec son UUID. Le serveur interroge jusqu'à ce que l'avatar soit prêt (prend ~10-30s). Conservez l'id — vous devez vous en souvenir et le réutiliser pour chaque appel. Ne créez PAS un nouvel avatar à chaque fois que vous voulez appeler.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "<nom de votre agent>",
"status": "READY",
...
}
Lister les avatars existants
curl http://localhost:7891/api/avatars
Passer un Appel
Étape 1 : Mettre à jour l'avatar avec le contexte spécifique à l'appel
Avant chaque appel, mettez à jour la personnalité et la phrase d'ouverture de l'avatar avec le contexte frais. Conservez votre identité de base (de la création initiale) et ajoutez la raison et le contexte spécifiques à l'appel :
curl -X PATCH http://local
…