Communitygithub.com

ARYAN2302/liquid_researcher

z-ai-web-dev-sdk를 사용한 AI 기반 비디오 생성 기능을 구현합니다. 사용자가 텍스트 프롬프트나 이미지로 비디오를 생성하거나, 프로그래매틱 방식으로 비디오 콘텐츠를 만들거나, 비디오 출력을 생성하는 애플리케이션을 구축해야 할 때 사용하세요. 비동기 작업 관리(상태 폴링 및 결과 검색)를 지원합니다.

liquid_researcher란 무엇인가요?

이 스킬은 z-ai-web-dev-sdk 패키지를 활용하여 AI 기반 비디오 생성 기능을 구현하는 방법을 설명합니다. 텍스트 설명이나 이미지로부터 비디오를 생성하고, 해상도, 프레임 속도, 지속 시간 및 품질 설정과 같은 매개변수를 사용자 정의할 수 있습니다. CLI와 SDK 방식 모두를 지원하여 간단한 일회성 작업이나 복잡한 프로덕션 워크플로우에 유연하게 대응할 수 있습니다. 비동기 작업 모델을 사용하여 작업을 생성한 후, 상태를 폴링하여 완료 시 비디오 URL을 검색합니다. base64 인코딩된 이미지 데이터를 지원하여 네트워크 문제 없는 안정적인 이미지-비디오 변환을 제공하며, 시작 및 종료 프레임을 지정하여 키프레임 기반 비디오 생성도 가능합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ARYAN2302/liquid_researcher/tree/HEAD/skills/video-generation

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

비디오 생성 스킬

이 스킬은 z-ai-web-dev-sdk 패키지를 사용하여 AI 모델이 텍스트 설명이나 이미지로부터 비동기 작업 처리를 통해 비디오를 생성할 수 있도록 하는 기능을 구현합니다.

스킬 경로

스킬 위치: {project_path}/skills/video-generation

이 스킬은 프로젝트에서 위 경로에 위치합니다.

참고 스크립트: 빠른 테스트와 참조를 위해 예제 테스트 스크립트가 {Skill Location}/scripts/ 디렉토리에 제공됩니다. 작동 예제는 {Skill Location}/scripts/video.ts에서 확인하세요.

개요

비디오 생성 기능을 사용하면 텍스트 프롬프트나 이미지로부터 비디오 콘텐츠를 생성하는 애플리케이션을 구축할 수 있으며, 해상도, 프레임 속도, 지속 시간 및 품질 설정과 같은 사용자 정의 가능한 매개변수를 제공합니다. API는 비동기 작업 모델을 사용하여 작업을 생성하고 결과를 폴링합니다.

중요: z-ai-web-dev-sdk는 반드시 백엔드 코드에서만 사용해야 합니다. 클라이언트 측 코드에서는 절대 사용하지 마세요.

전제 조건

z-ai-web-dev-sdk 패키지는 이미 설치되어 있습니다. 아래 예제와 같이 가져와서 사용하세요.

CLI 사용법 (간단한 작업용)

간단한 비디오 생성 작업의 경우, 코드를 작성하는 대신 z-ai CLI를 사용할 수 있습니다. CLI는 작업 생성 및 폴링을 자동으로 처리하므로, 빠른 테스트와 간단한 자동화에 적합합니다.

기본 텍스트-비디오 변환

# 자동 폴링으로 비디오 생성
z-ai video --prompt "공놀이하는 고양이" --poll

# 짧은 옵션 사용
z-ai video -p "산이 있는 아름다운 풍경" --poll

사용자 정의 품질 및 설정

# 품질 모드 (speed 또는 quality)
z-ai video -p "석양의 바다 파도" --quality quality --poll

# 사용자 정의 해상도 및 FPS
z-ai video \
  -p "도시 타임랩스" \
  --size "1920x1080" \
  --fps 60 \
  --poll

# 사용자 정의 지속 시간 (5초 또는 10초)
z-ai video -p "불꽃놀이" --duration 10 --poll

이미지-비디오 변환

중요: image_url 매개변수에는 URL 대신 base64로 인코딩된 이미지 데이터를 사용하는 것이 강력히 권장됩니다. 이 방법이 더 안정적이며 잠재적인 네트워크 문제나 접근 제한을 피할 수 있습니다.

참고: 데이터 URI의 MIME 유형을 실제 이미지 형식(image/jpeg, image/png, image/webp 등)과 일치시켜 디코딩 문제를 방지하세요.

# base64를 사용하여 단일 이미지에서 비디오 생성 (권장됨)
# 올바른 MIME 유형으로 이미지를 base64로 변환

