PixVerse CLI: 개발자를 위한 AI 비디오·이미지 생성 워크플로우

소개

모든 크리에이티브 워크플로우에는 병목 구간이 있습니다. 코드 에디터를 떠나 브라우저를 열고, 웹 인터페이스를 수동으로 클릭해 미디어를 생성해야 하는 순간입니다. 개발자와 AI 에이전트, 자동화 콘텐츠 파이프라인을 구축하는 팀에게 이런 컨텍스트 전환은 빠르게 누적되는 마찰입니다.

PixVerse CLI는 이 병목을 제거합니다. PixVerse 공식 커맨드라인 인터페이스로서, PixVerse 플랫폼의 모든 모델과 기능을 터미널에서 직접 사용할 수 있습니다. 텍스트 투 비디오, 이미지 투 비디오, 텍스트 투 이미지, 립싱크 음성, 사운드 효과, 업스케일링까지 모두 스크립트화·파이프라인화할 수 있으며 브라우저를 열 필요가 없습니다.

PixVerse CLI가 특히 강력한 이유는 설계 철학에 있습니다. 처음부터 AI 에이전트를 염두에 두고 만들어졌기 때문에, 모든 명령은 구조화된 JSON을 출력하고 종료 코드는 결정론적이며 파이프라인 단계는 조합 가능하게 설계되어 있습니다. 즉, Claude Code, Cursor, Codex 등 어떤 에이전트에게도 이미지·비디오 생성을 맡기고 안정적으로 반복 실행할 수 있습니다.

이 가이드는 설치부터 첫 생성, 그리고 다단계 자동화 파이프라인과 에이전트 네이티브 워크플로우까지 전체 과정을 안내합니다.

사전 요구 사항

시작 전에 다음을 준비합니다:

• Node.js 20 이상 — node --version으로 확인합니다
• PixVerse 계정 — pixverse.ai에서 가입합니다
• 활성 PixVerse 구독 — CLI는 웹사이트와 동일한 크레딧 체계를 사용하며, 구독 사용자만 생성이 가능합니다

PixVerse CLI는 API 키를 수동으로 복사할 필요가 없습니다. 인증은 브라우저 기반 OAuth 흐름으로 처리되며 토큰은 로컬에 저장됩니다.

1단계: CLI 설치

npm으로 전역 설치합니다:

npm install -g pixverse

설치를 확인합니다:

pixverse --version

전역 설치를 원하지 않으면 npx로 실행할 수도 있습니다:

npx pixverse create video --prompt "A cat walking on Mars"

2단계: 인증

로그인 명령을 실행합니다:

pixverse auth login

CLI는 OAuth 디바이스 인증을 위해 브라우저를 엽니다. URL을 복사해 다른 기기 브라우저에서 인증을 완료할 수도 있어 SSH·헤드리스 환경에서도 유용합니다. 토큰은 ~/.pixverse/에 자동 저장되며 30일 동안 유효합니다.

로그인 상태와 사용 가능한 크레딧을 확인하려면:

pixverse auth status
pixverse account info

account info 명령은 구독 등급, 남은 크레딧, 일일 크레딧 초기화 일정을 보여줍니다. 배치 작업 전에 반드시 잔액을 확인합니다.

3단계: 첫 이미지 생성

텍스트 투 이미지 생성은 설정을 검증하는 가장 빠른 방법입니다. 다음을 실행합니다:

pixverse create image --prompt "A photorealistic forest path at golden hour" --json

--json 플래그는 구조화된 출력을 반환합니다:

{
  "image_id": 789012,
  "status": "completed",
  "image_url": "https://...",
  "prompt": "A photorealistic forest path at golden hour",
  "model": "qwen-image",
  "width": 1024,
  "height": 1024
}

더 높은 해상도가 필요하면 해당 모델을 지정합니다:

pixverse create image \
  --prompt "A photorealistic forest path at golden hour" \
  --model seedream-5.0-lite \
  --quality 1800p \
  --aspect-ratio 16:9 \
  --json

PixVerse는 해상도 한도와 강점이 다른 다양한 이미지 모델을 제공합니다:

생성한 이미지를 다운로드하려면:

pixverse asset download 789012

4단계: 첫 비디오 생성

텍스트 투 비디오도 같은 방식으로 실행됩니다. 먼저 5초 클립을 생성합니다:

