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:speedouquality(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
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(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:
- Criar Tarefa: Envie a solicitação de geração de vídeo e receba um ID de tarefa
- 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âmetro | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
prompt | string | Não | - | Descrição textual do conteúdo do vídeo |
image_url | string | string[] | Não | - | Dados de imagem (preferencialmente codificados em base64) ou URL. Use array para dois quadros (início e fim) |
quality | string | Não | speed | Modo de saída: speed ou quality |
with_audio | boolean | Não | false | Gerar efeitos de áudio por IA para o vídeo |
size | string | Não | - | Resolução do vídeo (ex.: "1920x1080") |
fps | number | Não | 30 | Taxa de quadros: 30 ou 60 |
duration | number | Não | 5 | Duração em segundos: 5 ou 10 |
model | string | Não | - | Nome do modelo a ser usado |
Resolução de Problemas
Erros Comuns
-
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
- Correto:
-
Timeout de Polling: Se o vídeo demorar mais do que o esperado, aumente
maxPollsou opollInterval. -
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
| Formato | Tipo MIME | Status |
|---|---|---|
| JPEG | image/jpeg | ✅ Totalmente Suportado |
| PNG | image/png | ✅ Totalmente Suportado |
| WebP | image/webp | ✅ Totalmente Suportado |
| GIF | image/gif | ✅ Suportado |
| BMP | image/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