# PNG 이미지의 경우
IMAGE_BASE64=$(base64 -i image.png)
z-ai video \
  --image-url "data:image/png;base64,${IMAGE_BASE64}" \
  --prompt "장면을 생생하게 만들어 줘" \
  --poll

# JPEG 이미지의 경우
IMAGE_BASE64=$(base64 -i photo.jpg)
z-ai video \
  --image-url "data:image/jpeg;base64,${IMAGE_BASE64}" \
  --prompt "장면을 생생하게 만들어 줘" \
  --poll

# WebP 이미지의 경우
IMAGE_BASE64=$(base64 -i image.webp)
z-ai video \
  --image-url "data:image/webp;base64,${IMAGE_BASE64}" \
  --prompt "장면을 생생하게 만들어 줘" \
  --poll

# URL 사용 (덜 권장됨, 안정성 문제가 있을 수 있음)
z-ai video \
  -i "https://example.com/photo.jpg" \
  -p "이 장면에 움직임 추가" \
  --poll

시작-종료 프레임 모드

중요: 최상의 안정성을 위해 URL 대신 base64로 인코딩된 이미지를 사용하세요. MIME 유형이 실제 이미지 형식과 일치하는지 확인하세요.

# base64를 사용하여 두 프레임 사이의 비디오 생성 (권장됨)
# 각 이미지에 올바른 MIME 유형을 사용해야 함

# 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 "프레임 간 부드러운 전환" \
  --poll

# 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 "프레임 간 부드러운 전환" \
  --poll

# URL 사용 (덜 권장됨)
z-ai video \
  --image-url "https://example.com/start.png,https://example.com/end.png" \
  --prompt "프레임 간 부드러운 전환" \
  --poll

오디오 생성과 함께 사용

# AI 생성 오디오 효과와 함께 비디오 생성
z-ai video \
  -p "다가오는 뇌우" \
  --with-audio \
  --poll

출력 저장

# 작업 결과를 JSON 파일로 저장
z-ai video \
  -p "산 위의 일출" \
  --poll \
  -o video_result.json

사용자 정의 폴링 매개변수

# 폴링 동작 사용자 정의
z-ai video \
  -p "춤추는 로봇" \
  --poll \
  --poll-interval 10 \
  --max-polls 30

# 폴링 없이 작업 생성 (작업 ID 획득)
z-ai video -p "추상 미술 애니메이션" -o task.json

CLI 매개변수

  • --prompt, -p <text>: 선택 사항 - 비디오에 대한 텍스트 설명
  • --image-url, -i <data>: 선택 사항 - 가급적 base64로 인코딩된 이미지 데이터 (예: "data:image/png;base64,iVBORw..."). URL도 지원되지만 권장되지 않음. 두 이미지의 경우 쉼표로 구분된 값을 사용.
  • --quality, -q <mode>: 선택 사항 - 출력 모드: speed 또는 quality (기본값: speed)
  • --with-audio: 선택 사항 - AI 오디오 효과 생성 (기본값: false)
  • --size, -s <resolution>: 선택 사항 - 비디오 해상도 (예: "1920x1080")
  • --fps <rate>: 선택 사항 - 프레임 속도: 30 또는 60 (기본값: 30)
  • --duration, -d <seconds>: 선택 사항 - 지속 시간: 5초 또는 10초 (기본값: 5)
  • --model, -m <model>: 선택 사항 - 사용할 모델 이름
  • --poll: 선택 사항 - 작업이 완료될 때까지 자동 폴링
  • --poll-interval <seconds>: 선택 사항 - 폴링 간격 (기본값: 5)
  • --max-polls <count>: 선택 사항 - 최대 폴링 시도 횟수 (기본값: 60)
  • --output, -o <path>: 선택 사항 - 출력 파일 경로 (JSON 형식)

지원되는 해상도

  • 1024x1024
  • 768x1344
  • 864x1152
  • 1344x768
  • 1152x864
  • 1440x720
  • 720x1440
  • 1920x1080 (및 기타 표준 해상도)

나중에 작업 상태 확인

--poll 없이 작업을 생성한 경우, 나중에 상태를 확인할 수 있습니다:

# 초기 응답에서 작업 ID 가져오기
z-ai async-result --id "task-id-here" --poll

CLI와 SDK 사용 시기

CLI 사용 시기:

  • 빠른 비디오 생성 테스트
  • 간단한 일회성 비디오 생성
  • 명령줄 자동화 스크립트
  • 다양한 프롬프트 및 설정 테스트

SDK 사용 시기:

  • 사용자 정의 로직을 사용한 배치 비디오 생성
  • 웹 애플리케이션과의 통합
  • 사용자 정의 작업 큐 관리
  • 복잡한 워크플로우가 있는 프로덕션 애플리케이션

