비디오 생성 스킬
이 스킬은 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
사용자 정의 품질 및 설정
# 품질 모드 (속도 또는 품질)
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 <텍스트>: 선택사항 - 비디오에 대한 텍스트 설명--image-url, -i <데이터>: 선택사항 - 가급적 base64로 인코딩된 이미지 데이터 (예: "data:image/png;base64,iVBORw..."). URL도 지원되지만 덜 권장됩니다. 두 개의 이미지에는 쉼표로 구분된 값을 사용하세요.--quality, -q <모드>: 선택사항 - 출력 모드:speed또는quality(기본값: speed)--with-audio: 선택사항 - AI 오디오 효과 생성 (기본값: false)--size, -s <해상도>: 선택사항 - 비디오 해상도 (예: "1920x1080")--fps <속도>: 선택사항 - 프레임 속도: 30 또는 60 (기본값: 30)--duration, -d <초>: 선택사항 - 지속 시간: 5초 또는 10초 (기본값: 5)--model, -m <모델>: 선택사항 - 사용할 모델 이름--poll: 선택사항 - 작업이 완료될 때까지 자동 폴링--poll-interval <초>: 선택사항 - 폴링 간격 (기본값: 5)--max-polls <횟수>: 선택사항 - 최대 폴링 시도 횟수 (기본값: 60)--output, -o <경로>: 선택사항 - 출력 파일 경로 (JSON 형식)
지원되는 해상도
1024x1024768x1344864x11521344x7681152x8641440x720720x14401920x1080(및 기타 표준 해상도)
나중에 작업 상태 확인
--poll 없이 작업을 생성한 경우, 나중에 상태를 확인할 수 있습니다:
# 초기 응답에서 작업 ID 가져오기
z-ai async-result --id "task-id-here" --poll
CLI와 SDK 사용 시기
CLI 사용 시기:
- 빠른 비디오 생성 테스트
- 간단한 일회성 비디오 생성
- 명령줄 자동화 스크립트
- 다양한 프롬프트 및 설정 테스트
SDK 사용 시기:
- 사용자 정의 로직이 포함된 배치 비디오 생성
- 웹 애플리케이션과의 통합
- 사용자 정의 작업 큐 관리
- 복잡한 워크플로우가 있는 프로덕션 애플리케이션
비디오 생성 워크플로우
비디오 생성은 2단계 비동기 패턴을 따릅니다:
- 작업 생성: 비디오 생성 요청을 제출하고 작업 ID를 받습니다.
- 결과 폴링: 작업 상태를 완료될 때까지 조회하고 비디오 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;
}
}
미리보기 이미지 URL 가져오기
비디오 생성이 완료되면 일반적으로 비디오 자체와 함께 미리보기 이미지 URL을 받게 됩니다:
if (result.task_status === 'SUCCESS') {
// 비디오 URL (기본값: 빈 문자열)
const videoUrl = result.video_result?.[0]?.url || '';
// 미리보기 이미지 URL (기본값: 빈 문자열)
const previewImageUrl = result.video_result?.[0]?.cover_image_url || '';
// 사용 가능한 경우 썸네일 URL
const thumbnailUrl = result.video_result?.[0]?.thumbnail_url || '';
console.log('비디오 URL:', videoUrl);
console.log('미리보기 이미지 URL:', previewImageUrl);
}
사용자 정의 폴링 유틸리티
프로덕션 애플리케이션의 경우 재사용 가능한 폴링 유틸리티를 만드는 것을 고려하세요:
import ZAI from 'z-ai-web-dev-sdk';
async function waitForVideoCompletion(taskId, options = {}) {
const {
maxPolls = 60,
pollInterval = 5000, // 5초
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);
}
await new Promise(resolve => setTimeout(resolve, pollInterval));
result = await zai.async.result.query(taskId);
}
return {
success: result.task_status === 'SUCCESS',
status: result.task_status,
videoUrl: result.video_result?.[0]?.url || null,
previewImageUrl: result.video_result?.[0]?.cover_image_url || null,
data: result
};
}
// 사용 예시
const videoResult = await waitForVideoCompletion(taskId, {
maxPolls: 30,
pollInterval: 10000, // 10초
onProgress: (current, total) => {
console.log(`진행: ${current}/${total} 폴링`);
}
});
if (videoResult.success) {
console.log('비디오 URL:', videoResult.videoUrl);
}
API 세부 사항
zai.video.generations.create(params)
비디오 생성을 위한 새 작업을 생성합니다.
매개변수:
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
prompt | string | 아니요 | 생성할 비디오에 대한 텍스트 설명 |
image_url | string | string[] | 아니요 | 가급적 base64 데이터 문자열(예: "data:image/png;base64,...") 또는 단일 이미지용 URL. 여러 이미지의 경우 배열. 자세한 내용은 CLI 이미지-비디오 섹션 참조 |
quality | string | 아니요 | 출력 품질 모드: "speed" 또는 "quality". 기본값: "speed" |
with_audio | boolean | 아니요 | AI 오디오 효과 생성. 기본값: false |
size | string | 아니요 | 비디오 해상도 (예: "1920x1080") |
fps | number | 아니요 | 프레임 속도: 30 또는 60. 기본값: 30 |
duration | number | 아니요 | 지속 시간(초): 5 또는 10. 기본값: 5 |
model | string | 아니요 | 사용할 모델 이름 |
응답:
id: 작업 식별자task_status: 초기 상태 ("PENDING"또는"PROCESSING")
zai.async.result.query(taskId)
비디오 생성 작업의 상태와 결과를 조회합니다.
매개변수:
taskId(string, 필수): 비디오 생성 API에서 받은 작업 ID
응답:
task_status:"PENDING","PROCESSING","SUCCESS"또는"FAIL"video_result[].url: 생성된 비디오의 URL (완료 시)video_result[].cover_image_url: 미리보기 이미지 URL (사용 가능한 경우)- 추가 결과 데이터
오류 처리
일반적인 오류 시나리오
async function generateVideoWithRetry(prompt, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await generateVideo(prompt);
} catch (error) {
console.log(`시도 ${attempt}/${maxRetries} 실패: ${error.message}`);
if (attempt === maxRetries) {
throw new Error(`최대 재시도 횟수 ${maxRetries}회 초과. 마지막 오류: ${error.message}`);
}
// 지수 백오프를 통한 재시도 전 대기
await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt)));
}
}
}
오류 유형
- 인증 오류: API 키가 올바르게 구성되었는지 확인하세요.
- 유효성 검사 오류: 매개변수 값(예: 유효한 크기, fps, 지속 시간)을 확인하세요.
- 속도 제한: API 호출 사이에 적절한 지연을 구현하세요.
- 시간 초과: 폴링이 완료되기 전에 작업이 시간 초과되는 경우
maxPolls및pollInterval을 조정하세요.
모범 사례
- 이미지에 base64 사용: URL보다 더 안정적입니다.
- 올바른 MIME 유형 확인: 데이터 URI를 구성할 때 항상 이미지 형식과 일치하는지 확인하세요.
- 폴링 간격 구현: API 부하를 줄이기 위해 폴링 사이에 최소 5초를 기다리세요.
- 적절한 시간 초과: 프로덕션 사용을 위한 충분한 폴링 횟수를 설정하세요.
- 사용자 정의 가능한 품질: 품질과 속도 요구 사항에 맞게 품질 모드를 조정하세요.
- 출력 저장: 실패 시 재처리를 위해 작업 결과를 로컬에 저장하는 것을 고려하세요.
- 진행률 모니터링: 장기 실행 작업의 진행 상황을 추적하는 메커니즘을 구현하세요.