Communitygithub.com

Cetc2211/AcTR-app

Implementa recursos de geração de vídeo com IA usando o z-ai-web-dev-sdk. Use esta skill quando precisar gerar vídeos a partir de prompts de texto ou imagens, criar conteúdo de vídeo programaticamente ou construir aplicações que produzam saídas de vídeo. Suporta gerenciamento assíncrono de tarefas com polling de status e recuperação de resultados.

O que é AcTR-app?

Esta skill fornece funcionalidades abrangentes de geração de vídeo utilizando o pacote z-ai-web-dev-sdk, permitindo que desenvolvedores criem conteúdo de vídeo a partir de descrições textuais ou imagens através de processamento assíncrono de tarefas. Ela suporta vários parâmetros de personalização, como resolução, taxa de quadros, duração e configurações de qualidade, e pode ser usada com a interface de linha de comando (CLI) do z-ai para tarefas simples ou com o SDK para fluxos de trabalho mais complexos. A skill oferece capacidades de conversão de texto para vídeo, imagem para vídeo e animação entre dois quadros (first-last frame), com suporte robusto para codificação base64 no lugar de URLs para maior confiabilidade. Adequada para plataformas como Claude Code, Cursor e Codex, ela inclui polling automático de status, testes unitários e integração com geração de áudio, sendo ideal para construir aplicações que produzem saídas de vídeo em produção.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cetc2211/AcTR-app/tree/HEAD/skills/video-generation

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Habilidade de Geração de Vídeo

Esta habilidade orienta a implementação da funcionalidade de geração de vídeo usando o pacote z-ai-web-dev-sdk, permitindo que modelos de IA criem vídeos a partir de descrições textuais ou imagens através de processamento assíncrono de tarefas.

Caminho da Habilidade

Localização da Habilidade: {project_path}/skills/video-generation

Esta habilidade está localizada no caminho acima em seu projeto.

Scripts de Referência: Scripts de teste de exemplo estão disponíveis no diretório {Skill Location}/scripts/ para testes rápidos e referência. Veja {Skill Location}/scripts/video.ts para um exemplo funcional.

Visão Geral

A Geração de Vídeo permite que você construa aplicações que podem criar conteúdo de vídeo a partir de prompts de texto ou imagens, com parâmetros personalizáveis como resolução, taxa de quadros, duração e configurações de qualidade. A API usa um modelo de tarefas assíncronas onde você cria uma tarefa e faz polling pelos resultados.

IMPORTANTE: O z-ai-web-dev-sdk DEVE ser usado apenas em código backend. Nunca o use em código do lado do cliente.

Pré-requisitos

O pacote z-ai-web-dev-sdk já está instalado. Importe-o conforme mostrado nos exemplos abaixo.

Uso via CLI (Para Tarefas Simples)

Para tarefas simples de geração de vídeo, você pode usar a CLI do z-ai em vez de escrever código. A CLI lida com a criação de tarefas e polling automaticamente, tornando-a ideal para testes rápidos e automação simples.

Texto para Vídeo Básico

# Gerar vídeo com polling automático
z-ai video --prompt "Um gato brincando com uma bola" --poll

# Usando opções curtas
z-ai video -p "Linda paisagem com montanhas" --poll

Qualidade e Configurações Personalizadas

# Modo de qualidade (speed ou quality)
z-ai video -p "Ondas do oceano ao pôr do sol" --quality quality --poll

# Resolução e FPS personalizados
z-ai video \
  -p "Time-lapse da cidade" \
  --size "1920x1080" \
  --fps 60 \
  --poll

# Duração personalizada (5 ou 10 segundos)
z-ai video -p "Show de fogos de artifício" --duration 10 --poll

Imagem para Vídeo

IMPORTANTE: Para o parâmetro image_url, é fortemente recomendado usar dados de imagem codificados em base64 em vez de URLs. Esta abordagem é mais confiável e evita possíveis problemas de rede ou restrições de acesso.

Nota: Corresponda o tipo MIME no data URI ao formato real da sua imagem (image/jpeg, image/png, image/webp, etc.) para evitar problemas de decodificação.

# Gerar vídeo a partir de uma única imagem usando base64 (RECOMENDADO)
# Converta sua imagem para base64 com o tipo MIME correto

# Para imagens PNG
IMAGE_BASE64=$(base64 -i imagem.png)
z-ai video \
  --image-url "data:image/png;base64,${IMAGE_BASE64}" \
  --prompt "Faça a cena ganhar vida" \
  --poll

# Para imagens JPEG
IMAGE_BASE64=$(base64 -i foto.jpg)
z-ai video \
  --image-url "data:image/jpeg;base64,${IMAGE_BASE64}" \
  --prompt "Faça a cena ganhar vida" \
  --poll