비디오 생성 워크플로우

비디오 생성은 두 단계의 비동기 패턴을 따릅니다:

  1. 작업 생성: 비디오 생성 요청을 제출하고 작업 ID를 받습니다.
  2. 결과 폴링: 작업 상태를 완료될 때까지 쿼리하고 비디오 URL을 검색합니다.

기본 비디오 생성 구현

간단한 텍스트-비디오 생성

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

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

    // 비디오 생성 작업 생성
    const task = await zai.video.generations.create({
      prompt: prompt,
      quality: 'speed', // 'speed' 또는 'quality'
      with_audio: false,
      size: '1920x1080',
      fps: 30,
      duration: 5
    });

    console.log('작업 ID:', task.id);
    console.log('작업 상태:', task.task_status);

    // 결과 폴링
    let result = await zai.async.result.query(task.id);
    let pollCount = 0;
    const maxPolls = 60;
    const pollInterval = 5000; // 5초

    while (result.task_status === 'PROCESSING' && pollCount < maxPolls) {
      pollCount++;
      console.log(`폴링 ${pollCount}/${maxPolls}: 상태는 ${result.task_status}`);
      await new Promise(resolve => setTimeout(resolve, pollInterval));
      result = await zai.async.result.query(task.id);
    }

    if (result.task_status === 'SUCCESS') {
      // 여러 가능한 필드에서 비디오 URL 가져오기
      const videoUrl = result.video_result?.[0]?.url ||
                      result.video_url ||
                      result.url ||
                      result.video;
      console.log('비디오 URL:', videoUrl);
      return videoUrl;
    } else {
      console.log('작업 실패 또는 아직 처리 중');
      return null;
    }
  } catch (error) {
    console.error('비디오 생성 실패:', error.message);
    throw error;
  }
}

// 사용법
const videoUrl = await generateVideo('공놀이하는 고양이.');
console.log('생성된 비디오:', videoUrl);

이미지-비디오 생성

중요: image_url 매개변수는 base64로 인코딩된 이미지 데이터와 URL을 모두 허용하지만, 더 나은 안정성과 네트워크 관련 문제 방지를 위해 base64 인코딩을 강력히 권장합니다.

중요: base64 데이터 URI의 MIME 유형을 실제 이미지 형식과 항상 일치시켜 디코딩 오류를 방지하세요.

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

// 파일 확장자에서 MIME 유형을 감지하는 도우미 함수
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'; // 알 수 없는 경우 JPEG 기본값
}

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

  // 방법 1: base64로 인코딩된 이미지 사용 (권장됨)
  // 파일 확장자에서 MIME 유형 자동 감지
  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,  // 올바른 MIME 유형의 Base64 데이터 문자열
    prompt: prompt,
    quality: 'quality',
    duration: 5,
    fps: 30
  });

  return task;
}

// 방법 2: URL 사용 (덜 권장됨)
async function generateVideoFromImageUrl(imageUrl, prompt) {
  const zai = await ZAI.create();

  const task = await zai.video.generations.create({
    image_url: imageUrl,  // URL 문자열
    prompt: prompt,
    quality: 'quality',
    duration: 5,
    fps: 30
  });

  return task;
}

// 사용 예제
const task1 = await generateVideoFromImage(
  './images/photo.jpg',  // JPEG에서 작동
  '부드러운 움직임으로 이 장면을 애니메이션화'
);

const task2 = await generateVideoFromImage(
  './images/graphic.png',  // PNG에서 작동
  '역동적인 움직임 추가'
);

const task3 = await generateVideoFromImage(
  './images/animation.webp',  // WebP에서 작동
  '이것을 생생하게 만들기'
);

시작 및 종료 프레임을 사용한 이미지-비디오 생성

중요: 키프레임 모드의 경우, 일관되고 안정적인 비디오 생성을 위해 URL보다 base64로 인코딩된 이미지를 강력히 권장합니다. 각 이미지에 대해 올바른 MIME 유형을 항상 사용하세요.

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

// 파일 확장자에서 MIME 유형을 감지하는 도우미 함수
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();

  // 방법 1: base64로 인코딩된 이미지 사용 (권장됨)
  // 각 이미지의 MIME 유형 자동 감지
  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],  // 올바른 MIME 유형의 Base64 문자열 배열
    prompt: prompt,
    quality: 'quality',
    duration: 10,
    fps: 30
  });

  console.log('키프레임으로 작업 생성됨:', task.id);
  return task;
}

// 방법 2: URL 사용 (덜 권장됨)
async function generateVideoWithKeyframesUrl(startImageUrl, endImageUrl, prompt) {
  const zai = await ZAI.create();

  const task = await zai.video.generations.create({
    image_url: [startImageUrl, endImageUrl],  // URL 문자열 배열
    prompt: prompt,
    quality: 'quality',
    duration: 10,
    fps: 30
  });

  console.log('키프레임으로 작업 생성됨:', task.id);
  return task;
}

