Habilidad de Generación de Video
Esta habilidad guía la implementación de funcionalidad de generación de video usando el paquete z-ai-web-dev-sdk, permitiendo que los modelos de IA creen videos a partir de descripciones de texto o imágenes mediante procesamiento asíncrono de tareas.
Ruta de la Habilidad
Ubicación de la Habilidad: {project_path}/skills/video-generation
Esta habilidad se encuentra en la ruta anterior dentro de tu proyecto.
Scripts de Referencia: Hay scripts de prueba de ejemplo disponibles en el directorio {Skill Location}/scripts/ para pruebas rápidas y referencia. Consulta {Skill Location}/scripts/video.ts para ver un ejemplo funcional.
Resumen
La Generación de Video te permite construir aplicaciones que pueden crear contenido de video a partir de indicaciones de texto o imágenes, con parámetros personalizables como resolución, tasa de cuadros, duración y ajustes de calidad. La API utiliza un modelo de tareas asíncronas donde creas una tarea y sondeas los resultados.
IMPORTANTE: z-ai-web-dev-sdk DEBE usarse solo en código backend. Nunca lo uses en código del lado del cliente.
Prerrequisitos
El paquete z-ai-web-dev-sdk ya está instalado. Impórtalo como se muestra en los ejemplos a continuación.
Uso con CLI (Para Tareas Simples)
Para tareas simples de generación de video, puedes usar la CLI de z-ai en lugar de escribir código. La CLI maneja la creación de tareas y el sondeo automáticamente, lo que la hace ideal para pruebas rápidas y automatización simple.
Texto a Video Básico
# Generar video con sondeo automático
z-ai video --prompt "Un gato jugando con una pelota" --poll
# Usando opciones cortas
z-ai video -p "Hermoso paisaje con montañas" --poll
Configuración de Calidad y Ajustes Personalizados
# Modo de calidad (velocidad o calidad)
z-ai video -p "Olas del océano al atardecer" --quality quality --poll
# Resolución y FPS personalizados
z-ai video \
-p "Time-lapse de ciudad" \
--size "1920x1080" \
--fps 60 \
--poll
# Duración personalizada (5 o 10 segundos)
z-ai video -p "Espectáculo de fuegos artificiales" --duration 10 --poll
Imagen a Video
IMPORTANTE: Para el parámetro image_url, se recomienda encarecidamente usar datos de imagen codificados en base64 en lugar de URLs. Este enfoque es más confiable y evita posibles problemas de red o restricciones de acceso.
Nota: Haz coincidir el tipo MIME en la URI de datos con el formato real de tu imagen (image/jpeg, image/png, image/webp, etc.) para evitar problemas de decodificación.
# Generar video desde una sola imagen usando base64 (RECOMENDADO)
# Convierte tu imagen a base64 con el tipo MIME correcto
# Para imágenes PNG
IMAGE_BASE64=$(base64 -i imagen.png)
z-ai video \
--image-url "data:image/png;base64,${IMAGE_BASE64}" \
--prompt "Haz que la escena cobre vida" \
--poll
# Para imágenes JPEG
IMAGE_BASE64=$(base64 -i foto.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${IMAGE_BASE64}" \
--prompt "Haz que la escena cobre vida" \
--poll
# Para imágenes WebP
IMAGE_BASE64=$(base64 -i imagen.webp)
z-ai video \
--image-url "data:image/webp;base64,${IMAGE_BASE64}" \
--prompt "Haz que la escena cobre vida" \
--poll
# Usando URL (menos recomendado, puede tener problemas de confiabilidad)
z-ai video \
-i "https://ejemplo.com/foto.jpg" \
-p "Agrega movimiento a esta escena" \
--poll
Modo de Primer y Último Fotograma
IMPORTANTE: Para una mejor confiabilidad, usa imágenes codificadas en base64 en lugar de URLs. Asegúrate de que el tipo MIME coincida con el formato real de tu imagen.
# Generar video entre dos fotogramas usando base64 (RECOMENDADO)
# Asegúrate de usar el tipo MIME correcto para cada imagen
# Ejemplo con imágenes PNG
INICIO_BASE64=$(base64 -i inicio.png)
FIN_BASE64=$(base64 -i fin.png)
z-ai video \
--image-url "data:image/png;base64,${INICIO_BASE64},data:image/png;base64,${FIN_BASE64}" \
--prompt "Transición suave entre fotogramas" \
--poll
# Ejemplo con imágenes JPEG
INICIO_BASE64=$(base64 -i inicio.jpg)
FIN_BASE64=$(base64 -i fin.jpg)
z-ai video \
--image-url "data:image/jpeg;base64,${INICIO_BASE64},data:image/jpeg;base64,${FIN_BASE64}" \
--prompt "Transición suave entre fotogramas" \
--poll
# Usando URLs (menos recomendado)
z-ai video \
--image-url "https://ejemplo.com/inicio.png,https://ejemplo.com/fin.png" \
--prompt "Transición suave entre fotogramas" \
--poll
Con Generación de Audio
# Generar video con efectos de audio generados por IA
z-ai video \
-p "Tormenta acercándose" \
--with-audio \
--poll
Guardar Salida
# Guardar resultado de la tarea en un archivo JSON
z-ai video \
-p "Amanecer sobre montañas" \
--poll \
-o resultado_video.json
Parámetros de Sondeo Personalizados
# Personalizar el comportamiento de sondeo
z-ai video \
-p "Robot bailando" \
--poll \
--poll-interval 10 \
--max-polls 30
# Crear tarea sin sondeo (obtener ID de tarea)
z-ai video -p "Animación de arte abstracto" -o tarea.json
Parámetros de CLI
--prompt, -p <texto>: Opcional - Descripción textual del video--image-url, -i <datos>: Opcional - Preferiblemente datos de imagen codificados en base64 (ej., "data:image/png;base64,iVBORw..."). Las URLs también son compatibles pero menos recomendadas. Para dos imágenes, usa valores separados por comas.--quality, -q <modo>: Opcional - Modo de salida:speedoquality(predeterminado: speed)--with-audio: Opcional - Generar efectos de audio con IA (predeterminado: false)--size, -s <resolución>: Opcional - Resolución del video (ej., "1920x1080")--fps <tasa>: Opcional - Tasa de cuadros: 30 o 60 (predeterminado: 30)--duration, -d <segundos>: Opcional - Duración: 5 o 10 segundos (predeterminado: 5)--model, -m <modelo>: Opcional - Nombre del modelo a usar--poll: Opcional - Sondeo automático hasta que la tarea se complete--poll-interval <segundos>: Opcional - Intervalo de sondeo (predeterminado: 5)--max-polls <conteo>: Opcional - Máximo de intentos de sondeo (predeterminado: 60)--output, -o <ruta>: Opcional - Ruta del archivo de salida (formato JSON)
Resoluciones Compatibles
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(y otras resoluciones estándar)
Verificar Estado de la Tarea Más Tarde
Si creas una tarea sin --poll, puedes verificar su estado más tarde:
# Obtener el ID de la tarea de la respuesta inicial
z-ai async-result --id "id-de-tarea-aqui" --poll
Cuándo Usar CLI vs SDK
Usa CLI para:
- Pruebas rápidas de generación de video
- Creación simple de videos únicos
- Scripts de automatización de línea de comandos
- Probar diferentes indicaciones y ajustes
Usa SDK para:
- Generación de video por lotes con lógica personalizada
- Integración con aplicaciones web
- Gestión personalizada de colas de tareas
- Aplicaciones de producción con flujos de trabajo complejos
Flujo de Trabajo de Generación de Video
La generación de video sigue un patrón asíncrono de dos pasos:
- Crear Tarea: Envía una solicitud de generación de video y recibe un ID de tarea
- Sondear Resultados: Consulta el estado de la tarea hasta que se complete y recupera la URL del video
Implementación Básica de Generación de Video
Generación Simple de Texto a Video
import ZAI from 'z-ai-web-dev-sdk';
async function generateVideo(prompt) {
try {
const zai = await ZAI.create();
// Crear tarea de generación de video
const task = await zai.video.generations.create({
prompt: prompt,
quality: 'speed', // 'speed' o 'quality'
with_audio: false,
size: '1920x1080',
fps: 30,
duration: 5
});
console.log('ID de Tarea:', task.id);
console.log('Estado de Tarea:', task.task_status);
// Sondear resultados
let result = await zai.async.result.query(task.id);
let pollCount = 0;
const maxPolls = 60;
const pollInterval = 5000; // 5 segundos
while (result.task_status === 'PROCESSING' && pollCount < maxPolls) {
pollCount++;
console.log(`Sondeo ${pollCount}/${maxPolls}: El estado es ${result.task_status}`);
await new Promise(resolve => setTimeout(resolve, pollInterval));
result = await zai.async.result.query(task.id);
}
if (result.task_status === 'SUCCESS') {
// Obtener la URL del video de múltiples campos posibles
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
console.log('URL del Video:', videoUrl);
return videoUrl;
} else {
console.log('La tarea falló o aún está procesando');
return null;
}
} catch (error) {
console.error('La generación de video falló:', error.message);
throw error;
}
}
// Uso
const videoUrl = await generateVideo('Un gato está jugando con una pelota.');
console.log('Video generado:', videoUrl);
Generación de Imagen a Video
IMPORTANTE: El parámetro image_url acepta tanto datos de imagen codificados en base64 como URLs, pero la codificación base64 es fuertemente recomendada para una mejor confiabilidad y para evitar problemas relacionados con la red.
Crítico: Siempre haz coincidir el tipo MIME en tu URI de datos base64 con el formato real de la imagen para evitar errores de decodificación.
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
// Función auxiliar para detectar el tipo MIME desde la extensión del archivo
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'; // Predeterminado a JPEG si es desconocido
}
async function generateVideoFromImage(imagePath, prompt) {
const zai = await ZAI.create();
// Método 1: Usando imagen codificada en base64 (RECOMENDADO)
// Detecta automáticamente el tipo MIME desde la extensión del archivo
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, // Cadena de datos base64 con tipo MIME correcto
prompt: prompt,
quality: 'quality',
duration: 5,
fps: 30
});
return task;
}
// Método 2: Usando URL (menos recomendado)
async function generateVideoFromImageUrl(imageUrl, prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
image_url: imageUrl, // Cadena URL
prompt: prompt,
quality: 'quality',
duration: 5,
fps: 30
});
return task;
}
// Ejemplos de uso
const task1 = await generateVideoFromImage(
'./images/foto.jpg', // Funciona con JPEG
'Anima esta escena con movimiento suave'
);
const task2 = await generateVideoFromImage(
'./images/grafico.png', // Funciona con PNG
'Agrega movimiento dinámico'
);
const task3 = await generateVideoFromImage(
'./images/animacion.webp', // Funciona con WebP
'Dale vida a esto'
);
Imagen a Video con Fotogramas de Inicio y Fin
IMPORTANTE: Para el modo de fotogramas clave, las imágenes codificadas en base64 son altamente recomendadas sobre URLs para asegurar una generación de video consistente y confiable. Siempre usa el tipo MIME correcto para cada imagen.
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
// Función auxiliar para detectar el tipo MIME desde la extensión del archivo
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étodo 1: Usando imágenes codificadas en base64 (RECOMENDADO)
// Detecta automáticamente el tipo MIME para cada imagen
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], // Arreglo de cadenas base64 con tipos MIME correctos
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30
});
console.log('Tarea creada con fotogramas clave:', task.id);
return task;
}
// Método 2: Usando URLs (menos recomendado)
async function generateVideoWithKeyframesUrl(startImageUrl, endImageUrl, prompt) {
const zai = await ZAI.create();
const task = await zai.video.generations.create({
image_url: [startImageUrl, endImageUrl], // Arreglo de cadenas URL
prompt: prompt,
quality: 'quality',
duration: 10,
fps: 30
});
console.log('Tarea creada con fotogramas clave:', task.id);
return task;
}
// Ejemplos de uso con diferentes formatos
const task1 = await generateVideoWithKeyframes(
'./frames/inicio.jpg', // Fotograma de inicio JPEG
'./frames/fin.jpg', // Fotograma de fin JPEG
'Transición suave entre estas escenas'
);
const task2 = await generateVideoWithKeyframes(
'./frames/inicio.png', // Fotograma de inicio PNG
'./frames/fin.webp', // Fotograma de fin WebP - ¡diferentes formatos funcionan!
'Efecto de transformación entre imágenes'
);
Gestión de Resultados Asíncronos
Consultar Estado de Tarea
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('Estado de Tarea:', result.task_status);
if (result.task_status === 'SUCCESS') {
// Extraer URL del video del resultado
const videoUrl = result.video_result?.[0]?.url ||
result.video_url ||
result.url ||
result.video;
if (videoUrl) {
console.log('URL del Video:', videoUrl);
return { success: true, url: videoUrl };
}
} else if (result.task_status === 'PROCESSING') {
console.log('La tarea aún está procesando');
return { success: false, status: 'processing' };
} else if (result.task_status === 'FAIL') {
console.log('La tarea falló');
return { success: false, status: 'failed' };
}
} catch (error) {
console.error('Error al consultar estado de la tarea:', error.message);
throw error;
}
}
Gestión de Múltiples Tareas
Para aplicaciones que manejan múltiples generaciones de video, puedes gestionar tareas de manera eficiente:
import ZAI from 'z-ai-web-dev-sdk';
class VideoTaskManager {
constructor() {
this.tasks = new Map();
this.zai = null;
}
async initialize() {
this.zai = await ZAI.create();
}
async createTask(prompt, options = {}) {
const task = await this.zai.video.generations.create({
prompt: prompt,
quality: options.quality || 'speed',
with_audio: options.with_audio || false,
size: options.size || '1920x1080',
fps: options.fps || 30,
duration: options.duration || 5,
image_url: options.image_url || null
});
this.tasks.set(task.id, {
id: task.id,
status: task.task_status,
prompt: prompt,
created: new Date()
});
return task.id;
}
async checkAllTasks() {
const results = [];
for (const [taskId, taskInfo] of this.tasks) {
if (taskInfo.status === 'PROCESSING') {
const result = await this.zai.async.result.query(taskId);
taskInfo.status = result.task_status;
if (result.task_status === 'SUCCESS') {
const videoUrl = result.video_result?.[0]?.url || result.video_url || result.url;
taskInfo.videoUrl = videoUrl;
results.push({ id: taskId, status: 'SUCCESS', url: videoUrl });
} else if (result.task_status === 'FAIL') {
results.push({ id: taskId, status: 'FAIL' });
}
}
}
return results;
}
}
// Uso
const manager = new VideoTaskManager();
await manager.initialize();
const taskId1 = await manager.createTask('Tutorial de cocina');
const taskId2 = await manager.createTask('Animación de logo', {
image_url: 'ruta/al/logo.png',
duration: 10
});
// Verificar todas las tareas periódicamente
setInterval(async () => {
const completedTasks = await manager.checkAllTasks();
completedTasks.forEach(task => {
console.log(`Tarea ${task.id} completada. URL: ${task.url}`);
});
}, 5000);
Mejores Prácticas
- Usar codificación base64 para imágenes: Siempre prefiere imágenes codificadas en base64 sobre URLs para mejor confiabilidad y rendimiento.
- Gestión de errores: Siempre maneja errores y casos límite en la generación de video para asegurar una experiencia de usuario robusta.
- Sondeo eficiente: Implementa sondeo con intervalos apropiados (por ejemplo, 5 segundos) para evitar sobrecargar la API.
- Liberación de recursos: Gestiona adecuadamente los recursos, especialmente cuando se manejan múltiples tareas de video simultáneamente.
- Validación de parámetros: Valida parámetros de entrada como resolución, FPS y duración para evitar fallos en la solicitud.
Referencia de API
| Método | Descripción |
|---|---|
zai.video.generations.create(params) | Crear tarea de generación de video |
zai.async.result.query(taskId) | Consultar estado y resultado de la tarea |
Parámetros de zai.video.generations.create
| Parámetro | Tipo | Valor por Defecto | Descripción |
|---|---|---|---|
prompt | string | (requerido si no hay image_url) | Descripción textual del video deseado |
image_url | string o string[] | null | Datos de imagen codificados en base64 (recomendado) o URL(s) |
quality | string | "speed" | Modo de salida: "speed" o "quality" |
with_audio | boolean | false | Generar efectos de audio por IA |
size | string | "1920x1080" | Resolución del video (ver resoluciones compatibles) |
fps | number | 30 | Tasa de cuadros: 30 o 60 |
duration | number | 5 | Duración en segundos: 5 o 10 |
model | string | null | Nombre del modelo a usar (opcional) |
Respuesta de zai.async.result.query
| Campo | Tipo | Descripción |
|---|---|---|
task_status | string | Estado actual: "PROCESSING", "SUCCESS", "FAIL" |
task_id | string | Identificador único de la tarea |
video_result | object[] | Arreglo de objetos de resultado de video (presente cuando hay éxito) |
video_result[].url | string | URL del video generado |
video_url | string | Campo alternativo para URL del video |
url | string | Otro campo posible para URL del video |
video | string | Otro campo posible para URL del video |
error | object | Información del error (presente cuando falla) |