Compétence de Génération Vidéo
Cette compétence guide l'implémentation de fonctionnalités de génération vidéo à l'aide du 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 des tâches.
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 {Skill Location}/scripts/ pour des tests rapides et une référence. Voir {Skill Location}/scripts/video.ts pour un exemple fonctionnel.
Vue d'Ensemble
La génération vidéo vous permet de créer des applications capables de produire du contenu vidéo à partir de textes ou d'images, avec des paramètres personnalisables comme la résolution, la fréquence d'images, la durée et les réglages de qualité. L'API utilise un modèle de tâche asynchrone où vous créez une tâche et interrogez les résultats.
IMPORTANT : z-ai-web-dev-sdk DOIT être utilisé uniquement dans du code backend. Ne l'utilisez jamais 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 CLI (Pour les Tâches Simples)
Pour les tâches simples de génération vidéo, vous pouvez utiliser la CLI z-ai au lieu d'écrire du code. La CLI gère automatiquement la création de tâches et l'interrogation, ce qui est idéal pour des tests rapides et une automatisation simple.
Texte-vers-Vidéo de Base
# Générer une vidéo avec interrogation automatique
z-ai video --prompt "Un chat jouant avec une balle" --poll
# Utilisation des options courtes
z-ai video -p "Beau paysage avec des montagnes" --poll
Qualité et Réglages Personnalisés
# Mode qualité (speed ou quality)
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 urbain" \
--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 URL. Cette approche est plus fiable et évite les problèmes de réseau ou les restrictions d'accès potentiels.
Remarque : 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 les 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 "Faire revivre 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 "Faire revivre 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 "Faire revivre la scène" \
--poll
# Utilisation d'une URL (moins recommandé, 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 URL. Assurez-vous que le type MIME correspond au 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'URL (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 "Tempête qui approche" \
--with-audio \
--poll
Sauvegarder la Sortie
# Sauvegarder le résultat de la tâche dans un fichier JSON
z-ai video \
-p "Lever de soleil sur les montagnes" \
--poll \
-o video_result.json
Paramètres d'Interrogation Personnalisés
# Personnaliser le comportement d'interrogation
z-ai video \
-p "Robot dansant" \
--poll \
--poll-interval 10 \
--max-polls 30
# Créer une tâche sans interrogation (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 exemple, "data:image/png;base64,iVBORw..."). Les URL sont également prises en charge 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 exemple, "1920x1080")--fps <taux>: Optionnel - Fréquence d'images : 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 - Interrogation automatique jusqu'à la fin de la tâche--poll-interval <secondes>: Optionnel - Intervalle d'interrogation (par défaut : 5)--max-polls <nombre>: Optionnel - Nombre maximal de tentatives d'interrogation (par défaut : 60)--output, -o <chemin>: Optionnel - Chemin du fichier de sortie (format JSON)
Résolutions Prise en Charge
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(et autres résolutions standard)
Vérification du Statut de la Tâche Plus Tard
Si vous créez une tâche sans --poll, vous pouvez vérifier son statut plus tard :
# Obtenir l'ID de la tâche à partir de la réponse initiale
z-ai async-result --id "task-id-here" --poll
Quand Utiliser CLI vs SDK
Utilisez la CLI pour :
- Tests rapides de génération vidéo
- Création vidéo unique et simple
- Scripts d'automatisation en ligne de commande
- Test de 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 des 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 modèle asynchrone en deux étapes :
- Créer une Tâche : Soumettre une demande de génération vidéo et recevoir un ID de tâche
- Interroger les Résultats : Interroger le statut de la tâche jusqu'à son achèvement et récupérer l'URL de la vidéo
Implémentation de Base 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' or 'quality'
with_audio: false,
size: '1920x1080',
fps: 30,
duration: 5
});
console.log('ID de la Tâche :', task.id);
console.log('Statut de la Tâche :', task.task_status);
// Interroger 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(`Interrogation ${pollCount}/${maxPolls} : Statut 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 de la vidéo à partir de plusieurs champs possibles
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
console.log('URL de la 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 les données d'image encodées en base64 et les URL, mais l'encodage base64 est fortement recommandé pour une meilleure fiabilité et pour éviter les 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 les 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 à partir de l'extension de 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 : Utilisation d'une image encodée en base64 (RECOMMANDÉ)
// Détection automatique du type MIME à partir de l'extension de 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 : Utilisation d'une URL (moins recommandé)
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 à ceci'
);
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 URL 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 à partir de l'extension de 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 : Utilisation d'images encodées en base64 (RECOMMANDÉ)
// Détection automatique du 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 : Utilisation d'URL (moins recommandé)
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 le Statut 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('Statut de la Tâche :', result.task_status);
if (result.task_status === 'SUCCESS') {
// Extraire l'URL de la vidéo du résultat
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
if (videoUrl) {
console.log('URL de la 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 la vérification du statut :', error.message);
throw error;
}
}
// Utilisation
const taskStatus = await checkTaskStatus('votre-id-de-tâche-ici');
if (taskStatus.success) {
console.log('Vidéo disponible à :', taskStatus.url);
}
Fonction d'Interrogation Complète avec Timeout
import ZAI from 'z-ai-web-dev-sdk';
async function pollForResult(taskId, maxRetries = 60, delayMs = 5000) {
const zai = await ZAI.create();
for (let attempt = 1; attempt <= maxRetries; attempt++) {
console.log(`Tentative d'interrogation ${attempt}/${maxRetries}...`);
const result = await zai.async.result.query(taskId);
if (result.task_status === 'SUCCESS') {
console.log('Tâche terminée avec succès !');
return result;
}
if (result.task_status === 'FAIL') {
throw new Error('La tâche a échoué');
}
if (attempt < maxRetries) {
console.log(`Toujours en cours de traitement, nouvelle tentative dans ${delayMs/1000} secondes...`);
await new Promise(resolve => setTimeout(resolve, delayMs));
}
}
throw new Error('Délai d'attente dépassé : la tâche n\'est pas terminée dans le nombre maximal de tentatives');
}
Guide de Référence Rapide des Paramètres
| Paramètre | Type | Par Défaut | Description |
|---|---|---|---|
prompt | string | requis | Description textuelle de la vidéo |
image_url | string/string[] | optionnel | Base64 ou URL de l'image source |
quality | 'speed' | 'quality' | 'speed' |
with_audio | boolean | false | Activer les effets audio générés par IA |
size | string | '1920x1080' | Résolution vidéo |
fps | number | 30 | Fréquence d'images (30 ou 60) |
duration | number | 5 | Durée en secondes (5 ou 10) |
model | string | optionnel | Modèle spécifique à utiliser |
Dépannage
Problèmes Courants
-
Échec de l'encodage base64 : Assurez-vous que le type MIME dans votre URI de données correspond exactement au format de l'image. Utilisez la fonction utilitaire
getMimeTypefournie. -
Erreurs réseau : Lorsque vous utilisez des URL au lieu de base64, assurez-vous que l'URL est accessible publiquement et ne nécessite pas d'authentification.
-
Délai d'attente des tâches : Les vidéos plus longues ou de qualité supérieure peuvent prendre plus de temps à traiter. Ajustez les paramètres
maxPollsetpollIntervalen conséquence. -
Réponses vides : Si la réponse ne contient pas d'URL vidéo, vérifiez les différents noms de champs possibles (
video_result,video_url,url,video).
Exemples de Scripts
Des exemples de scripts de test sont disponibles dans le répertoire {Skill Location}/scripts/ :
video.ts: Exemple complet de génération vidéo texte-vers-vidéo et image-vers-vidéo
Pour exécuter les exemples :
cd {Skill Location}
npx ts-node scripts/video.ts