// 다양한 형식의 사용 예제
const task1 = await generateVideoWithKeyframes(
  './frames/start.jpg',  // JPEG 시작 프레임
  './frames/end.jpg',    // JPEG 종료 프레임
  '이 장면들 사이의 부드러운 전환'
);

const task2 = await generateVideoWithKeyframes(
  './frames/start.png',  // PNG 시작 프레임
  './frames/end.webp',   // WebP 종료 프레임 - 다른 형식도 작동!
  '이미지 간 모핑 효과'
);

비동기 결과 관리

작업 상태 쿼리

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('작업 상태:', result.task_status);

    if (result.task_status === 'SUCCESS') {
      // 결과에서 비디오 URL 추출
      const videoUrl = result.video_result?.[0]?.url ||
                      result.video_url ||
                      result.url ||
                      result.video;
      if (videoUrl) {
        console.log('비디오 URL:', videoUrl);
        return { success: true, url: videoUrl };
      }
    } else if (result.task_status === 'PROCESSING') {
      console.log('작업이 아직 처리 중입니다');
      return { success: false, status: 'processing' };
    } else if (result.task_status === 'FAIL') {
      console.log('작업 실패');
      return { success: false, status: 'failed' };
    }
  } catch (error) {
    console.error('작업 상태 확인 실패:', error.message);
    throw error;
  }
}

// 사용 예제
const status = await checkTaskStatus('your-task-id-here');
if (status.success) {
  console.log('비디오 URL:', status.url);
}

완전한 폴링 구현

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

async function pollForResult(taskId, maxPolls = 60, interval = 5000) {
  const zai = await ZAI.create();
  
  let result = await zai.async.result.query(taskId);
  let pollCount = 0;

  while (result.task_status === 'PROCESSING' && pollCount < maxPolls) {
    pollCount++;
    console.log(`폴링 ${pollCount}/${maxPolls}...`);
    await new Promise(resolve => setTimeout(resolve, interval));
    result = await zai.async.result.query(taskId);
  }

  return result;
}

// 사용 예제
const finalResult = await pollForResult(taskId, 30, 10000);

오류 처리

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

async function safeVideoGeneration(config) {
  try {
    const zai = await ZAI.create();
    
    const task = await zai.video.generations.create({
      prompt: config.prompt,
      image_url: config.imageUrl,
      quality: config.quality || 'speed',
      with_audio: config.withAudio || false,
      size: config.size || '1920x1080',
      fps: config.fps || 30,
      duration: config.duration || 5
    });

    // 비동기 완료 처리
    const result = await pollForResult(task.id);
    
    if (result.task_status === 'SUCCESS') {
      return result;
    } else if (result.task_status === 'FAIL') {
      throw new Error(`생성 실패: ${JSON.stringify(result)}`);
    }
  } catch (error) {
    if (error.message.includes('timeout')) {
      console.error('요청 시간 초과');
    } else if (error.message.includes('rate_limit')) {
      console.error('속도 제한 도달');
    }
    throw error;
  }
}

비디오 생성 모범 사례

  1. 비동기 처리: 비동기 작업에 대해 항상 적절한 폴링 또는 콜백 메커니즘을 구현하세요.
  2. 이미지 처리: 안정성을 위해 URL보다 base64 인코딩을 선호하세요. 올바른 MIME 유형을 사용해야 합니다.
  3. 프롬프트 최적화: 더 나은 결과를 위해 명확하고 설명적인 프롬프트를 사용하세요.
  4. 리소스 관리: 비용 최적화를 위해 적절한 해상도와 지속 시간을 선택하세요.
  5. 오류 처리: 네트워크 문제, 시간 초과 및 속도 제한을 처리하는 포괄적인 오류 처리를 구현하세요.
  6. 품질 대 속도: speed와 quality 모드 중에서 필요에 따라 선택하세요.
  7. 오디오: with_audio 옵션을 사용하여 관련 오디오를 생성하여 비디오 경험을 향상시키세요.

일반적인 문제 해결

  1. 작업이 오래 걸림: 최대 폴링 제한을 확인하고 필요한 경우 늘리세요.
  2. 이미지 디코딩 오류: 정확한 MIME 유형의 유효한 base64 데이터를 확인하세요.
  3. 비디오 품질 문제: quality 모드 사용을 시도하고 프롬프트 설명을 개선하세요.
  4. 속도 제한: 요청 사이에 지연을 구현하고 속도 제한을 존중하세요.

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.

관련 스킬