# Para imagens WebP
IMAGE_BASE64=$(base64 -i imagem.webp)
z-ai video \
  --image-url "data:image/webp;base64,${IMAGE_BASE64}" \
  --prompt "Faça a cena ganhar vida" \
  --poll

# Usando URL (menos recomendado, pode ter problemas de confiabilidade)
z-ai video \
  -i "https://exemplo.com/foto.jpg" \
  -p "Adicione movimento a esta cena" \
  --poll

Modo Primeiro-Último Quadro

IMPORTANTE: Para melhor confiabilidade, use imagens codificadas em base64 em vez de URLs. Certifique-se de que o tipo MIME corresponda ao formato real da sua imagem.

# Gerar vídeo entre dois quadros usando base64 (RECOMENDADO)
# Certifique-se de usar o tipo MIME correto para cada imagem

# Exemplo com imagens PNG
INICIO_BASE64=$(base64 -i inicio.png)
FIM_BASE64=$(base64 -i fim.png)
z-ai video \
  --image-url "data:image/png;base64,${INICIO_BASE64},data:image/png;base64,${FIM_BASE64}" \
  --prompt "Transição suave entre quadros" \
  --poll

# Exemplo com imagens JPEG
INICIO_BASE64=$(base64 -i inicio.jpg)
FIM_BASE64=$(base64 -i fim.jpg)
z-ai video \
  --image-url "data:image/jpeg;base64,${INICIO_BASE64},data:image/jpeg;base64,${FIM_BASE64}" \
  --prompt "Transição suave entre quadros" \
  --poll

# Usando URLs (menos recomendado)
z-ai video \
  --image-url "https://exemplo.com/inicio.png,https://exemplo.com/fim.png" \
  --prompt "Transição suave entre quadros" \
  --poll

Com Geração de Áudio

# Gerar vídeo com efeitos de áudio gerados por IA
z-ai video \
  -p "Tempestade se aproximando" \
  --with-audio \
  --poll

Salvar Saída

# Salvar resultado da tarefa em arquivo JSON
z-ai video \
  -p "Nascer do sol sobre montanhas" \
  --poll \
  -o video_result.json

Parâmetros de Polling Personalizados

# Personalizar comportamento de polling
z-ai video \
  -p "Robô dançando" \
  --poll \
  --poll-interval 10 \
  --max-polls 30

# Criar tarefa sem polling (obter ID da tarefa)
z-ai video -p "Animação de arte abstrata" -o task.json

Parâmetros da CLI

  • --prompt, -p <texto>: Opcional - Descrição textual do vídeo
  • --image-url, -i <dados>: Opcional - Preferencialmente dados de imagem codificados em base64 (ex.: "data:image/png;base64,iVBORw..."). URLs também são suportadas, mas menos recomendadas. Para duas imagens, use valores separados por vírgula.
  • --quality, -q <modo>: Opcional - Modo de saída: speed ou quality (padrão: speed)
  • --with-audio: Opcional - Gerar efeitos de áudio por IA (padrão: false)
  • --size, -s <resolução>: Opcional - Resolução do vídeo (ex.: "1920x1080")
  • --fps <taxa>: Opcional - Taxa de quadros: 30 ou 60 (padrão: 30)
  • --duration, -d <segundos>: Opcional - Duração: 5 ou 10 segundos (padrão: 5)
  • --model, -m <modelo>: Opcional - Nome do modelo a ser usado
  • --poll: Opcional - Polling automático até a tarefa ser concluída
  • --poll-interval <segundos>: Opcional - Intervalo de polling (padrão: 5)
  • --max-polls <contagem>: Opcional - Número máximo de tentativas de polling (padrão: 60)
  • --output, -o <caminho>: Opcional - Caminho do arquivo de saída (formato JSON)

Resoluções Suportadas

  • 1024x1024
  • 768x1344
  • 864x1152
  • 1344x768
  • 1152x864
  • 1440x720
  • 720x1440
  • 1920x1080 (e outras resoluções padrão)

Verificar Status da Tarefa Depois

Se você criar uma tarefa sem --poll, pode verificar seu status depois:

# Obter o ID da tarefa da resposta inicial
z-ai async-result --id "task-id-aqui" --poll

Quando Usar CLI vs SDK

Use CLI para:

  • Testes rápidos de geração de vídeo
  • Criação de vídeos únicos e simples
  • Scripts de automação de linha de comando
  • Testar diferentes prompts e configurações

Use SDK para:

  • Geração de vídeo em lote com lógica personalizada
  • Integração com aplicações web
  • Gerenciamento personalizado de fila de tarefas
  • Aplicações de produção com fluxos de trabalho complexos

Fluxo de Trabalho de Geração de Vídeo

