Que fait Agent d'appel vidéo ?
Lancez un appel vidéo avec un avatar IA en temps réel. L'agent envoie un lien d'invitation à l'utilisateur, l'avatar parle en premier avec le contexte, et après 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 de l'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 cloudflared explicitement.
- Package npm : L'environnement d'exécution 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_clé
2. (Facultatif) Installer cloudflared pour les appels à distance
Si l'utilisateur peut répondre aux appels depuis son téléphone (par exemple via Telegram ou WhatsApp), installez cloudflared pour le tunnel automatique :
brew install cloudflared
Sans cela, les appels fonctionnent uniquement sur la même machine (localhost).
Démarrer le serveur d'appel vidéo
Le serveur d'appel vidéo doit être en cours d'exécution avant que l'agent 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 attendant que l'agent initie des 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, une fois — réutilisez le même ID d'avatar pour tous les appels futurs.
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". Ne créez un nouvel avatar que si la liste est vide.
Construire la personnalité de l'avatar
L'avatar doit vous ressembler et sonner comme vous. 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 essentiels — 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 astucieux mais amical avec un ton chaleureux et légèrement espiègle. Vous êtes concis, plein d'opinion 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 la 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 indiqué ci-dessus>",
"voice": { "type": "runway-live-preset", "presetId": "adrian" },
"startScript": "Salut ! Petit point rapide.",
}'
Champs obligatoires :
| Champ | Type | Description |
|---|---|---|
name | string | Nom du personnage (1-50 caractères) |
personality | string | Prompt système (1-2000 caractères) |
voice | object | { "type": "runway-live-preset", "presetId": "<voix>" } |
referenceImage | string | URL HTTPS d'une image de visage — utilisez votre image d'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 facultatifs :
| Champ | Type | Description |
|---|---|---|
startScript | string | Phrase d'ouverture que l'avatar dit au début de l'appel (jusqu'à 2000 caractères) |
documentIds | string[] | UUID des documents de connaissances pour plus de contexte |
Obtenir une image de référence
Le champ referenceImage accepte trois formats :
- URL HTTPS — par exemple
https://example.com/face.png(préféré pour les grandes images) - URI Runway — par exemple
runway://...(depuis l'API d'upload Runway) - URI de données — par exemple
data:image/png;base64,...(max ~5MB, fonctionne pour les petites images)
Si l'utilisateur fournit une image (par exemple 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 ~1MB) → passez-la directement en tant qu'URI de données
data:image/...;base64,.... - L'utilisateur a envoyé une grande image base64 (plus de ~1MB) → téléchargez-la d'abord sur Runway pour obtenir un URI
runway://, puis utilisez-le commereferenceImage. Voir "Télécharger 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 comme avatar, utilisez-la (voir les instructions de téléchargement ci-dessous si c'est une grande image 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:- Homard Openclaw 1 :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster1.jpg - Homard Openclaw 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 extraterrestre, texture bonbon :
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-man-candy-texture.jpg - Femme extraterrestre, texture 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 - Mec 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 et 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
- Homard Openclaw 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 spécifiquement 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 contentez pas des humains photoréalistes ennuyeux. Adaptez le style à votre personnalité.
Tout d'abord, choisissez un style qui correspond à votre ambiance :
- Chaleureux / amical → animation 3D douce, style Pixar, aquarelle
- Perçant / professionnel → illustration nette, portrait stylisé, low-poly
- Chaotique / enjoué → texture bonbon, claymation, marionnette, pop art
- Mystérieux / sombre → noir, cyberpunk, créature abstraite, glitch art
- Mignon / sain → chibi, peluche, personnage animal, kawaii
Exemples de prompts :
"Un plan rapproché d'une mignonne créature blanche et duveteuse avec de grands yeux expressifs et une bouche grande ouverte, regardant directement le spectateur. La créature a de petites oreilles roses et une expression joueuse et innocente. L'arrière-plan est un champ herbeux vert vif légèrement flou avec de petites fleurs rouges et roses dispersées, rendu dans un style d'animation CGI très détaillé. faisant face à la caméra, tête et épaules""Un rendu 3D animé, très détaillé et en plan rapproché d'une jeune femme, à la peau brune claire, aux cheveux crépus courts brun foncé, et aux grands yeux ambrés expressifs. Elle porte un blazer bleu foncé net sur un chemisier crème clair, avec une épingle de carte du monde argentée sur son revers. Elle a un sourire chaleureux et accueillant. L'arrière-plan est un bureau ou une agence de voyages bien éclairé, avec des affiches de voyage représentant des paysages pittoresques (comme une plage tropicale et une scène de désert) et un présentoir de brochures de voyage. Un petit globe repose sur un bureau à sa droite. Animation de style 3D, éclairage de studio, éclairage volumétrique, très détaillé. Faisant face à la caméra, tête et épaules""Un portrait en gros plan d'une jeune femme aux longs cheveux blonds et à la frange, portant une combinaison de science-fiction argentée et rose futuriste. Elle a un maquillage doux, des lèvres pulpeuses et des yeux bruns, faisant face à la caméra, tête et épaules""Rendu 3D d'un jeune garçon aux cheveux blonds bouclés, aux grands yeux bleus et aux taches de rousseur légères, portant un pull tricoté bleu, ayant l'air surpris. Style d'animation 3D, éclairage doux, fond bleu pastel, texture de peau très détaillée, mèches de cheveux réalistes. faisant face à la caméra, tête et épaules"
Ceci 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écharger de grandes images
Si l'utilisateur fournit une grande image base64 (plus de ~1MB), 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écharger le fichier image vers l'URL de téléchargement
Utilisez les champs uploadUrl et 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 : Utiliser l'URI Runway comme referenceImage
Passez le runwayUri de la réponse (par exemple runway://...) comme referenceImage lors de la création ou de la mise à jour de l'avatar.
Voix disponibles — choisissez celle qui correspond à votre personnalité :
| ID | Genre | Style | Ton |
|---|---|---|---|
victoria | Femme | Ferme | Moyen |
vincent | Homme | Savant | Moyen |
clara | Femme | Doux | Plus aigu |
drew | Homme | Sifflant | Plus grave |
skye | Femme | Lumineux | Plus aigu |
max | Homme | Entrainant | Moyen |
morgan | Homme | Informatif | Plus grave |
felix | Homme | Excitable | Plus grave-moyen |
mia | Femme | Juvénile | Plus aigu |
marcus | Homme | Ferme | Plus grave-moyen |
summer | Femme | Léger | Moyen |
ruby | Femme | Décontracté | Moyen |
aurora | Femme | Lumineux | Moyen |
jasper | Homme | Clair | Plus grave-moyen |
leo | Homme | Décontracté | Plus grave-moyen |
adrian | Homme | Doux | Plus grave |
nina | Femme | Doux | Moyen |
emma | Femme | Clair | Moyen |
blake | Homme | Grave | Plus grave |
david | Homme | Informatif | Moyen |
maya | Femme | Entrainant | Plus aigu |
nathan | Homme | Ferme | Plus grave-moyen |
sam | Homme | Égal | Plus grave-moyen |
georgia | Femme | Mature | Moyen |
petra | Femme | Direct | Moyen |
adam | Homme | Amical | Plus grave-moyen |
zach | Homme | Décontracté | Plus grave-moyen |
violet | Femme | Doux | Moyen |
roman | Homme | Vivant | Plus grave |
luna | Femme | Chaleureux | Moyen |
Choisissez une voix qui correspond à votre personnalité. Par exemple : si votre ambiance est "chaleureux et amical", essayez luna ou adam. Si vous êtes "perçant 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-30 s). Enregistrez 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 un contexte frais. Gardez votre identité de base (lors de la création initiale) et ajoutez la raison et le contexte spécifiques à l'appel :
curl -X POST http://localhost:7891/api/update-avatar/$AVATAR_ID \
-H "Content-Type: application/json" \
-d '{
"personality": "<personnalité de base mise à jour avec le contexte de cet appel>",
"startScript": "<nouvelle phrase d'ouverture reflétant la raison de cet appel>"
}'
Étape 2 : Lancer l'appel
curl -X POST http://localhost:7891/api/start-call \
-H "Content-Type: application/json" \
-d '{
"avatarId": "$AVATAR_ID",
"platform": "telegram"
}'
Étape 3 : Envoyer le lien à l'utilisateur
L'API start-call renvoie une URL de lien de l'appel que vous devez partager avec l'utilisateur. Envoyez ce lien à l'utilisateur via le canal approprié (par exemple, chat Telegram, WhatsApp, e-mail).
{
"callLink": "https://...",
"expiresIn": 3600
}
Transcrire l'appel
Après la fin de l'appel, récupérez la transcription :
curl http://localhost:7891/api/transcript/$CALL_ID
La réponse contient la transcription complète de l'appel, que l'agent peut utiliser pour un suivi ou une journalisation.
Gérer les avatars
# Supprimer un avatar
curl -X DELETE http://localhost:7891/api/delete-avatar/$AVATAR_ID
# Mettre à jour un avatar (personnalité, voix, etc.)
curl -X POST http://localhost:7891/api/update-avatar/$AVATAR_ID \
-H "Content-Type: application/json" \
-d '{
"name": "<nouveau nom>",
"personality": "<nouvelle personnalité>",
"voice": { "type": "runway-live-preset", "presetId": "<nouvelle voix>" }
}'
Débogage
- Vérifiez les journaux du serveur : le serveur
openclaw-video-callimprime les journaux dans la console. - Assurez-vous que le serveur est en cours d'exécution avant de faire des requêtes API.
- Pour les problèmes de tunnel, vérifiez que cloudflared est installé et en cours d'exécution.
- La création d'avatar nécessite une image de visage de bonne qualité — des images floues ou de mauvaise qualité peuvent échouer.
- Vérifiez l'état de l'avatar avec
GET /api/avatarsavant d'essayer de lancer un appel.