Compétence de Génération Vidéo
Cette compétence guide l'implémentation 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 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 comme référence. Voir {Skill Location}/scripts/video.ts pour un exemple fonctionnel.
Aperçu
La Génération Vidéo vous permet de construire des applications capables de créer du contenu vidéo à partir de prompts texte ou d'images, avec des paramètres personnalisables comme la résolution, le taux de rafraîchissement, 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 pour les résultats.
IMPORTANT : z-ai-web-dev-sdk DOIT être utilisé uniquement dans le code backend. Ne l'utilisez jamais dans le 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 Tâches Simples)
Pour des 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 la création de tâches et l'interrogation 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 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 de qualité (rapidité 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 URL. Cette approche est plus fiable et évite les problèmes potentiels de réseau ou de restrictions d'accès.
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 vivre 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 vivre 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 vivre 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 à 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'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(défaut : speed)--with-audio: Optionnel - Générer des effets audio IA (défaut : false)--size, -s <résolution>: Optionnel - Résolution vidéo (par exemple, "1920x1080")--fps <taux>: Optionnel - Taux de rafraîchissement : 30 ou 60 (défaut : 30)--duration, -d <secondes>: Optionnel - Durée : 5 ou 10 secondes (défaut : 5)--model, -m <modèle>: Optionnel - Nom du modèle à utiliser--poll: Optionnel - Interrogation automatique jusqu'à ce que la tâche soit terminée--poll-interval <secondes>: Optionnel - Intervalle d'interrogation (défaut : 5)--max-polls <nombre>: Optionnel - Nombre maximum de tentatives d'interrogation (défaut : 60)--output, -o <chemin>: Optionnel - Chemin du fichier de sortie (format JSON)
Résolutions Prises en Charge
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(et autres résolutions standard)
Vérifier le 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 tâche depuis la réponse initiale
z-ai async-result --id "task-id-here" --poll
Quand Utiliser la CLI vs le SDK
Utilisez la CLI pour :
- Tests rapides de génération vidéo
- Création vidéo unique simple
- Scripts d'automatisation en ligne de commande
- Tester différents prompts et réglages
Utilisez le SDK pour :
- Génération vidéo en lot avec logique personnalisée
- Intégration avec des applications web
- Gestion de file d'attente de tâches personnalisée
- Applications de production avec des flux de travail complexes
Flux de Travail 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 Génération Vidéo Basique
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('Statut de la Tâche :', task.task_status);
// Interroger pour 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 depuis 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 des données d'image encodées en base64 et des 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 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 à partir de 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 : Utilisation d'une image encodée en base64 (RECOMMANDÉ)
// Détection automatique du type MIME à partir de 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 : 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 à cela'
);
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 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 : 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 Asynchrone des Résultats
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 l\'interrogation :', error.message);
throw error;
}
}
// Exemple d'utilisation
const result = await checkTaskStatus('task-id-example');
Fonction d'Interrogation avec Timeout
import ZAI from 'z-ai-web-dev-sdk';
async function pollForVideo(taskId, maxPolls = 60, pollIntervalMs = 5000) {
const zai = await ZAI.create();
let result = await zai.async.result.query(taskId);
for (let i = 0; i < maxPolls; i++) {
if (result.task_status !== 'PROCESSING') {
break;
}
console.log(`Tentative d'interrogation ${i + 1}/${maxPolls}`);
await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
result = await zai.async.result.query(taskId);
}
return result;
}
Exemple de Gestion d'Erreurs
import ZAI from 'z-ai-web-dev-sdk';
async function generateVideoWithFallback(prompt) {
const zai = await ZAI.create();
// Essai 1 : Qualité standard
try {
const task = await zai.video.generations.create({
prompt,
size: '1920x1080',
fps: 30,
duration: 5
});
return task;
} catch (error) {
console.warn('La génération initiale a échoué, nouvelle tentative avec une résolution plus basse');
// Essai 2 : Résolution plus basse en cas d'échec
const task = await zai.video.generations.create({
prompt,
size: '1024x1024',
fps: 30,
duration: 5
});
return task;
}
}
Dépannage
Problèmes Courants
-
Les images encodées en base64 échouent
- Vérifiez que le type MIME dans l'URI de données base64 correspond au format d'image réel (par exemple,
image/pngpour les fichiers .png) - Assurez-vous que la chaîne base64 est correctement formatée sans caractères superflus
- Les images volumineuses peuvent dépasser les limites de taille. Essayez de redimensionner l'image si nécessaire
- Vérifiez que le type MIME dans l'URI de données base64 correspond au format d'image réel (par exemple,
-
Timeouts d'interrogation
- Augmentez
maxPollspour les vidéos plus longues (par exemple, 120 tentatives pour les vidéos de 10 secondes) - Vérifiez la connectivité réseau entre votre serveur backend et l'API
- Augmentez
-
La vidéo générée est de mauvaise qualité
- Utilisez
quality: 'quality'au lieu despeedpour une meilleure qualité de sortie - Assurez-vous que le prompt est descriptif et détaillé
- Utilisez
-
L'audio n'est pas généré
- Vérifiez que
with_audio: trueest défini dans le paramètre de création de la tâche - Tous les prompts ne se prêtent pas à la génération audio. Essayez des descriptions plus évocatrices
- Vérifiez que
Référence de l'API
Méthodes du SDK
interface VideoGenerationOptions {
prompt?: string; // Description textuelle (optionnel si image_url est fourni)
image_url?: string | string[]; // Image(s) de départ encodée(s) en base64 ou URL(s) (optionnel)
quality?: 'speed' | 'quality'; // Qualité de sortie (défaut : 'speed')
with_audio?: boolean; // Générer des effets audio (défaut : false)
size?: string; // Résolution vidéo (défaut : '1920x1080')
fps?: 30 | 60; // Taux de rafraîchissement (défaut : 30)
duration?: 5 | 10; // Durée en secondes (défaut : 5)
model?: string; // Modèle spécifique à utiliser
}
Réponse de la Tâche
interface VideoTaskResponse {
id: string;
task_status: 'PENDING' | 'PROCESSING' | 'SUCCESS' | 'FAIL';
video_result?: Array<{ url: string }>;
video_url?: string;
url?: string;
video?: string;
created_at: string;
updated_at: string;
}