pixverse create video --prompt "A sunset over ocean waves" --json

완전한 커스텀 생성은 다음과 같습니다:

pixverse create video \
  --prompt "A cinematic drone shot over a misty mountain valley at dawn" \
  --model v6 \
  --quality 1080p \
  --aspect-ratio 16:9 \
  --duration 8 \
  --audio \
  --json

--audio는 영상 내용에 맞는 AI 주변음을 활성화합니다. --json은 완료 시 video_url을 반환하므로 다운로드 명령이나 파이프라인 다음 단계로 바로 전달할 수 있습니다.

PixVerse는 서로 다른 특성을 가진 여러 비디오 모델을 제공합니다:

정적 이미지를 애니메이션으로 만들기

사진 또는 생성 이미지를 비디오로 바꾸려면 --image 플래그를 사용합니다:

pixverse create video \
  --prompt "Gentle wind moves through the scene" \
  --image ./product-photo.jpg \
  --model v6 \
  --quality 1080p \
  --json

로컬 파일 경로나 URL을 전달할 수 있습니다. 로컬 파일은 자동 업로드되므로 수동 업로드 단계가 필요 없습니다.

5단계: 인터랙티브 마법사 실행

처음 사용하는 경우, 플래그가 익숙하지 않다면 인수 없이 생성 명령을 실행해 가이드 마법사를 사용할 수 있습니다:

pixverse create video
pixverse create image

마법사는 프롬프트, 모델 선택, 품질, 화면비, 길이 등 옵션을 단계별로 안내하므로, 스크립트화 전에 파라미터를 파악하기 좋습니다.

생성 그 이상: 에셋과 워크스페이스 관리

최신 PixVerse CLI에는 엔드투엔드 터미널 워크플로우를 위한 관리 명령도 포함되어 있습니다:

• pixverse task status <id> 및 pixverse task wait <id>: 작업 폴링
• pixverse asset list|upload|info|download|delete: 에셋 라이프사이클 관리
• pixverse saved list|items|new|rename|add|remove|delete: 저장 폴더 관리
• pixverse workspace list|status|switch|manage: 멀티 워크스페이스 운영

이제 생성뿐 아니라 정리, 다운로드, 전달까지 하나의 스크립트에서 자동화할 수 있습니다.

AI 에이전트에게 미디어 생성을 가르치기

이 지점에서 PixVerse CLI의 진가가 드러납니다. 모든 명령이 구조화된 JSON과 결정론적 종료 코드를 제공하므로, 셸 명령을 실행할 수 있는 AI 에이전트라면 누구나 이미지·비디오 생성을 온디맨드로 수행하도록 학습시킬 수 있습니다.

PixVerse Skills 설치

PixVerse Skills는 CLI를 정확히 사용하도록 에이전트를 학습시키는 구조화 스킬 라이브러리입니다. 명령 플래그, 모델 제약, 다단계 파이프라인, 견고한 오류 처리 방식이 포함됩니다.

Claude Code 및 skills 형식을 지원하는 에이전트는 다음으로 PixVerse skills를 추가합니다:

npx skills add https://github.com/pixverseai/skills --skill pixverse-ai-image-and-video-generator

Cursor, Claude Code, Codex 및 기타 에이전트 프레임워크에서 이 스킬은 추측 기반 실행 대신 명시적 제약을 제공해 안정성을 높입니다.

스킬을 로드한 뒤에는 다음과 같은 자연어 지시를 줄 수 있습니다:

• “Generate a 10-second product demo video from this screenshot”
• “Create four variations of this blog cover image in 16:9 format”
• “Animate this diagram into a 5-second explainer clip with ambient sound”
• “Generate three 8-second 16:9 promo clips with different camera motions”

에이전트는 이를 올바른 CLI 명령으로 변환하고 JSON을 파싱하며 폴링과 다운로드까지 자동 처리합니다.

Claude Code

Claude Code에서 PixVerse CLI는 에이전트가 자율적으로 사용하는 네이티브 도구가 됩니다. PixVerse skills를 로드하면 어떤 작업에서도 미디어 생성을 직접 포함할 수 있습니다:

Generate a cover image for this blog post about machine learning,
use the seedream-5.0-lite model at 1800p in 16:9 format,
download it to ./assets/cover.webp