A geração de vídeo segue um padrão assíncrono de duas etapas:

  1. Criar Tarefa: Envie a solicitação de geração de vídeo e receba um ID de tarefa
  2. Resultados de Polling: Consulte o status da tarefa até a conclusão e recupere o URL do vídeo

Implementação Básica de Geração de Vídeo

Geração de Texto para Vídeo Simples

import ZAI from 'z-ai-web-dev-sdk';

async function generateVideo(prompt) {
  try {
    const zai = await ZAI.create();

    // Criar tarefa de geração de vídeo
    const task = await zai.video.generations.create({
      prompt: prompt,
      quality: 'speed', // 'speed' or 'quality'
      with_audio: false,
      size: '1920x1080',
      fps: 30,
      duration: 5
    });

    console.log('ID da Tarefa:', task.id);
    console.log('Status da Tarefa:', task.task_status);

    // Fazer polling pelos 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 é ${result.task_status}`);
      await new Promise(resolve => setTimeout(resolve, pollInterval));
      result = await zai.async.result.query(task.id);
    }

    if (result.task_status === 'SUCCESS') {
      // Obter URL do vídeo de vários campos possíveis
      const videoUrl = result.video_result?.[0]?.url ||
                      result.video_url ||
                      result.url ||
                      result.video;
      console.log('URL do Vídeo:', videoUrl);
      return videoUrl;
    } else {
      console.log('Tarefa falhou ou ainda está processando');
      return null;
    }
  } catch (error) {
    console.error('Geração de vídeo falhou:', error.message);
    throw error;
  }
}

// Uso
const videoUrl = await generateVideo('Um gato está brincando com uma bola.');
console.log('Vídeo gerado:', videoUrl);

Geração de Imagem para Vídeo

IMPORTANTE: O parâmetro image_url aceita tanto dados de imagem codificados em base64 quanto URLs, mas a codificação base64 é fortemente recomendada para melhor confiabilidade e para evitar problemas relacionados à rede.

Crítico: Sempre corresponda o tipo MIME no seu data URI base64 ao formato real da imagem para evitar erros de decodificação.

import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';

// Função auxiliar para detectar o tipo MIME a partir da extensão do arquivo
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'; // Padrão para JPEG se desconhecido
}

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

  // Método 1: Usando imagem codificada em base64 (RECOMENDADO)
  // Detecta automaticamente o tipo MIME a partir da extensão do arquivo
  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,  // String de dados base64 com tipo MIME correto
    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,  // String de URL
    prompt: prompt,
    quality: 'quality',
    duration: 5,
    fps: 30
  });

  return task;
}

// Exemplos de uso
const task1 = await generateVideoFromImage(
  './images/foto.jpg',  // Funciona com JPEG
  'Anime esta cena com movimento suave'
);

const task2 = await generateVideoFromImage(
  './images/grafico.png',  // Funciona com PNG
  'Adicione movimento dinâmico'
);

const task3 = await generateVideoFromImage(
  './images/animacao.webp',  // Funciona com WebP
  'Traga isto à vida'
);

Imagem para Vídeo com Quadros Inicial e Final

IMPORTANTE: Para o modo de quadros-chave, imagens codificadas em base64 são altamente recomendadas em vez de URLs para garantir geração de vídeo consistente e confiável. Sempre use o tipo MIME correto para cada imagem.

import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';

// Função auxiliar para detectar o tipo MIME a partir da extensão do arquivo
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 imagens codificadas em base64 (RECOMENDADO)
  // Detecta automaticamente o tipo MIME para cada imagem
  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 strings base64 com tipos MIME corretos
    prompt: prompt,
    quality: 'quality',
    duration: 10,
    fps: 30
  });

  console.log('Tarefa criada com quadros-chave:', 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 strings de URL
    prompt: prompt,
    quality: 'quality',
    duration: 10,
    fps: 30
  });

  console.log('Tarefa criada com quadros-chave:', task.id);
  return task;
}

// Exemplos de uso com diferentes formatos
const task1 = await generateVideoWithKeyframes(
  './quadros/inicio.jpg',  // Quadro inicial JPEG
  './quadros/fim.jpg',     // Quadro final JPEG
  'Transição suave entre estas cenas'
);

const task2 = await generateVideoWithKeyframes(
  './quadros/inicio.png',  // Quadro inicial PNG
  './quadros/fim.webp',    // Quadro final WebP - formatos diferentes funcionam!
  'Efeito de metamorfose entre imagens'
);

Gerenciamento de Resultados Assíncronos

