Communitygithub.com

AiCurv/ADBCommander

Implementa capacidades de generación de video impulsadas por IA utilizando el SDK z-ai-web-dev-sdk. Usa esta habilidad cuando necesites generar videos a partir de texto o imágenes, crear contenido de video programáticamente o desarrollar aplicaciones que produzcan salidas de video. Soporta gestión de tareas asíncronas con sondeo de estado y recuperación de resultados.

¿Qué es ADBCommander?

Esta habilidad proporciona una guía completa para implementar generación de video mediante IA utilizando el SDK z-ai-web-dev-sdk. Permite crear videos desde descripciones de texto o imágenes, con parámetros personalizables como resolución, tasa de cuadros, duración y calidad. El flujo de trabajo es asíncrono: primero se crea una tarea de generación y luego se sondea el estado hasta obtener el resultado. Soporta tanto el uso desde CLI (con el comando `z-ai video`) como desde código JavaScript/TypeScript usando el SDK. Las funcionalidades incluyen generación de texto a video, imagen a video (con soporte para imágenes base64 y URLs), modo de fotogramas inicial y final, y generación de audio. Está diseñado principalmente para entornos backend, con énfasis en la confiabilidad mediante el uso de imágenes codificadas en base64.

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

Preguntar en tu IA favorita

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

Documentación

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: speed o quality (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

  • 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:

# 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:

  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 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

  1. Usar codificación base64 para imágenes: Siempre prefiere imágenes codificadas en base64 sobre URLs para mejor confiabilidad y rendimiento.
  2. Gestión de errores: Siempre maneja errores y casos límite en la generación de video para asegurar una experiencia de usuario robusta.
  3. Sondeo eficiente: Implementa sondeo con intervalos apropiados (por ejemplo, 5 segundos) para evitar sobrecargar la API.
  4. Liberación de recursos: Gestiona adecuadamente los recursos, especialmente cuando se manejan múltiples tareas de video simultáneamente.
  5. 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étodoDescripció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ámetroTipoValor por DefectoDescripción
promptstring(requerido si no hay image_url)Descripción textual del video deseado
image_urlstring o string[]nullDatos de imagen codificados en base64 (recomendado) o URL(s)
qualitystring"speed"Modo de salida: "speed" o "quality"
with_audiobooleanfalseGenerar efectos de audio por IA
sizestring"1920x1080"Resolución del video (ver resoluciones compatibles)
fpsnumber30Tasa de cuadros: 30 o 60
durationnumber5Duración en segundos: 5 o 10
modelstringnullNombre del modelo a usar (opcional)

Respuesta de zai.async.result.query

CampoTipoDescripción
task_statusstringEstado actual: "PROCESSING", "SUCCESS", "FAIL"
task_idstringIdentificador único de la tarea
video_resultobject[]Arreglo de objetos de resultado de video (presente cuando hay éxito)
video_result[].urlstringURL del video generado
video_urlstringCampo alternativo para URL del video
urlstringOtro campo posible para URL del video
videostringOtro campo posible para URL del video
errorobjectInformación del error (presente cuando falla)

Individual skills in this repo

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

AiCurv/ADBCommander

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.

AiCurv/ADBCommander

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.

AiCurv/ADBCommander

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.

AiCurv/ADBCommander

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.

AiCurv/ADBCommander

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

AiCurv/ADBCommander

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.

AiCurv/ADBCommander

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