Claude Code는 적절한 CLI 명령을 호출하고, JSON 응답에서 이미지 URL을 파싱해 지정 경로로 다운로드합니다. 같은 세션에서 코드 작업과 함께 수행됩니다.

일반적인 Claude Code 워크플로우:

# Claude Code runs this autonomously based on your instruction
IMG=$(pixverse create image \
  --prompt "Abstract visualization of neural network layers, dark background, blue and purple tones" \
  --model seedream-5.0-lite \
  --quality 1800p \
  --aspect-ratio 16:9 \
  --json | jq -r '.image_url')
 
# Then animates it
pixverse create video \
  --prompt "Slow pan across glowing neural connections" \
  --image "$IMG" \
  --model v6 \
  --quality 1080p \
  --duration 6 \
  --json

Cursor

Cursor 사용자는 PixVerse Skills를 프로젝트 컨텍스트 파일로 로드할 수 있습니다. 관련 파일을 .cursor/에 두거나 워크스페이스 규칙에 추가하면, Cursor가 PixVerse CLI 명령 전체를 이해한 상태로 코딩 작업 중 미디어를 생성할 수 있습니다.

대표적인 사용 방식은, 구현 중인 디자인에 맞춘 목업 이미지를 에이전트로 생성하고 IDE 세션 내에서 즉시 참조하는 것입니다.

Codex 및 기타 에이전트

PixVerse CLI는 셸 실행과 JSON 파싱이 가능한 모든 에이전트와 호환됩니다. 일관된 필드명, 예측 가능한 오류 코드, stderr 분리 오류 메시지라는 구조 덕분에 단순한 스크립팅 에이전트도 안정적으로 통합할 수 있습니다.

종료 코드 규약은 오류 처리를 단순화합니다:

자동화 파이프라인

개별 명령을 이해하면 PixVerse CLI로 사용자 개입 없이 실행되는 강력한 다단계 워크플로우를 구성할 수 있습니다.

텍스트 → 이미지 → 비디오

가장 유용한 파이프라인 중 하나는 텍스트 프롬프트로 고해상도 이미지를 만든 뒤 비디오로 애니메이션화하는 흐름입니다.

# Step 1: Generate a base image
IMG_RESULT=$(pixverse create image \
  --prompt "A cyberpunk cityscape at night, neon lights reflecting on wet pavement" \
  --model gemini-3.1-flash \
  --quality 2160p \
  --aspect-ratio 16:9 \
  --json)
 
IMAGE_URL=$(echo "$IMG_RESULT" | jq -r '.image_url')
 
# Step 2: Animate it into a video
VID_RESULT=$(pixverse create video \
  --prompt "Camera slowly pans across the neon-lit streets" \
  --image "$IMAGE_URL" \
  --model v6 \
  --quality 1080p \
  --duration 8 \
  --json)
 
VIDEO_ID=$(echo "$VID_RESULT" | jq -r '.video_id')
 
# Step 3: Download the final video
pixverse asset download "$VIDEO_ID" --json

풀 비디오 제작 파이프라인

완성도 높은 결과물을 위해 생성 이후 후처리 단계를 연결할 수 있습니다:

# Step 1: Create the base video
RESULT=$(pixverse create video \
  --prompt "A product being assembled in slow motion" \
  --model v6 \
  --quality 720p \
  --duration 5 \
  --json)
 
VID=$(echo "$RESULT" | jq -r '.video_id')
 
# Step 2: Extend duration
EXTENDED=$(pixverse create extend \
  --video "$VID" \
  --prompt "Continue the assembly sequence" \
  --duration 5 \
  --json | jq -r '.video_id')
 
pixverse task wait "$EXTENDED" --json
 
# Step 3: Add ambient sound
WITH_SOUND=$(pixverse create sound \
  --video "$EXTENDED" \
  --prompt "Industrial workshop ambience, soft mechanical sounds" \
  --json | jq -r '.video_id')
 
pixverse task wait "$WITH_SOUND" --json
 
# Step 4: Upscale to 1080p
FINAL=$(pixverse create upscale \
  --video "$WITH_SOUND" \
  --quality 1080p \
  --json | jq -r '.video_id')
 
pixverse task wait "$FINAL" --json
 
# Step 5: Download
pixverse asset download "$FINAL" --json

배치 생성

여러 변형이 필요한 콘텐츠 파이프라인은 병렬 실행이 효율적입니다:

# Check credits first
CREDITS=$(pixverse account info --json | jq -r '.credits.total')
echo "Available credits: $CREDITS"
 
# Submit four parallel generations
pixverse create video --prompt "Sunrise over mountains" --no-wait --json > /tmp/v1.json &
pixverse create video --prompt "Sunset over ocean" --no-wait --json > /tmp/v2.json &
pixverse create video --prompt "Stars over a desert" --no-wait --json > /tmp/v3.json &
pixverse create video --prompt "Aurora over a frozen lake" --no-wait --json > /tmp/v4.json &
wait
 
# Wait for each and download
for f in /tmp/v1.json /tmp/v2.json /tmp/v3.json /tmp/v4.json; do
  ID=$(jq -r '.video_id' "$f")
  pixverse task wait "$ID" --json
  pixverse asset download "$ID" --json
done

--no-wait는 작업 제출 후 즉시 task ID를 반환하므로, 여러 작업을 먼저 넣고 나중에 폴링할 수 있습니다. pixverse task wait가 적응형 폴링을 처리하므로 수동 sleep 루프가 필요 없습니다.

기본값 구성

동일한 모델·품질·화면비를 반복 사용한다면 기본값으로 설정해 플래그 반복 입력을 줄일 수 있습니다:

pixverse config defaults set video model v6
pixverse config defaults set video quality 1080p
pixverse config defaults set image model seedream-5.0-lite
pixverse config set output-dir ~/Downloads/pixverse
pixverse config defaults show

커맨드라인 플래그는 항상 기본값보다 우선하므로, 반복을 줄이면서도 유연성을 유지할 수 있습니다.

무엇을 만들 수 있나요

PixVerse CLI를 에이전트 워크플로우에 통합하면 자동화 가능한 업무 범위가 크게 확장됩니다:

• 문서화 — 문서 빌드 과정에서 제품 데모 비디오와 스크린샷 자동 생성
• 마케팅 — 단일 프롬프트 라이브러리로 SNS 콘텐츠 변형을 야간 배치로 생성
• 앱 개발 — UI를 개발하는 동안 에이전트가 플레이스홀더 비주얼, 목업 애니메이션, 로딩 화면 비디오를 생성
• 콘텐츠 파이프라인 — CLI 호출을 ffmpeg, ImageMagick, 클라우드 스토리지와 연결해 완전 자동 미디어 제작 흐름 구축
• 프로토타이핑 — 본 제작 전에 수초 내 모션 콘셉트를 생성해 아이디어를 빠르게 검증

CLI는 셸 기반 워크플로우에 자연스럽게 맞도록 설계되었습니다. 기존 자동화가 bash, Python, Node, CI/CD 중 어디에서 실행되든 추가 통합 부담 없이 적용할 수 있습니다.

시작 체크리스트

• Node.js 20 이상 설치
• npm install -g pixverse 실행
• pixverse auth login 실행 후 브라우저 승인
• pixverse account info 실행으로 크레딧 확인
• 첫 이미지 생성: pixverse create image --prompt "..." --json
• 첫 비디오 생성: pixverse create video --prompt "..." --json
• 에이전트용 PixVerse Skills 설치(Claude Code, Cursor, Codex)
• pixverse config defaults set으로 기본값 구성
• 첫 자동화 파이프라인 구축

CLI를 최신 상태로 유지하기

npm으로 로컬 CLI를 업데이트합니다:

npm update -g pixverse

릴리스 단위 변경 사항과 신규 지원 모델은 공식 changelog를 확인합니다:

• PixVerse CLI Changelog

다음 단계

npm의 PixVerse CLI(npm install -g pixverse)를 사용하면 생성, 작업 폴링, 에셋 관리, 저장 폴더, 워크스페이스 제어를 하나의 인터페이스에서 즉시 사용할 수 있습니다. PixVerse Skills 저장소를 함께 적용하면 Claude Code, Cursor, Codex 등 다양한 도구에서 이 워크플로우를 더 안정적으로 실행할 수 있습니다.

신뢰할 수 있는 CLI와 에이전트 친화적 스킬 라이브러리를 결합하면 이미지·비디오 생성을 코드 작업과 같은 흐름 안에 둘 수 있습니다. 같은 에이전트가 같은 터미널에서 처리하므로 도구 전환이 필요 없습니다.

하나의 명령으로 시작하고, 거기서부터 확장하면 됩니다.