Consultar Status da Tarefa

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('Status da Tarefa:', result.task_status);

    if (result.task_status === 'SUCCESS') {
      // Extrair URL do vídeo do resultado
      const videoUrl = result.video_result?.[0]?.url ||
                      result.video_url ||
                      result.url ||
                      result.video;
      if (videoUrl) {
        console.log('URL do Vídeo:', videoUrl);
        return { success: true, url: videoUrl };
      }
    } else if (result.task_status === 'PROCESSING') {
      console.log('Tarefa ainda está processando');
      return { success: false, status: 'processing' };
    } else if (result.task_status === 'FAIL') {
      console.log('Tarefa falhou');
      return { success: false, status: 'failed' };
    }
  } catch (error) {
    console.error('Falha ao consultar status da tarefa:', error.message);
    throw error;
  }
}

Polling Automatizado com Retry

import ZAI from 'z-ai-web-dev-sdk';

async function pollTaskResult(taskId, options = {}) {
  const {
    maxPolls = 60,
    pollInterval = 5000, // 5 segundos
    onProgress = null
  } = options;

  const zai = await ZAI.create();
  let result = await zai.async.result.query(taskId);
  let pollCount = 0;

  while (result.task_status === 'PROCESSING' && pollCount < maxPolls) {
    pollCount++;
    
    if (onProgress) {
      onProgress(pollCount, maxPolls);
    }

    // Aguardar antes do próximo polling
    await new Promise(resolve => setTimeout(resolve, pollInterval));
    result = await zai.async.result.query(taskId);
  }

  return result;
}

// Uso
const result = await pollTaskResult('task-id-123', {
  maxPolls: 120,  // 10 minutos máximo
  pollInterval: 5000,
  onProgress: (current, total) => {
    console.log(`Progresso do Polling: ${current}/${total}`);
  }
});

if (result.task_status === 'SUCCESS') {
  const videoUrl = result.video_result?.[0]?.url || result.video_url || result.url;
  console.log('Vídeo gerado:', videoUrl);
} else {
  console.log('Tarefa não foi concluída com sucesso');
}

Parâmetros de Geração de Vídeo

Parâmetros do SDK (zai.video.generations.create)

ParâmetroTipoObrigatórioPadrãoDescrição
promptstringNão-Descrição textual do conteúdo do vídeo
image_urlstring | string[]Não-Dados de imagem (preferencialmente codificados em base64) ou URL. Use array para dois quadros (início e fim)
qualitystringNãospeedModo de saída: speed ou quality
with_audiobooleanNãofalseGerar efeitos de áudio por IA para o vídeo
sizestringNão-Resolução do vídeo (ex.: "1920x1080")
fpsnumberNão30Taxa de quadros: 30 ou 60
durationnumberNão5Duração em segundos: 5 ou 10
modelstringNão-Nome do modelo a ser usado

Resolução de Problemas

Erros Comuns

  1. Falha de Decodificação de Imagem: Certifique-se de que o tipo MIME no seu data URI base64 corresponda ao formato real da imagem.

    • Correto: data:image/png;base64,... para imagens PNG
    • Correto: data:image/jpeg;base64,... para imagens JPEG
    • Incorreto: data:image/png;base64,... para imagem JPEG
  2. Timeout de Polling: Se o vídeo demorar mais do que o esperado, aumente maxPolls ou o pollInterval.

  3. URL da Imagem Não Acessível: Ao usar URLs, certifique-se de que eles sejam acessíveis publicamente ou estejam dentro de uma rede com as permissões corretas.

Suporte a Diferentes Formatos de Imagem

FormatoTipo MIMEStatus
JPEGimage/jpeg✅ Totalmente Suportado
PNGimage/png✅ Totalmente Suportado
WebPimage/webp✅ Totalmente Suportado
GIFimage/gif✅ Suportado
BMPimage/bmp✅ Suportado

Testes

Testes Unitários

A habilidade vem com um conjunto abrangente de testes unitários para validar a funcionalidade de geração de vídeo.

# Executar todos os testes de geração de vídeo
npm run test -- --grep "Video Generation"

# Executar testes específicos
npm run test -- --grep "Text-to-Video"
npm run test -- --grep "Image-to-Video"
npm run test -- --grep "Keyframe Generation"
npm run test -- --grep "Video Generation with Audio"

Testes de Integração

Testes de integração validam o fluxo de trabalho completo de ponta a ponta:

# Executar testes de integração
npm run test:integration -- --grep "Video Generation"

# Executar teste de amostra
npm run test -- --grep "Video Generation Sample"

Cobertura de Testes

  • Geração de texto para vídeo com parâmetros padrão
  • Geração de texto para vídeo com parâmetros personalizados (tamanho, qualidade, FPS, duração)
  • Geração de imagem para vídeo com codificação base64
  • Geração de imagem para vídeo com URLs
  • Geração de quadros-chave com duas imagens
  • Geração de vídeo com áudio
  • Tratamento de erros para prompts inválidos
  • Tratamento de erros para entradas de imagem inválidas
  • Comportamento de polling e gerenciamento de status de tarefas

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.

Habilidades Relacionadas