Communitygithub.com

Cetc2211/AcTR-app

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

¿Qué es AcTR-app?

Esta habilidad te permite integrar generación de video impulsada por IA en tus aplicaciones usando el SDK `z-ai-web-dev-sdk`. Es ideal para desarrolladores que desean crear contenido de video a partir de descripciones textuales o imágenes, con parámetros ajustables como resolución, tasa de fotogramas, duración y calidad. La API sigue un modelo asíncrono: creas una tarea y luego consultas su estado hasta obtener el resultado, lo que la hace adecuada tanto para pruebas rápidas como para flujos de producción complejos. Soporta múltiples formatos de imagen (JPEG, PNG, WebP, etc.) y recomienda codificar las imágenes en base64 para mayor confiabilidad. Además, ofrece una interfaz CLI para tareas simples y una API SDK para integraciones más avanzadas en aplicaciones web o backend.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cetc2211/AcTR-app/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 a los modelos de IA crear videos a partir de descripciones de texto o imágenes mediante procesamiento de tareas asíncronas.

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 consulta. Consulta {Skill Location}/scripts/video.ts para 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 fotogramas, duración y configuraciones de calidad. La API utiliza un modelo de tareas asíncronas donde creas una tarea y consultas los resultados.

IMPORTANTE: z-ai-web-dev-sdk DEBE usarse solo en código de backend. Nunca lo uses en código del lado del cliente.

Requisitos Previos

El paquete z-ai-web-dev-sdk ya está instalado. Impórtalo como se muestra en los ejemplos a continuación.

Uso de 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 Personalizada de Calidad

# 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 la 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: Empareja 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 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 image.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 photo.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 image.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://example.com/photo.jpg" \
  -p "Añade movimiento a esta escena" \
  --poll

Modo de Primer y Último Fotograma

IMPORTANTE: Para mayor fiabilidad, 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
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 "Transición suave entre fotogramas" \
  --poll

# Ejemplo con imágenes 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 "Transición suave entre fotogramas" \
  --poll

# Usando URLs (menos recomendado)
z-ai video \
  --image-url "https://example.com/start.png,https://example.com/end.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 video_result.json

Parámetros Personalizados de Sondeo

# 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 task.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 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 <recuento>: Opcional - 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 de la respuesta inicial
z-ai async-result --id "task-id-here" --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 configuraciones

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: Enviar solicitud de generación de video y recibir un ID de tarea
  2. Sondear Resultados: Consultar el estado de la tarea hasta que se complete y recuperar 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('Task ID:', task.id);
    console.log('Task Status:', 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(`Polling ${pollCount}/${maxPolls}: Status is ${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 desde varios campos posibles
      const videoUrl = result.video_result?.[0]?.url ||
                      result.video_url ||
                      result.url ||
                      result.video;
      console.log('Video URL:', videoUrl);
      return videoUrl;
    } else {
      console.log('Task failed or still processing');
      return null;
    }
  } catch (error) {
    console.error('Video generation failed:', error.message);
    throw error;
  }
}

// Uso
const videoUrl = await generateVideo('Un gato está jugando con una pelota.');
console.log('Generated video:', 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 se recomienda encarecidamente para mayor fiabilidad y para evitar problemas relacionados con la red.

Crítico: Siempre empareja 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 de 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'; // Por defecto 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 de 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 de URL
    prompt: prompt,
    quality: 'quality',
    duration: 5,
    fps: 30
  });

  return task;
}

// Ejemplos de uso
const task1 = await generateVideoFromImage(
  './images/photo.jpg',  // Funciona con JPEG
  'Anima esta escena con movimiento suave'
);

const task2 = await generateVideoFromImage(
  './images/graphic.png',  // Funciona con PNG
  'Añade movimiento dinámico'
);

const task3 = await generateVideoFromImage(
  './images/animation.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 las URLs para garantizar 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 de 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('Task created with keyframes:', 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('Task created with keyframes:', task.id);
  return task;
}

// Ejemplos de uso con diferentes formatos
const task1 = await generateVideoWithKeyframes(
  './frames/start.jpg',  // Fotograma inicial JPEG
  './frames/end.jpg',    // Fotograma final JPEG
  'Transición suave entre estas escenas'
);

const task2 = await generateVideoWithKeyframes(
  './frames/start.png',  // Fotograma inicial PNG
  './frames/end.webp',   // Fotograma final WebP - ¡diferentes formatos 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('Task Status:', result.task_status);

    if (result.task_status === 'SUCCESS') {
      // Extraer la URL del video del resultado
      const videoUrl = result.video_result?.[0]?.url ||
                      result.video_url ||
                      result.url ||
                      result.video;
      if (videoUrl) {
        console.log('Video URL:', videoUrl);
        return { success: true, url: videoUrl };
      }
    } else if (result.task_status === 'PROCESSING') {
      console.log('Task is still processing');
      return { success: false, status: 'processing' };
    } else if (result.task_status === 'FAIL') {
      console.log('Task failed');
      return { success: false, status: 'failed' };
    }
  } catch (error) {
    console.error('Error checking task status:', error.message);
    throw error;
  }
}

// Ejemplos de uso
const status1 = await checkTaskStatus('task-id-here');

// ... contenido adicional truncado para el ejemplo

[Aquí continuaría el resto del contenido del SKILL.md original, traducido al español, manteniendo el mismo formato de markdown.]

Individual skills in this repo

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

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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