Compétence Génération Vidéo
Cette compétence guide la mise en œuvre de fonctionnalités de génération vidéo en utilisant le package z-ai-web-dev-sdk, permettant aux modèles d'IA de créer des vidéos à partir de descriptions textuelles ou d'images via un traitement asynchrone.
Chemin de la Compétence
Emplacement de la Compétence : {project_path}/skills/video-generation
Cette compétence se trouve au chemin ci-dessus dans votre projet.
Scripts de Référence : Des scripts de test d'exemple sont disponibles dans le répertoire {Emplacement de la Compétence}/scripts/ pour des tests rapides et une référence. Voir {Emplacement de la Compétence}/scripts/video.ts pour un exemple fonctionnel.
Aperçu
La Génération Vidéo permet de construire des applications capables de créer du contenu vidéo à partir de textes ou d'images, avec des paramètres personnalisables comme la résolution, le taux d'images par seconde, la durée et les réglages de qualité. L'API utilise un modèle asynchrone de tâches où vous créez une tâche et sondez les résultats.
IMPORTANT : z-ai-web-dev-sdk DOIT être utilisé uniquement dans du code backend. Ne jamais l'utiliser dans du code côté client.
Prérequis
Le package z-ai-web-dev-sdk est déjà installé. Importez-le comme indiqué dans les exemples ci-dessous.
Utilisation en Ligne de Commande (pour des Tâches Simples)
Pour des tâches simples de génération vidéo, vous pouvez utiliser la ligne de commande z-ai au lieu d'écrire du code. La CLI gère la création de la tâche et le sondage automatiquement, ce qui la rend idéale pour des tests rapides et de l'automatisation simple.
Texte-vers-Vidéo Basique
# Générer une vidéo avec sondage automatique
z-ai video --prompt "Un chat jouant avec une balle" --poll
# Utiliser des options courtes
z-ai video -p "Beau paysage avec des montagnes" --poll
Qualité et Réglages Personnalisés
# Mode qualité (vitesse ou qualité)
z-ai video -p "Vagues de l'océan au coucher du soleil" --quality quality --poll
# Résolution et FPS personnalisés
z-ai video \
-p "Time-lapse de la ville" \
--size "1920x1080" \
--fps 60 \
--poll
# Durée personnalisée (5 ou 10 secondes)
z-ai video -p "Feu d'artifice" --duration 10 --poll
Image-vers-Vidéo
IMPORTANT : Pour le paramètre image_url, il est fortement recommandé d'utiliser des données d'image encodées en base64 plutôt que des URLs. Cette approche est plus fiable et évite les problèmes de réseau ou de restrictions d'accès potentiels.
Note : Faites correspondre le type MIME dans l'URI de données à votre format d'image réel (image/jpeg, image/png, image/webp, etc.) pour éviter des problèmes de décodage.
# Générer une vidéo à partir d'une seule image en utilisant base64 (RECOMMANDÉ)
# Convertissez votre image en base64 avec le bon type MIME
# Pour les images PNG
IMAGE_BASE64=$(base64 -i image.png)
z-ai video \
--image-url "data:image/png;base64,${IMAGE_BASE64}" \
--prompt "Animer la scène" \
--poll
# Pour les images JPEG
IMAGE_BASE64=$(base64 -i photo.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${IMAGE_BASE64}" \
--prompt "Animer la scène" \
--poll
# Pour les images WebP
IMAGE_BASE64=$(base64 -i image.webp)
z-ai video \
--image-url "data:image/webp;base64,${IMAGE_BASE64}" \
--prompt "Animer la scène" \
--poll
# Utilisation d'une URL (moins recommandée, peut avoir des problèmes de fiabilité)
z-ai video \
-i "https://example.com/photo.jpg" \
-p "Ajouter du mouvement à cette scène" \
--poll
Mode Première-Dernière Image
IMPORTANT : Pour une meilleure fiabilité, utilisez des images encodées en base64 plutôt que des URLs. Assurez-vous que le type MIME correspond à votre format d'image réel.
# Générer une vidéo entre deux images en utilisant base64 (RECOMMANDÉ)
# Assurez-vous d'utiliser le bon type MIME pour chaque image
# Exemple avec des images PNG
START_BASE64=$(base64 -i start.png)
END_BASE64=$(base64 -i end.png)
z-ai video \
--image-url "data:image/png;base64,${START_BASE64},data:image/png;base64,${END_BASE64}" \
--prompt "Transition fluide entre les images" \
--poll
# Exemple avec des images JPEG
START_BASE64=$(base64 -i start.jpg)
END_BASE64=$(base64 -i end.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${START_BASE64},data:image/jpeg;base64,${END_BASE64}" \
--prompt "Transition fluide entre les images" \
--poll
# Utilisation d'URLs (moins recommandé)
z-ai video \
--image-url "https://example.com/start.png,https://example.com/end.png" \
--prompt "Transition fluide entre les images" \
--poll
Avec Génération Audio
# Générer une vidéo avec des effets audio générés par IA
z-ai video \
-p "Orage approchant" \
--with-audio \
--poll
Sauvegarder la Sortie
# Sauvegarder le résultat de la tâche dans un fichier JSON
z-ai video \
-p "Lever du soleil sur les montagnes" \
--poll \
-o video_result.json
Paramètres de Sondage Personnalisés
# Personnaliser le comportement de sondage
z-ai video \
-p "Robot dansant" \
--poll \
--poll-interval 10 \
--max-polls 30
# Créer une tâche sans sondage (obtenir l'ID de tâche)
z-ai video -p "Animation d'art abstrait" -o task.json
Paramètres CLI
--prompt, -p <texte>: Optionnel - Description textuelle de la vidéo--image-url, -i <données>: Optionnel - De préférence des données d'image encodées en base64 (par ex., "data:image/png;base64,iVBORw..."). Les URLs sont également supportées mais moins recommandées. Pour deux images, utilisez des valeurs séparées par des virgules.--quality, -q <mode>: Optionnel - Mode de sortie :speedouquality(par défaut : speed)--with-audio: Optionnel - Générer des effets audio IA (par défaut : false)--size, -s <résolution>: Optionnel - Résolution vidéo (par ex., "1920x1080")--fps <taux>: Optionnel - Taux d'images par seconde : 30 ou 60 (par défaut : 30)--duration, -d <secondes>: Optionnel - Durée : 5 ou 10 secondes (par défaut : 5)--model, -m <modèle>: Optionnel - Nom du modèle à utiliser--poll: Optionnel - Sondage automatique jusqu'à la fin de la tâche--poll-interval <secondes>: Optionnel - Intervalle de sondage (par défaut : 5)--max-polls <nombre>: Optionnel - Nombre maximum de tentatives de sondage (par défaut : 60)--output, -o <chemin>: Optionnel - Chemin du fichier de sortie (format JSON)
Résolutions Supportées
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(et autres résolutions standard)
Vérification de l'État de la Tâche Plus Tard
Si vous créez une tâche sans --poll, vous pouvez vérifier son état plus tard :
# Obtenir l'ID de tâche depuis la réponse initiale
z-ai async-result --id "task-id-ici" --poll
Quand Utiliser la CLI vs le SDK
Utilisez la CLI pour :
- Tests rapides de génération vidéo
- Création vidéo ponctuelle simple
- Scripts d'automatisation en ligne de commande
- Tester différents prompts et réglages
Utilisez le SDK pour :
- Génération vidéo par lots avec logique personnalisée
- Intégration avec des applications web
- Gestion personnalisée de files d'attente de tâches
- Applications de production avec des workflows complexes
Workflow de Génération Vidéo
La génération vidéo suit un motif asynchrone en deux étapes :
- Créer la Tâche : Soumettre une demande de génération vidéo et recevoir un ID de tâche
- Sonder les Résultats : Interroger l'état de la tâche jusqu'à son achèvement et récupérer l'URL vidéo
Mise en Œuvre Basique de la Génération Vidéo
Génération Texte-vers-Vidéo Simple
import ZAI from 'z-ai-web-dev-sdk';
async function generateVideo(prompt) {
try {
const zai = await ZAI.create();
// Créer une tâche de génération vidéo
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'speed', // 'speed' ou 'quality'
with_audio: false,
size: '1920x1080',
fps: 30,
duration: 5
});
console.log('ID de tâche :', task.id);
console.log('État de la tâche :', task.task_status);
// Sonder les résultats
let result = await zai.async.result.query(task.id);
let pollCount = 0;
const maxPolls = 60;
const pollInterval = 5000; // 5 secondes
while (result.task_status === 'PROCESSING' && pollCount < maxPolls) {
pollCount++;
console.log(`Sondage ${pollCount}/${maxPolls} : L'état est ${result.task_status}`);
await new Promise(resolve => setTimeout(resolve, pollInterval));
result = await zai.async.result.query(task.id);
}
if (result.task_status === 'SUCCESS') {
// Obtenir l'URL vidéo depuis plusieurs champs possibles
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
console.log('URL vidéo :', videoUrl);
return videoUrl;
} else {
console.log('La tâche a échoué ou est toujours en cours de traitement');
return null;
}
} catch (error) {
console.error('La génération vidéo a échoué :', error.message);
throw error;
}
}
// Utilisation
const videoUrl = await generateVideo('Un chat joue avec une balle.');
console.log('Vidéo générée :', videoUrl);
Génération Image-vers-Vidéo
IMPORTANT : Le paramètre image_url accepte à la fois des données d'image encodées en base64 et des URLs, mais l'encodage base64 est fortement recommandé pour une meilleure fiabilité et pour éviter des problèmes liés au réseau.
Critique : Faites toujours correspondre le type MIME dans votre URI de données base64 au format d'image réel pour éviter des erreurs de décodage.
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
// Fonction utilitaire pour détecter le type MIME depuis l'extension du fichier
function getMimeType(filePath) {
const ext = path.extname(filePath).toLowerCase();
const mimeTypes = {
'.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg',
'.png': 'image/png',
'.gif': 'image/gif',
'.webp': 'image/webp',
'.bmp': 'image/bmp'
};
return mimeTypes[ext] || 'image/jpeg'; // Par défaut JPEG si inconnu
}
async function generateVideoFromImage(imagePath, prompt) {
const zai = await ZAI.create();
// Méthode 1 : Utiliser une image encodée en base64 (RECOMMANDÉ)
// Détecter automatiquement le type MIME depuis l'extension du fichier
const imageBuffer = fs.readFileSync(imagePath);
const mimeType = getMimeType(imagePath);
const base64Image = `data:${mimeType};base64,${imageBuffer.toString('base64')}`;
const task = await zai.video.generations.create({
image_url: base64Image, // Chaîne de données base64 avec le bon type MIME
prompt: prompt,
quality: 'quality',
duration: 5,
fps: 30
});
return task;
}
// Méthode 2 : Utiliser une URL (moins recommandée)
async function generateVideoFromImageUrl(imageUrl, prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
image_url: imageUrl, // Chaîne URL
prompt: prompt,
quality: 'quality',
duration: 5,
fps: 30
});
return task;
}
// Exemples d'utilisation
const task1 = await generateVideoFromImage(
'./images/photo.jpg', // Fonctionne avec JPEG
'Animer cette scène avec un mouvement doux'
);
const task2 = await generateVideoFromImage(
'./images/graphic.png', // Fonctionne avec PNG
'Ajouter un mouvement dynamique'
);
const task3 = await generateVideoFromImage(
'./images/animation.webp', // Fonctionne avec WebP
'Donner vie à cette scène'
);
Image-vers-Vidéo avec Images de Début et de Fin
IMPORTANT : Pour le mode image clé, les images encodées en base64 sont fortement recommandées par rapport aux URLs pour garantir une génération vidéo cohérente et fiable. Utilisez toujours le bon type MIME pour chaque image.
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
// Fonction utilitaire pour détecter le type MIME depuis l'extension du fichier
function getMimeType(filePath) {
const ext = path.extname(filePath).toLowerCase();
const mimeTypes = {
'.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg',
'.png': 'image/png',
'.gif': 'image/gif',
'.webp': 'image/webp',
'.bmp': 'image/bmp'
};
return mimeTypes[ext] || 'image/jpeg';
}
async function generateVideoWithKeyframes(startImagePath, endImagePath, prompt) {
const zai = await ZAI.create();
// Méthode 1 : Utiliser des images encodées en base64 (RECOMMANDÉ)
// Détecter automatiquement le type MIME pour chaque image
const startBuffer = fs.readFileSync(startImagePath);
const endBuffer = fs.readFileSync(endImagePath);
const startMimeType = getMimeType(startImagePath);
const endMimeType = getMimeType(endImagePath);
const startBase64 = `data:${startMimeType};base64,${startBuffer.toString('base64')}`;
const endBase64 = `data:${endMimeType};base64,${endBuffer.toString('base64')}`;
const task = await zai.video.generations.create({
image_url: [startBase64, endBase64], // Tableau de chaînes base64 avec les bons types MIME
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30
});
console.log('Tâche créée avec images clés :', task.id);
return task;
}
// Méthode 2 : Utiliser des URLs (moins recommandée)
async function generateVideoWithKeyframesUrl(startImageUrl, endImageUrl, prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
image_url: [startImageUrl, endImageUrl], // Tableau de chaînes URL
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30
});
console.log('Tâche créée avec images clés :', task.id);
return task;
}
// Exemples d'utilisation avec différents formats
const task1 = await generateVideoWithKeyframes(
'./frames/start.jpg', // Image de début JPEG
'./frames/end.jpg', // Image de fin JPEG
'Transition fluide entre ces scènes'
);
const task2 = await generateVideoWithKeyframes(
'./frames/start.png', // Image de début PNG
'./frames/end.webp', // Image de fin WebP - différents formats fonctionnent !
'Effet de morphing entre les images'
);
Gestion des Résultats Asynchrones
Interroger l'État de la Tâche
import ZAI from 'z-ai-web-dev-sdk';
async function checkTaskStatus(taskId) {
try {
const zai = await ZAI.create();
const result = await zai.async.result.query(taskId);
console.log('État de la tâche :', result.task_status);
if (result.task_status === 'SUCCESS') {
// Extraire l'URL vidéo du résultat
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
if (videoUrl) {
console.log('URL vidéo :', videoUrl);
return { success: true, url: videoUrl };
}
} else if (result.task_status === 'PROCESSING') {
console.log('La tâche est toujours en cours de traitement');
return { success: false, status: 'processing' };
} else if (result.task_status === 'FAIL') {
console.log('La tâche a échoué');
return { success: false, status: 'failed' };
}
} catch (error) {
console.error('Erreur lors de l\'interrogation de la tâche :', error.message);
throw error;
}
}
// Utilisation
const result = await checkTaskStatus('task-id-123');
if (result.success) {
console.log('Vidéo prête à :', result.url);
}
Fonction de Sondage avec Timeout
import ZAI from 'z-ai-web-dev-sdk';
async function pollForCompletion(taskId, maxPolls = 60, intervalMs = 5000) {
const zai = await ZAI.create();
for (let attempt = 1; attempt <= maxPolls; attempt++) {
const result = await zai.async.result.query(taskId);
console.log(`Tentative ${attempt}/${maxPolls} : ${result.task_status}`);
switch (result.task_status) {
case 'SUCCESS':
return {
success: true,
url: result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video,
attempts: attempt
};
case 'FAIL':
return {
success: false,
status: 'failed',
attempts: attempt
};
case 'PROCESSING':
if (attempt < maxPolls) {
await new Promise(resolve => setTimeout(resolve, intervalMs));
}
break;
default:
return {
success: false,
status: result.task_status,
attempts: attempt
};
}
}
return {
success: false,
status: 'timeout',
attempts: maxPolls
};
}
// Utilisation
const video = await pollForCompletion(taskId, 30, 10000);
if (video.success) {
console.log('Vidéo générée :', video.url);
} else {
console.log('Échec de la génération :', video.status);
}
Paramètres de Configuration
| Paramètre | Type | Valeur par Défaut | Description |
|---|---|---|---|
prompt | string (optionnel) | undefined | Description textuelle de la vidéo souhaitée |
image_url | string ou string[] (optionnel) | undefined | Image(s) source(s) - Recommandé : chaînes de données base64 |
quality | string (optionnel) | speed | Mode de qualité : speed ou quality |
with_audio | boolean (optionnel) | false | Générer des effets audio par IA |
size | string (optionnel) | 1024x1024 | Résolution vidéo (voir la section Résolutions Supportées) |
fps | integer (optionnel) | 30 | Taux d'images par seconde : 30 ou 60 |
duration | integer (optionnel) | 5 | Durée en secondes : 5 ou 10 |
model | string (optionnel) | undefined | Nom du modèle spécifique |
Note : Soit
prompt, soitimage_urldoit être fourni. Les deux peuvent être utilisés ensemble pour générer des vidéos à partir d'images avec du mouvement guidé par texte.
Exemple de Script Complet
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
async function main() {
try {
const zai = await ZAI.create();
// Étape 1 : Créer une tâche de génération vidéo
console.log('Création de la tâche de génération vidéo...');
const task = await zai.video.generations.create({
prompt: 'Un paysage urbain futuriste avec des voitures volantes',
quality: 'quality',
size: '1920x1080',
fps: 30,
duration: 10
});
console.log('ID de tâche :', task.id);
// Étape 2 : Sonder les résultats
console.log('Sondage des résultats...');
const result = await pollForCompletion(task.id, 30, 5000);
if (result.success) {
console.log('✅ Vidéo générée avec succès !');
console.log('URL vidéo :', result.url);
console.log('Nombre de tentatives :', result.attempts);
} else {
console.log('❌ La génération a échoué ou a expiré :', result.status);
}
} catch (error) {
console.error('Erreur :', error.message);
process.exit(1);
}
}
async function pollForCompletion(taskId, maxPolls, intervalMs) {
// ... (même que ci-dessus)
}
main();
Dépannage
Problèmes Courants
-
Échec de la génération
- Vérifiez que l'API est accessible
- Assurez-vous que le prompt n'est pas vide et a du sens
- Vérifiez que le format de l'image est supporté
-
Timeout de la tâche
- Augmentez
maxPollssi la génération prend plus de temps que prévu - Vérifiez la charge du serveur API
- Augmentez
-
Erreurs de décodage d'image
- Assurez-vous que le type MIME dans votre chaîne base64 correspond exactement au format de l'image
- Utilisez la fonction
getMimeType()fournie pour une détection automatique fiable du type
-
URL vidéo manquante
- L'URL vidéo peut être située dans différents champs du résultat selon l'API. Vérifiez toujours les champs suivants :
result.video_result[0]?.urlresult.video_urlresult.urlresult.video
- L'URL vidéo peut être située dans différents champs du résultat selon l'API. Vérifiez toujours les champs suivants :
Meilleures Pratiques
- Toujours utiliser des images encodées en base64 pour des paramètres fiables. Les URLs peuvent échouer en raison de restrictions réseau ou d'accès.
- Mettre en œuvre une logique de nouvelle tentative pour les échecs de tâche
- Utiliser des temps de sondage adaptés à votre cas d'utilisation (50 ms pour des tâches rapides, plus longs pour des tâches complexes)
- Toujours vérifier
result.task_statusavant d'essayer d'accéder à l'URL vidéo