Communitygithub.com

ARYAN2302/liquid_researcher

Habilita capacidades de generación de video impulsadas por IA usando el SDK z-ai-web-dev-sdk. Usa esta skill cuando el usuario necesite generar videos a partir de texto o imágenes, crear contenido de video mediante programación o construir aplicaciones que produzcan salidas de video. Soporta gestión de tareas asíncronas con sondeo de estado y recuperación de resultados.

¿Qué es liquid_researcher?

Esta skill te permite integrar generación de video impulsada por IA en tus aplicaciones usando el paquete `z-ai-web-dev-sdk`. Es ideal para desarrolladores que necesitan crear aplicaciones capaces de generar contenido de video dinámico a partir de descripciones textuales, imágenes fijas o secuencias de fotogramas inicial y final. La skill soporta configuraciones personalizables como resolución, tasa de fotogramas, duración y calidad (velocidad o calidad). Funciona tanto con la CLI de `z-ai` para tareas rápidas como con el SDK de Node.js para flujos de trabajo más complejos y asíncronos. El proceso sigue un patrón de dos pasos: primero se crea una tarea de generación y luego se sondea el estado hasta que se completa, momento en el cual se recupera la URL del video resultante. Se recomienda encarecidamente usar imágenes codificadas en base64 para el parámetro `image_url` en lugar de URLs, ya que esto mejora la fiabilidad y evita problemas de red. Es importante hacer coincidir el tipo MIME en la URI de datos con el formato real de la imagen (por ejemplo, image/jpeg, image/png) para evitar errores de decodificación. La skill se integra con plataformas como Claude Code, Cursor y Codex, y está diseñada para usarse exclusivamente en el backend.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ARYAN2302/liquid_researcher/tree/HEAD/skills/video-generation

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Skill de Generación de Video

Esta skill guía la implementación de funcionalidad de generación de video usando el paquete z-ai-web-dev-sdk, permitiendo que modelos de IA creen videos a partir de descripciones de texto o imágenes mediante procesamiento asíncrono de tareas.

Ruta de la Skill

Ubicación de la Skill: {project_path}/skills/video-generation

Esta skill 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 un ejemplo funcional.

Descripción General

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 fotogramas, duración y configuraciones de calidad. La API utiliza un modelo de tarea asíncrona 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 de la CLI (Para Tareas Sencillas)

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

Calidad y Configuración Personalizadas

# Modo de calidad (speed o quality)
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 fiable y evita posibles problemas de red o restricciones de acceso.

Nota: Haz coincidir el tipo MIME en la URI de datos con tu formato de imagen real (image/jpeg, image/png, image/webp, etc.) para evitar problemas de decodificación.

# Generar video a partir de 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 fiabilidad)
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 fiabilidad, usa imágenes codificadas en base64 en lugar de URLs. Asegúrate de que el tipo MIME coincida con tu formato de imagen real.

# Generar video entre dos fotogramas usando base64 (RECOMENDADO)
# Asegúrate de usar el tipo MIME correcto para cada imagen

# Ejemplo con imágenes PNG
START_BASE64=$(base64 -i inicio.png)
END_BASE64=$(base64 -i fin.png)
z-ai video \
  --image-url "data:image/png;base64,${START_BASE64},data:image/png;base64,${END_BASE64}" \
  --prompt "Transición suave entre fotogramas" \
  --poll

# Ejemplo con imágenes JPEG
START_BASE64=$(base64 -i inicio.jpg)
END_BASE64=$(base64 -i fin.jpg)
z-ai video \
  --image-url "data:image/jpeg;base64,${START_BASE64},data:image/jpeg;base64,${END_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 eléctrica acercándose" \
  --with-audio \
  --poll

Guardar Salida

# Guardar resultado de la tarea en un archivo JSON
z-ai video \
  -p "Amanecer sobre las montañas" \
  --poll \
  -o resultado_video.json

Parámetros de Sondeo Personalizados

# Personalizar el comportamiento del 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..."). También se admiten URLs pero es menos recomendado. Para dos imágenes, usa valores separados por comas.
  • --quality, -q <modo>: Opcional - Modo de salida: speed o quality (predeterminado: speed)
  • --with-audio: Opcional - Generar efectos de audio por IA (predeterminado: false)
  • --size, -s <resolución>: Opcional - Resolución del video (ej., "1920x1080")
  • --fps <tasa>: Opcional - Tasa de fotogramas: 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 <número>: Opcional - Número máximo de intentos de sondeo (predeterminado: 60)
  • --output, -o <ruta>: Opcional - Ruta del archivo de salida (formato JSON)

Resoluciones Soportadas

  • 1024x1024
  • 768x1344
  • 864x1152
  • 1344x768
  • 1152x864
  • 1440x720
  • 720x1440
  • 1920x1080 (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:

# Obtén el ID de la tarea desde la respuesta inicial
z-ai async-result --id "id-de-la-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 en línea de comandos
  • Probar diferentes indicaciones y configuraciones

Usa SDK para:

  • Generación de video por lotes con lógica personalizada
  • Integración con aplicaciones web
  • Gestión de colas de tareas personalizadas
  • Aplicaciones en 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:

  1. Crear Tarea: Envía una solicitud de generación de video y recibe un ID de tarea
  2. 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 URL del video de varios 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 se recomienda encarecidamente la codificación base64 para una mejor fiabilidad 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 de imagen real 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 se desconoce
}

async function generateVideoFromImage(imagePath, prompt) {
  const zai = await ZAI.create();

  // Método 1: Usando imagen codificada en base64 (RECOMENDADO)
  // Detectar 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 el 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 de 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 Fotograma Inicial y Final

IMPORTANTE: Para el modo de fotogramas clave, se recomienda encarecidamente usar imágenes codificadas en base64 en lugar de URLs para garantizar una generación de video consistente y fiable. Usa siempre 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)
  // Detectar 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],  // Array 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],  // Array de cadenas de 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 inicial JPEG
  './frames/fin.jpg',     // Fotograma final JPEG
  'Transición suave entre estas escenas'
);

const task2 = await generateVideoWithKeyframes(
  './frames/inicio.png',  // Fotograma inicial PNG
  './frames/fin.webp',    // Fotograma final WebP - ¡formatos diferentes funcionan!
  'Efecto de transformación entre imágenes'
);

Gestión de Resultados Asíncronos

Consultar Estado de la 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 se 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 verificar el estado de la tarea:', error.message);
  }
}

Mejores Prácticas

  1. Usa codificación base64 para imágenes: La codificación base64 es más fiable que las URLs. Evita problemas de red y autenticación.

  2. Verifica los tipos MIME: Siempre asegúrate de que el tipo MIME en tu URI de datos coincida con el formato de imagen real para evitar errores de decodificación.

  3. Implementa un sondeo robusto: Siempre usa límites máximos de sondeo para evitar bucles infinitos. El valor predeterminado es 60 intentos con un intervalo de 5 segundos.

  4. Extracción de URL: Al obtener la URL del video de la respuesta, verifica múltiples campos: video_result[0].url, video_url, url, video.

  5. Uso en backend: z-ai-web-dev-sdk está diseñado para uso exclusivo en el backend. Nunca expongas claves API o el SDK en código del lado del cliente.

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

ARYAN2302/liquid_researcher

Generate a single-file Chinese atelier-style portfolio website (horizontal-row list + hover-reveal thumb interaction, art lishu typography "Alimama DaoLiTi" via CDN, light/dark theme, hash-routed detail pages). Takes a natural-language description of the studio (name, director, discipline, works) and outputs ONE working .html file. Runs in BOTH Claude Code (writes to ~/Desktop) and GLM / online chat (outputs HTML inline). Trigger phrases include "做个中式工作室作品集", "做个隶书作品集", "lishu-portfolio-gen ...", "做个白屋风格的作品集", or when user drags this skill folder into chat asking for an atelier-style site.

ARYAN2302/liquid_researcher

Chinese-market SaaS pricing page template — soft sky-blue glass-morphism, 4-tier card grid with one elevated "recommended" tier, monthly/annual toggle, FAQ accordion, ¥ pricing with Inter numerals, careful CJK linebreaking, ICP filing footer.

ARYAN2302/liquid_researcher

Premium calm-tech SaaS landing template — bilingual (CN/EN) literary voice over a dark forest-night palette with warm gold accent, Cormorant + Noto Serif SC, Three.js procedural forest hero, station-based scrolling narrative, custom cursor. Built for ambient-AI / creative-tool / philosophical SaaS, not loud commercial launch.

ARYAN2302/liquid_researcher

Pro-camera HUD mockup template — full-viewport black canvas wrapping a real video with monospace overlays (corner brackets, top status bar, side AF/exposure columns, bottom timecode + aperture/shutter/ISO row, vertical 8-filter wheel, animated reticle). For cinematographer portfolios, camera-app demos, LUT pack previews, filter-look auditions. NOT a TikTok/Reels mockup, NOT a storyboard, NOT a shot list, NOT a script document. The chrome wraps real footage — never a div placeholder.

ARYAN2302/liquid_researcher

Premium pre-launch waitlist page template — dark charcoal canvas with subtle vignette, drifting portrait video-thumbnail cards, fade-up cascades, glass nav, live-updating join counter, single email form with success/error states. Built for creative-tool / AI / niche-SaaS invite-only launches with hushed exclusive tone, not loud growth-marketing.

ARYAN2302/liquid_researcher

Route design-related HTML artifact tasks to the right artifact skill, reference, design system generation, or export skill.

ARYAN2302/liquid_researcher

Implement text-to-speech (TTS) capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to convert text into natural-sounding speech, create audio content, build voice-enabled applications, or generate spoken audio files. Supports multiple voices, adjustable speed, and various audio formats.

ARYAN2302/liquid_researcher

Implement specialized video understanding capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to analyze video content, understand motion and temporal sequences, extract information from video frames, describe video scenes, or perform video-based AI analysis. Optimized for MP4, AVI, MOV, and other common video formats.

Skills relacionados